Skip to main content
Start with:
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:
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 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 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 and 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 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. 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. 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

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