> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artil.dev/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, and agent channels. Text mode also checks message delivery setup. |
| `artil auth login` | `--url`, `--account`, `--token` | Sign in through a browser or save a supplied token. |
| `artil auth logout` | None | Remove the saved login and MCP entries installed by the CLI. |

See [authentication](/authentication).

## Use the terminal menu

To browse your inbox without typing each command, run:

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

Choose **Email** or **SMS** to read, reply, or compose a message. **Secrets**
stores credentials and links them to a client. **Set up this machine** connects
Claude Code or Hermes. **Status** shows your login and channel setup.

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 or SMS 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 [--name <machine>] [--agent <agent>] [--client <client>]
```

| Flag | Values and purpose |
| - | - |
| `--client` | `claude-code`, `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` | Machine label; defaults to its hostname. Renaming preserves its identity. |

Without an interactive terminal, pass `--client` to make a selection. Otherwise
`init` prints the available connections without connecting one. See
[automatic delivery](/automatic-messages). For the Claude Code plugin or Pi
extension, follow their [installation guides](/setup); `init` does not install them.

`--client none` removes local delivery setup and the selected agent's remote
Hermes webhook, including a webhook configured on another computer. See
[disconnect message delivery](/automatic-messages#change-or-disconnect-a-client)
before running it.

## Email and SMS

Personal SMS is in beta. Email
[founders@firaresearch.com](mailto:founders@firaresearch.com) to request access
before using the SMS commands.

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

The default list limit is 25; accepted values are 1 to 25. Use a listed message ID
with `read` or `--reply-to`. See [email](/email) and [Personal SMS (beta)](/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.

## 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`, `--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 and refresh local links. |
| `artil secrets copy <name>` | `--agent` | Copy the value to the clipboard. |
| `artil secrets link <place>` | `--agent`, `--force` | Link `claude-code`, `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` | `--agent` | Refresh the agent's links on this machine. |

See [secrets](/secrets).

## Updates

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

This updates a standalone installation. If you installed through a package
manager, use that package manager to update. 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 and SMS commands put message data inside `result`. 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. In text mode, errors appear on stderr.
In JSON mode, message errors can appear on stdout and may have a different
structure from successful results. Check the exit status before reading `result`.
Unknown flags return an error.

## Configuration

| Variable | Purpose |
| - | - |
| `ARTIL_BASE_URL` | Artil server URL used for login; overridden by `--url`. |
| `ARTIL_TOKEN` | Token to use during login instead of browser authentication; overridden by `--token`. |
| `ARTIL_CONFIG_HOME` | Directory for the CLI's local configuration and login. |
| `XDG_CONFIG_HOME` | When no explicit config directory is set, configuration goes in its `artil` subdirectory. |
| `ARTIL_NO_AUTOUPDATE` | Set to `1` to disable background update checks. |
| `ARTIL_RELEASES_URL` | Override the release source used by standalone installation and updates. |

The default configuration directory is `~/.config/artil`. `credentials.json`
holds the login; `config.json` holds machine and OAuth registration state;
`secrets.json` records local secret links.

## Older command names

Older aliases and internal commands still work for existing client setups.
Use the commands above for new scripts. `tools`, `mcp`, and `sync` are hidden
from help, and sync must also be enabled on the Artil server.


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