> ## 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.

# Troubleshooting

> Fix sign-in, email, SMS, client setup, and secret-loading problems.

Start with:

```bash theme={null}
artil --version
artil auth status
```

Status shows your agent account, workspace, channels, and message delivery setup,
including the agent's webhooks.

## The shell cannot find artil

Check that `~/.local/bin` is on PATH. For the current terminal:

```bash theme={null}
export PATH="$HOME/.local/bin:$PATH"
artil --version
```

If your shell finds an older installation, follow the installer's instructions
to switch to the new one. See [installation](/installation).

## Login does not return to the terminal

Open the login link in a browser on the same computer as the CLI. On a remote
server, use [token login](/authentication#use-a-headless-machine).

If a token is rejected, create another token or run `artil auth login` again.

## The wrong agent is shown

Run `artil auth login` and select the agent you want in the browser, then
restart the client session. The plugins use that saved login. If you also
configured automatic delivery with `artil init`, run it again to review the
connection and linked secrets. The CLI keeps one login at a time.

## Email or SMS is unavailable

Run `artil auth status` to check which agent you are using. Open its
**Manage** link and finish any email or SMS setup shown there. When the agent
has no address for a channel, the error links to the page where you add one.

Under an `--account` login, email and SMS commands fail with "This needs a
login as one agent account." Sign in as the agent with `artil auth login`.

An empty list means the command found no incoming messages. A channel that
is unavailable returns an error.

## Sending to a Message URL says no one is listening

`artil url send` and the agent's [Message URL](/url) reach an agent only while a
client listens to it; `artil team` says which agents someone listens to. Start
the agent's client, such as a Claude Code session with the Artil channel, or
add a [webhook](/webhooks), then try again.

## A send failed or its outcome is unknown

Read the error before retrying. Artil refuses a send past a
[limit](/commands#limits), such as the plan's monthly allowance, the agent's
hourly one, or too many recipients.

A successful send confirms submission to the messaging service. Open the
agent's email address or phone number in Artil to see the conversation and
reported send failures. For confirmation of delivery, check with the
recipient. If the outcome is unknown, do that before sending again to avoid a
duplicate.

## Plugin skills or tools are missing

For Claude Code, run `/plugin` and check that `artil@artil` is installed and
enabled. If it is missing, run `artil plugin install claude-code`. Check for
`/artil:email`, `/artil:sms`, and `/artil:secrets`.

For Pi, check `pi list` and start a new session after installing the package.
If it is missing, run `artil plugin install pi`. Check for `/skill:artil`.

For Codex, check that `codex plugin list` shows `artil@artil` as installed and
enabled, and start a new session after installing it. If it is missing, run
`artil plugin install codex`. See the [Claude Code](/claude-code), [Pi](/pi),
and [Codex](/codex) installation guides.

All require `artil` on PATH and an agent login. Check `artil auth status`
in the same terminal used to launch the client.

## Claude Code does not receive automatic notifications

Claude Code hears about new messages only in a session started with a
channel: the plugin's, from `artil plugin install claude-code`, or the one
[automatic delivery](/automatic-messages) sets up with `artil init`. If `/mcp`
shows the `artil-messages` server as failed, check that `artil` is on the PATH
Claude Code starts with and that `artil auth status` shows the agent's login.

If you already configured delivery, check Claude Code's startup warnings.
Channels require Anthropic authentication and are unavailable through Bedrock,
Google Cloud's Agent Platform, or Microsoft Foundry. Team and Enterprise owners
must enable channels; Console organizations with managed settings must set
`channelsEnabled: true`.
The development flag cannot override disabled channels. See
[Claude's channel requirements](https://code.claude.com/docs/en/channels#enterprise-controls).

Once channels are available, run setup again:

```bash theme={null}
artil init --client claude-code
```

Start Claude Code with the command printed by setup, including its channel
flag. Keep that session open to receive notifications.

Check that the channel is active. A message that is in the inbox but did not
wake the agent shows why under "Did not wake the agents": spam, its sender, or
a limit. See [Who can wake the agent](/wake-access) to let the sender through.

When another session or client takes over the agent's new messages, Claude is
told which one and hears nothing more; start a new session with the channel to
take them back. See [Who hears about new messages](/delivery).

## Pi does not receive automatic notifications

Run `artil init --client pi` again and complete its **Next steps**. Then start
Pi, or run `/reload` in an open session. Only interactive and RPC sessions
receive messages; `pi -p` runs do not. When delivery stops, Pi shows the
reason, such as a missing agent login. A notification can also be refused; see
[Who can wake the agent](/wake-access).

## Hermes does not run

For local delivery, Hermes must be installed and configured, and the machine
must stay online. Background delivery needs a working macOS login session or
Linux systemd user service. Inspect the log path printed by `init`. When
another client takes over the agent's new messages, the log says which one and
delivery waits; run `artil init --client hermes` again to take them back.

With the plugin from `artil plugin install hermes`, the Hermes gateway must
run; restart it after installing with `hermes gateway restart`, and check that
`hermes status` lists Artil as configured. The gateway's log says why it stops
hearing about messages, such as a missing agent login. When it says the gateway
cannot run artil, the CLI belongs to another user, such as root in a Docker
container: install it and sign in as the user the gateway runs as; see
[Hermes](/hermes).

For server delivery, finish the webhook configuration printed by `init` and
check that the server is reachable at the configured URL.

## A secret is stored but not available in the client

```bash theme={null}
artil secrets list
artil secrets pull
```

Check the linked destinations and any reported conflicts. Link the client or
file that needs the secret. After its first link, start a new Claude Code
session or run `/reload` in Pi, and restart programs that load their
environment only at startup.

The CLI keeps existing `.env` assignments outside the section it writes. If
a conflicting name was left out, resolve that assignment and pull again. If
a file is rejected because Git could commit it, add it to `.gitignore` before
linking it.

## Setting a secret with --json reports a missing value

`artil secrets set NAME --json` never opens a hidden prompt. Supply the value
or pipe it from the command that produced it. For a value you want to type,
run `artil secrets set NAME` without `--json`.

## A flag is rejected

Use the installed command's help:

```bash theme={null}
artil email send --help
artil secrets link --help
```

Flags are specific to commands. For example, SMS does not take `--subject`,
and `init` does not take `--json`. See the [command reference](/commands).


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