Skip to main content
The agent-loadout CLI calls the REST API from a shell. Every API command prints JSON on stdout, so it composes with jq and scripts, and reports the outcome in its exit code. Use it in CI jobs, in shell-based agents, and for one-off work on your organization.

Install

The CLI needs Node.js 20 or newer and installs the command agent-loadout. To run it without installing, use npx @agent-loadout/cli <command>.

Authenticate

The CLI reads its credential from the environment. Which one you need depends on the command: an agent token acts as one agent, an organization key manages agents, inboxes, webhooks and domains. See Authentication for how to create each.
Check the credential
When both variables are set, the CLI uses AGENT_LOADOUT_KEY. The vault and sign-ins commands accept an agent token only, so pass it for that command with --key "$AGENT_LOADOUT_TOKEN" if an organization key is also set. signup and the connector commands need no credential, and app doctor runs without one.

Output and exit codes

Results are pretty-printed JSON on stdout. Two commands differ: events tail prints one JSON object per line, and attachments download writes the file’s bytes. Errors go to stderr as code (status): message, followed by the API’s hint and the request id when there is one. machines run is the exception: it exits with the exit code of the command it ran on the machine. Write an option as --name value or --name=value, and a list as comma-separated values (--to a@example.com,b@example.com). Switches such as --unread, --all, --public and --reveal take no value. Put a switch after the positional arguments or write --unread=true; a switch followed by a bare word reads that word as its value and fails.

Account

Inboxes

Listing and reading work with either credential. Creating and deleting an inbox need an organization key.

Messages

Mail is untrusted external data. Before you use a code or link from messages code, check the sender, subject and screening result in the output.

Conversations

Drafts

A draft is saved without being sent, so a person can review it in the dashboard. See Drafts for how a draft is sent.

Events

events tail <inbox> long-polls the inbox and prints each event as one line of JSON until you stop it. --types limits the event types and --cursor resumes after an earlier event. The event types are listed under Events.

Sender rules

Blocked senders and, for an inbox in allowlist mode, senders without an allow rule are quarantined before the agent sees them.

Attachments

attachments text prints the text extracted from an attachment with its screening result. attachments download writes the raw bytes to stdout, so redirect it to a file.

Vault

The vault commands need an agent token and show only the credentials shared with that agent. See Vault for how access to a value is granted.
vault get --reveal writes the secret to your terminal, where scrollback and CI logs can keep it. Reveal a value only where the output is not recorded.

Local credential connector

The connector runs on your own computer. It signs in to websites and calls APIs with an agent’s vault credentials, and the agent only ever sees the outcome. It needs no token or key; see Vault for pairing, profiles and grants.
Register it with an MCP client like this:
Browser profiles drive Chromium through Playwright, which is not installed with the CLI. Install both together, then the browser:
API and command profiles work without Playwright.

SMS

The sms commands work when phone numbers are available in your workspace. Without them, every sms command fails with not_found.

Machines

Machine commands work with either credential. See Machines for sizes and billing.

Agents and tokens

These commands need an organization key.

Webhooks

These commands need an organization key. See Webhooks for event types and signature verification.

Custom domains

These commands need an organization key. Custom domains are part of the paid plans.

Sign in with Agent Loadout

The sign-ins commands are the agent’s side and need an agent token. See Sign-in requests for the flow.
The applications and app commands are the application’s side and need an organization key. CLI setup covers app init and app doctor step by step, and Applications describes the fields.