> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agent-loadout.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Loadout CLI: Install, Authenticate and Run Commands

> Install the agent-loadout CLI, authenticate with an agent token or an organization key, and run mail, vault, SMS, machine and webhook commands from a shell.

The `agent-loadout` CLI calls the [REST API](https://docs.agent-loadout.com/api-reference/overview.md) 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

```bash theme={null}
npm install -g @agent-loadout/cli
```

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](https://docs.agent-loadout.com/api-reference/authentication.md) for how to create each.

| Variable | Value | Used for |
| - | - | - |
| `AGENT_LOADOUT_TOKEN` | Agent token (`alt_…`) | Mail, drafts, vault, SMS, machines and sign-ins of one agent |
| `AGENT_LOADOUT_KEY` | Organization key (`alk_…`) | Agents, tokens, inboxes, webhooks, domains and sign-in applications |

```bash title="Check the credential" theme={null}
export AGENT_LOADOUT_TOKEN=alt_…
agent-loadout me
```

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.

| Option | Description |
| - | - |
| `--key <credential>` | Use this token or key for one command instead of the environment. |
| `--base-url <url>` | API origin. Defaults to `AGENT_LOADOUT_URL`, then `https://agent-loadout.com`. |
| `--help` | Print the list of commands. |

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

| Exit code | Meaning |
| - | - |
| `0` | The command succeeded. |
| `1` | The API returned an error, or `app doctor` found a problem. |
| `2` | Usage error: unknown command, missing argument, or no credential. |
| `3` | Nothing matched: `messages wait`, `messages code` or `sms wait` ran out of time. |

`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

```bash theme={null}
agent-loadout signup --owner-email you@example.com --agent-name "Support agent" --username support
agent-loadout me
```

| Command | What it does |
| - | - |
| `signup --owner-email <email>` | Creates a pending Free Sandbox workspace with one agent, its inbox and an agent token, and mails a claim link to the owner. The workspace receives mail at once; sending unlocks when the owner claims it, and an unclaimed workspace is deleted after 7 days. Optional: `--workspace`, `--agent-name`, `--username`. |
| `me` | Shows the agent behind an agent token, or the organization and capabilities behind a key. |

## Inboxes

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

```bash theme={null}
agent-loadout inboxes list --agent agt_…
agent-loadout inboxes create support --display-name "Support" --metadata tenant=acme
agent-loadout inboxes get inb_…
agent-loadout inboxes delete inb_…
```

| Command | Options and behavior |
| - | - |
| `inboxes list` | `--agent <id>` and `--metadata key=value` narrow the list for an organization key. |
| `inboxes create <username>` | `--agent <id>` picks the owning agent; without it an agent named after the username is created. `--domain` selects one of your verified domains, `--display-name` and `--metadata key=value` label the inbox, `--allowlist` quarantines every sender without an allow rule, and `--idempotency-key` makes a retry safe. |
| `inboxes get <inbox>` | Reads one inbox. |
| `inboxes delete <inbox>` | Deletes the inbox and its mail permanently, without a confirmation prompt. |

## Messages

```bash theme={null}
agent-loadout messages list inb_… --direction inbound --limit 20
agent-loadout messages get msg_…
agent-loadout messages send inb_… --to person@example.com --subject "Report" --text "Done." --idempotency-key report-1
agent-loadout messages reply msg_… --text "Thanks, received." --all
agent-loadout messages wait inb_… --from shop.example --timeout 120
agent-loadout messages code inb_… --from shop.example --wait 25
```

| Command | Options and behavior |
| - | - |
| `messages list <inbox>` | `--direction inbound` or `outbound`, `--since <ISO time>`, `--limit`, `--cursor`. |
| `messages get <message>` | Reads one message with its body and attachments. |
| `messages send <inbox>` | Needs `--to` and `--subject`. The body comes from `--text`, `--text-file <path>` or `--html-file <path>`. Optional: `--cc`, `--bcc`, `--reply-to`, `--label`, `--idempotency-key`. |
| `messages reply <message>` | `--text` is the reply, `--all` answers every recipient, `--idempotency-key` makes a retry safe. |
| `messages wait <inbox>` | Checks recent mail, then waits up to `--timeout` seconds (default 120) for a message that matches `--from` and `--subject`. Prints the message, or `{"matched": false}` with exit code 3. `--since` sets where the search starts. |
| `messages code <inbox>` | Finds a verification code or link in recent mail and waits up to `--wait` seconds (default 20, maximum 25). Exits with 3 when nothing is found. Filters: `--from`, `--subject`, `--since`. |

> [!WARNING]
>
> 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

```bash theme={null}
agent-loadout threads list inb_… --folder inbox --unread
agent-loadout threads get thr_…
agent-loadout threads archive thr_…
agent-loadout threads trash thr_…
agent-loadout threads read thr_…
agent-loadout threads unread thr_…
agent-loadout threads label thr_… --add billing,urgent
```

| Command | Options and behavior |
| - | - |
| `threads list <inbox>` | `--folder` is `inbox`, `sent`, `archive`, `trash` or `spam`. `--query` searches subjects, senders, bodies and attachment text, `--label` filters by label, and `--unread` keeps conversations the agent has not marked read. Paging: `--limit`, `--cursor`. |
| `threads get <thread>` | Reads the messages of a conversation. |
| `threads archive <thread>`, `threads trash <thread>` | Move the conversation to Archive or Trash. |
| `threads read <thread>`, `threads unread <thread>` | Set the agent's own read state. Members keep theirs in the dashboard. |
| `threads label <thread>` | `--add` and `--remove` change labels, `--set` replaces them all. |

## Drafts

A draft is saved without being sent, so a person can review it in the dashboard. See [Drafts](https://docs.agent-loadout.com/api-reference/email/drafts.md) for how a draft is sent.

```bash theme={null}
agent-loadout drafts list inb_…
agent-loadout drafts save inb_… --to customer@example.com --subject "Re: Your question" --text-file reply.txt
agent-loadout drafts delete drf_…
```

| Command | Options and behavior |
| - | - |
| `drafts list <inbox>` | Paging: `--limit`, `--cursor`. |
| `drafts save <inbox>` | Creates a draft from `--to`, `--cc`, `--bcc`, `--subject` and a body in `--text`, `--text-file <path>` or `--html-file <path>`. With `--id <draft>` it replaces that draft, and fields you leave out become empty. Add `--expected-updated-at <ISO time>` with the draft's `updated_at` as you last read it to have the save refused if someone changed the draft since. |
| `drafts delete <draft>` | Deletes a draft permanently. |

## Events

```bash theme={null}
agent-loadout events tail inb_… --types message.received | jq -r .data.message_id
```

`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](https://docs.agent-loadout.com/api-reference/email/events.md).

## Sender rules

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

```bash theme={null}
agent-loadout rules list inb_…
agent-loadout rules add inb_… allow @example.com --note "Customer domain"
agent-loadout rules remove <RULE_ID>
```

| Command | Options and behavior |
| - | - |
| `rules list <inbox>` | Lists the allow and block rules of an inbox. |
| `rules add <inbox> <kind> <pattern>` | The kind is `allow` or `block`. The pattern is a full address such as `person@example.com` or a domain such as `@example.com`. `--note` adds a comment. |
| `rules remove <rule>` | Removes a rule by the id that `rules list` shows. |

## Attachments

```bash theme={null}
agent-loadout attachments text att_…
agent-loadout attachments download att_… > invoice.pdf
```

`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](https://docs.agent-loadout.com/concepts/vault.md) for how access to a value is granted.

```bash theme={null}
agent-loadout vault list
agent-loadout vault get vlt_… --reveal
agent-loadout vault totp vlt_…
```

| Command | Options and behavior |
| - | - |
| `vault list` | Lists credential metadata, never values. Paging: `--limit`, `--cursor`. |
| `vault get <credential>` | Prints the metadata of one credential. With `--reveal` it prints the username, secret and notes, and the read is recorded in the audit log. |
| `vault totp <credential>` | Prints the current authenticator code and the seconds it stays valid. |

> [!WARNING]
>
> `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](https://docs.agent-loadout.com/concepts/vault.md) for pairing, profiles and grants.

```bash theme={null}
agent-loadout connector pair --url https://agent-loadout.com --name "My computer"
agent-loadout connector serve
```

| Command | Options and behavior |
| - | - |
| `connector pair` | Prints a code to approve on the dashboard's Vault page and saves the device configuration with mode 0600. Options: `--url`, `--name`, `--config PATH` (default `~/.config/agent-loadout/connector.json`). |
| `connector serve` | Starts the stdio MCP server an MCP client on the same computer connects to. Option: `--config PATH`. |

Register it with an MCP client like this:

```bash theme={null}
claude mcp add loadout-vault -- npx -y @agent-loadout/cli connector serve
```

Browser profiles drive Chromium through Playwright, which is not installed with the CLI. Install both together, then the browser:

```bash theme={null}
npm install -g @agent-loadout/cli playwright
npx playwright install chromium
```

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

```bash theme={null}
agent-loadout sms numbers
agent-loadout sms list phn_… --direction inbound --limit 20
agent-loadout sms send phn_… --to +14155552671 --text "Your order has shipped."
agent-loadout sms wait phn_… --contains code --timeout 120
```

| Command | Options and behavior |
| - | - |
| `sms numbers` | Lists phone numbers. `--agent <id>` narrows the list for an organization key. |
| `sms list <number>` | Texts sent and received on a number, newest first. `--direction inbound` or `outbound`, `--since <ISO time>`, `--limit`, `--cursor`. |
| `sms send <number>` | Needs `--to` with the recipient in E.164 format and `--text`. `--idempotency-key` makes a retry safe. |
| `sms wait <number>` | Checks recent texts, then waits up to `--timeout` seconds (default 120) for one that matches `--from` and `--contains`. Prints the text with any verification code found in it, or `{"matched": false}` with exit code 3. `--since` sets where the search starts. |

## Machines

Machine commands work with either credential. See [Machines](https://docs.agent-loadout.com/concepts/machines.md) for sizes and billing.

```bash theme={null}
agent-loadout machines list
agent-loadout machines create --size small --ttl 1200 --name ci-fix
agent-loadout machines get mch_…
agent-loadout machines run mch_… --command "cd app && bun test" --timeout 600
agent-loadout machines host mch_… 8080 --title "Preview"
agent-loadout machines stop mch_…
agent-loadout machines resume mch_… --ttl 1800
agent-loadout machines delete mch_…
```

| Command | Options and behavior |
| - | - |
| `machines list` | `--agent <id>` narrows the list for an organization key. |
| `machines create` | `--size` is `small`, `default` or `large`. `--ttl <seconds>` sets the auto-stop window (default 3600). `--env KEY=value,KEY2=value` sets environment variables, `--inject vlt_…,vlt_…` injects vault credentials as environment variables, and `--token email:read,email:send` places an agent token with those capabilities in `AGENT_LOADOUT_TOKEN` on the machine. An organization key needs `--agent <id>`. Optional: `--name`, `--idempotency-key`. |
| `machines get <machine>` | Reads the machine. Poll it after `create` or `resume` until `state` is `ready`. |
| `machines run <machine>` | Runs `--command` and waits up to `--timeout` seconds (default 60, maximum 600). `--cwd` sets the working directory. The CLI exits with the command's exit code. |
| `machines host <machine> <port>` | Returns a public HTTPS URL for a service on that port. The URL carries an access token unless you pass `--public`. `--title` labels it. |
| `machines stop <machine>` | Snapshots the disk and stops billing. |
| `machines resume <machine>` | Starts a stopped machine again. `--ttl <seconds>` sets a new auto-stop window. |
| `machines delete <machine>` | Deletes the machine and its snapshots permanently, without a confirmation prompt. |

## Agents and tokens

These commands need an organization key.

```bash theme={null}
agent-loadout agents list
agent-loadout agents create "Support agent" --metadata tenant=acme
agent-loadout agents token agt_… --name ci --capabilities email:read,email:send --expires-in-days 30
```

| Command | Options and behavior |
| - | - |
| `agents list` | Lists the agents of the organization. |
| `agents create <name>` | `--description` and `--metadata key=value` describe the agent. |
| `agents token <agent>` | Issues an agent token named `--name`. `--capabilities` defaults to `email:read,email:send`, and `--expires-in-days` sets an expiry of 1 to 365 days. The token is printed once. |

## Webhooks

These commands need an organization key. See [Webhooks](https://docs.agent-loadout.com/api-reference/webhooks.md) for event types and signature verification.

```bash theme={null}
agent-loadout webhooks list
agent-loadout webhooks create https://example.com/hooks/agent-loadout --events message.received
agent-loadout webhooks test whk_…
agent-loadout webhooks deliveries whk_… --limit 20
agent-loadout webhooks redeliver whk_… --since 2026-11-01T00:00:00Z
agent-loadout webhooks delete whk_…
```

| Command | Options and behavior |
| - | - |
| `webhooks list` | Lists the endpoints of the organization. |
| `webhooks create <url>` | `--events` limits the event types, `--inbox <id>` limits the endpoint to one inbox, `--description` labels it. The signing secret is printed once. |
| `webhooks test <webhook>` | Queues a test delivery. |
| `webhooks deliveries <webhook>` | Prints the delivery log, newest first. `--limit` takes 1 to 200. |
| `webhooks redeliver <webhook>` | Queues the deliveries the endpoint missed since `--since <ISO time>` again. `--statuses` narrows them to `failed`, `dead` or `skipped`. |
| `webhooks delete <webhook>` | Deletes the endpoint. |

## Custom domains

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

```bash theme={null}
agent-loadout domains list
agent-loadout domains add agents.example.com
agent-loadout domains check cdm_…
agent-loadout domains remove cdm_…
```

| Command | Options and behavior |
| - | - |
| `domains list` | Lists the managed domain and your custom subdomains with their DNS records and verification state. |
| `domains add <subdomain>` | Adds a subdomain you control and prints the DNS records to create. |
| `domains check <domain>` | Runs the verification pass now and prints the refreshed record states. |
| `domains remove <domain>` | Removes a custom domain. |

## Sign in with Agent Loadout

The `sign-ins` commands are the agent's side and need an agent token. See [Sign-in requests](https://docs.agent-loadout.com/api-reference/identity/sign-ins.md) for the flow.

```bash theme={null}
agent-loadout sign-ins get alsi_…
agent-loadout sign-ins approve alsi_…
agent-loadout sign-ins deny alsi_…
agent-loadout sign-ins connect alap_… --scope openid,email
agent-loadout sign-ins apps
agent-loadout sign-ins keys
agent-loadout sign-ins revoke-key alsk_…
```

| Command | Options and behavior |
| - | - |
| `sign-ins get <sign-in>` | Reads a pending request: the application, the scopes and what the agent would share. |
| `sign-ins approve <sign-in>`, `sign-ins deny <sign-in>` | Sign the agent in at the application, or decline the request. |
| `sign-ins connect [client_id]` | Starts a sign-in from the agent's side and prints a connect link and the application's login start. `--scope` lists the scopes to grant (default `openid,email,profile`). Without a client id the link only enrols a browser. |
| `sign-ins apps` | Lists the applications that accept the sign-in. |
| `sign-ins keys` | Lists the agent's sign-in keys. |
| `sign-ins revoke-key <key>` | Revokes a sign-in key. |

The `applications` and `app` commands are the application's side and need an organization key. [CLI setup](https://docs.agent-loadout.com/api-reference/identity/cli.md) covers `app init` and `app doctor` step by step, and [Applications](https://docs.agent-loadout.com/api-reference/identity/applications.md) describes the fields.

```bash theme={null}
agent-loadout applications list
agent-loadout applications create "Acme Billing" --redirect-uris https://billing.acme.example/callback
agent-loadout applications get alap_…
agent-loadout applications update alap_… --listed true --description "Invoices for agents" --website https://acme.example
agent-loadout applications rotate-secret alap_…
agent-loadout applications history alap_… --limit 20
agent-loadout applications delete alap_…
agent-loadout app init
agent-loadout app doctor
```

| Command | Options and behavior |
| - | - |
| `applications list` | Lists the applications your organization registered. |
| `applications create <name>` | Needs `--redirect-uris`. Optional: `--website`, `--logo`, `--description`, `--listed`, `--login-url`, `--max-signups`. The client secret is printed once. |
| `applications get <application>` | Reads one application. |
| `applications update <application>` | Changes `--name`, `--redirect-uris`, `--website`, `--logo`, `--description` and `--listed true` or `false`. `--login-url none` and `--max-signups none` clear those values. |
| `applications rotate-secret <application>` | Replaces the client secret. The old one stops working at once. |
| `applications history <application>` | Prints recent sign-ins at the application. `--limit` sets how many. |
| `applications delete <application>` | Deletes the application. |
| `app init` | Registers the project in the current directory as an application and writes the client values to `.env.local`. |
| `app doctor` | Checks the project's setup and exits with 1 when a check fails. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.