Skip to main content
Start with:
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:
If your shell finds an older installation, follow the installer’s instructions to switch to the new one. See 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. 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 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, then try again.

​
A send failed or its outcome is unknown

Read the error before retrying. Artil refuses a send past a limit, 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, Pi, and 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 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. Once channels are available, run setup again:
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 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.

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

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

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:
Flags are specific to commands. For example, SMS does not take --subject, and init does not take --json. See the command reference.