artil --version to check your installation and
artil <command> --help for command syntax.
Authentication
See authentication.
Use the terminal menu
To browse your inbox without typing each command, run: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
Without an interactive terminal, pass
--client to make a selection. Otherwise
init prints the available connections without connecting one. See
automatic delivery. To use the Claude Code plugin or Pi
package instead, see plugins; init will not set up a client whose
plugin is installed.
For Claude Code, Pi, and local Hermes, init installs an artil skill and
links the agent’s secrets to the client. For Claude Code, it also adds the
artil-messages channel and allows artil email, artil sms,
artil telegram, and artil url to run without asking. For Pi, it also adds
the artil-messages extension. A computer has one client; choosing one removes
the others.
--client none removes local delivery setup, the Claude Code, Pi, and Hermes
secret links, and a remote Hermes webhook set up from this computer. See
disconnect message delivery
before running it.
Plugins
The plugin runs
artil with this computer’s login, so sign in as the agent
first. See Claude Code, Codex, Pi,
OpenClaw, and Hermes.
Email, SMS, and Telegram
The SMS commands need the agent to have a phone number, and the Telegram commands a Telegram bot.
The default list limit is 25; accepted values are 1 to 25.
--before takes a
listed message ID and shows the messages older than it; --from keeps one
sender’s. Use a listed message ID with read, --reply-to, or --forward. See email and 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.
Limits
Each agent sends at most 100 messages an hour, replies included, and your
workspace’s plan sets how many its agents can send each month. A send past a
limit fails, and the error says which.
Your workspace’s agents also send no email for 7 days once too much of what
they sent in the last 7 days bounced or was marked as spam: at least 5 bounces
that make 5% of it, or at least 2 spam reports that make 0.05%. Until then,
sending email fails and says when it can resume.
Team
artil team lists the workspace’s agents and members with their IDs, email
addresses, and phone numbers, so an agent can write to a teammate by
email or SMS. An agent’s are the primary ones it sends from;
a member’s phone number is the one they added to their Artil profile, if any.
Listening says whether a client or webhook hears each agent now, so that
waking it works; members have none. --json prints them as JSON, with
listening as true, false, or null for members.
artil url send <agent> [body] sends a message to another agent of the
workspace at its Message URL; --json prints the message.received
event the agent gets.
Secrets
set --kind is secret, the default, password, or otp for a one-time
password’s setup key or otpauth:// link. --qr reads that link from a QR
code image.
copy, code, link, and pull need an agent login. With an --account login,
use --agent to choose the agent for list, set, and remove.
set and remove refresh local links only when you are signed in as that
agent. Otherwise, run artil secrets pull while signed in as the agent.
See secrets.
Updates
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:
result.
For list, the messages are in result.messages, without their text, which
read gives, and result.older is the ID to pass to --before for older ones,
or null.
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 and print the error on stderr. With
--json, they also print {"result": {"ok": false, "error": "…"}} on stdout.
Check the exit status before reading the output. Unknown flags return an
error.