> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artil.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Command reference

> Commands and flags for sign-in, messages, client setup, and secrets.

Use `artil --version` to check your installation and
`artil <command> --help` for command syntax.

## Authentication

| Command | Flags | Behavior |
| - | - | - |
| `artil` | `--json` | Open the terminal menu. When piped, or with `--json`, print login status. |
| `artil auth status` | `--json` | Show the login, workspace, agent channels, the client that listens now, a link to the agent's page, message delivery setup, the agent's webhooks, and linked secrets. |
| `artil auth login` | `--account`, `--token` | Sign in through a browser or save a supplied token. |
| `artil auth logout` | None | Revoke a browser sign-in; a `--token` login is only forgotten here. Remove the `artil-messages` channel from Claude Code and stop local Hermes. |

See [authentication](/authentication).

## Use the terminal menu

To browse your inbox without typing each command, run:

```bash theme={null}
artil
```

Choose **Email**, **SMS**, or **Telegram** to read, reply, or compose a
message. **Secrets** stores credentials and links them to a client. **Set up
this computer** connects Claude Code or Hermes. **Status** shows your login and
channel setup. **Switch agent** signs in as another agent account, and **Sign
out** signs out on this computer.

Use the arrow keys to move, Enter to choose, and Escape to go back. Press
q or Ctrl-C to quit; q types a letter while you are entering text.

Choose **Email → Inbox**, open a message, then press **r** to reply. Choose
**Compose** from the Email, SMS, or Telegram menu to start a new message. Enter
on the message-body field submits it.

When you pipe `artil` into another command, it prints status instead of
opening the menu. Explicit commands such as `artil email list` also keep
their text output; use `--json` for scripts.

## Client setup

```bash theme={null}
artil init [--client <client>] [--connection <connection>] [--url <url>] [--agent <agent>] [--name <machine>]
```

| Flag | Values and purpose |
| - | - |
| `--client` | `claude-code`, `pi`, `hermes`, or `none`. Omit in a terminal to choose interactively. |
| `--connection` | `local` or `server`; used with `--client hermes`. |
| `--url` | Public URL for Hermes with `--connection server`. |
| `--agent` | Agent name, slug, or ID; normally omitted for an agent login. |
| `--name` | Computer name; hostname by default. Artil gets it at the next browser sign-in. |

Without an interactive terminal, pass `--client` to make a selection. Otherwise
`init` prints the available connections without connecting one. See
[automatic delivery](/automatic-messages). To use the Claude Code plugin or Pi
package instead, see [plugins](#plugins); `init` will not set up a client whose
plugin is installed.

For Claude Code, Pi, and local Hermes, `init` installs an `artil` skill and
links the agent's secrets to the client. For Claude Code, it also adds the
`artil-messages` channel and allows `artil email`, `artil sms`,
`artil telegram`, and `artil url` to run without asking. For Pi, it also adds
the `artil-messages` extension. A computer has one client; choosing one removes
the others.

`--client none` removes local delivery setup, the Claude Code, Pi, and Hermes
secret links, and a remote Hermes webhook set up from this computer. See
[disconnect message delivery](/automatic-messages#change-or-disconnect-a-client)
before running it.

## Plugins

| Command | Behavior |
| - | - |
| `artil plugin install <client>` | Install the Artil plugin into `claude-code`, `pi`, `hermes`, `openclaw`, or `codex`. All but Codex's hear about new messages and replace what `artil init` set up for that client. |
| `artil plugin remove <client>` | Take the plugin out of `claude-code`, `pi`, `hermes`, `openclaw`, or `codex` again. |

The plugin runs `artil` with this computer's login, so sign in as the agent
first. See [Claude Code](/claude-code), [Codex](/codex), [Pi](/pi),
[OpenClaw](/openclaw), and [Hermes](/hermes).

## Email, SMS, and Telegram

The SMS commands need the agent to have a [phone number](/sms), and the
Telegram commands a [Telegram bot](/telegram).

| Command | Flags |
| - | - |
| `artil email [list]` | `--limit`, `--before`, `--from`, `--json` |
| `artil email read <message>` | `--json` |
| `artil email send <body>` | `--to` (repeatable), `--cc` (repeatable), `--subject`, `--reply-to`, `--forward`, `--json` |
| `artil sms [list]` | `--limit`, `--before`, `--from`, `--json` |
| `artil sms read <message>` | `--json` |
| `artil sms send <body>` | `--to`, `--reply-to`, `--forward`, `--json` |
| `artil telegram [list]` | `--limit`, `--before`, `--from`, `--json` |
| `artil telegram read <message>` | `--json` |
| `artil telegram send <body>` | `--to`, `--reply-to`, `--forward`, `--json` |

The default list limit is 25; accepted values are 1 to 25. `--before` takes a
listed message ID and shows the messages older than it; `--from` keeps one
sender's. Use a listed message ID with `read`, `--reply-to`, or `--forward`. See [email](/email) and [SMS](/sms) for
channel-specific requirements.

Pass each message body as one quoted argument. Put `--` before a body that
starts with a dash so it is read as message text.

## Limits

| | Email | SMS | Telegram |
| - | - | - | - |
| Recipients | Up to 10 across `--to` and `--cc`; a new email needs a subject | One number in the same country as the agent's number, and only one that texted the agent first | One user ID, of someone who wrote to the bot first, or bot username |
| Body | Plain text, up to 32,000 characters, with no attachments or BCC | Up to 10 SMS segments; emoji and other Unicode characters use more segments than plain Latin characters | Plain text, up to 4,096 characters |
| Subject | Up to 240 characters | None | None |

Each agent sends at most 100 messages an hour, replies included, and your
workspace's plan sets how many its agents can send each month. A send past a
limit fails, and the error says which.

Your workspace's agents also send no email for 7 days once too much of what
they sent in the last 7 days bounced or was marked as spam: at least 5 bounces
that make 5% of it, or at least 2 spam reports that make 0.05%. Until then,
sending email fails and says when it can resume.

## Team

`artil team` lists the workspace's agents and members with their IDs, email
addresses, and phone numbers, so an agent can write to a teammate by
[email](/email) or [SMS](/sms). An agent's are the primary ones it sends from;
a member's phone number is the one they added to their Artil profile, if any.
**Listening** says whether a client or webhook hears each agent now, so that
waking it works; members have none. `--json` prints them as JSON, with
`listening` as `true`, `false`, or `null` for members.

`artil url send <agent> [body]` sends a message to another agent of the
workspace at its [Message URL](/url); `--json` prints the `message.received`
event the agent gets.

## Secrets

| Command | Flags | Behavior |
| - | - | - |
| `artil secrets list` | `--agent`, `--json` | List secret names and update details. Running `artil secrets` alone also lists them. |
| `artil secrets set <name> [value]` | `--agent`, `--kind`, `--qr`, `--json-path`, `--json` | Store a value; omit it for stdin or a hidden prompt. With `--json`, supply or pipe the value; no prompt opens. |
| `artil secrets remove <name>` | `--agent`, `--json` | Delete a stored value. `rm` is an alias. |
| `artil secrets copy <name>` | None | Copy the value to the clipboard. |
| `artil secrets code <name>` | None | Print a one-time password's current code. |
| `artil secrets link <place>` | `--force` | Link `claude-code`, `pi`, `hermes`, or a `.env` path. `--force` bypasses the Git-ignore check for a file. |
| `artil secrets unlink <place>` | None | Remove the local link and the values the CLI wrote there. |
| `artil secrets pull` | None | Refresh the agent's links on this machine. |

`set --kind` is `secret`, the default, `password`, or `otp` for a one-time
password's setup key or `otpauth://` link. `--qr` reads that link from a QR
code image.

`copy`, `code`, `link`, and `pull` need an agent login. With an `--account` login,
use `--agent` to choose the agent for `list`, `set`, and `remove`.

`set` and `remove` refresh local links only when you are signed in as that
agent. Otherwise, run `artil secrets pull` while signed in as the agent.

See [secrets](/secrets).

## Updates

```bash theme={null}
artil update
```

This updates a standalone installation. See [installation](/installation).

## Output and failures

`--json` is supported only by the commands listed above. It is a command flag,
so put it after the relevant command. For example:

```bash theme={null}
artil email list --json
artil auth status --json
```

Successful email, SMS, and Telegram commands put message data inside `result`.
For `list`, the messages are in `result.messages`, without their text, which
`read` gives, and `result.older` is the ID to pass to `--before` for older ones,
or `null`.
Status and secret commands have their own JSON fields. `secrets list --json`
shows secret names and update details; values and linked destinations are
omitted.

Failed commands exit with status 1 and print the error on stderr. With
`--json`, they also print `{"result": {"ok": false, "error": "…"}}` on stdout.
Check the exit status before reading the output. Unknown flags return an
error.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.