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

# 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, workspace, channels, and message delivery setup,
including any remote Hermes webhook.

## 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 in the same Artil server or run
`artil auth login` again. After changing `ARTIL_BASE_URL`, sign in again to
save the new server address.

## 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 setup link
and finish any email or SMS setup shown there.

Artil grants permission to list, read, and send messages when it sets up an
agent's first channel. If the CLI reports missing access, follow any
access-request instructions in the error and wait for approval. If no request
is offered, ask your Artil administrator to investigate; include the command
and error text.

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

SMS is in beta; email
[founders@firaresearch.com](mailto:founders@firaresearch.com) to request access.
Once access is enabled, check the owner's JOIN enrollment and carrier approval.
Wait for approval before sending. After `STOP`, the enrolled phone must send
`START` to allow messages again.

## A send failed or its outcome is unknown

Read the error before retrying. 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 `/plugin marketplace add artilai/claude-plugins`
and `/plugin install artil@artil`. Check for `/artil:email` and `/artil:sms`.

For Pi, check `pi list` and start a new session after installing the package.
It provides six tools: list, read, and reply for each of email and SMS. See
the [Claude Code](/claude-code) and [Pi](/pi) installation guides.

Both 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

The plugin checks messages during a conversation. For incoming notifications,
follow [automatic delivery](/automatic-messages) to set up `artil init`.

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. Notifications are blocked for messages
marked as spam, messages from the agent itself, and senders excluded by its
settings. At most 60 incoming messages per hour can wake an agent. A message
may still appear in the inbox when its notification is blocked.

After reconnecting, Claude may show a notification for a message it has already
seen. Check the message ID before replying again. Keep one answering session
open per agent to reduce duplicate replies.

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

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. Start a new Claude Code session after its first
link, 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.