# The operator CLI

Some acts belong to whoever runs the machine rather than to whoever holds a project key. Minting the first key, claiming a fresh deployment, destroying a collection, sweeping retention, reading the outbound audit: none of them should be reachable over the network by a credential a program carries.

So they live on the command line, on the node, and the binary that serves the API is the same binary that performs them. Most of these commands open the databases directly with no server running, which means they also work when the deployment is down. Three of them address a running server instead, and this page says which.

## Where a command runs

| Reads the data directory | Addresses a running server |
|---|---|
| `apikey`, `identity`, `snapshot`, `retention`, `erase`, `egress`, `import` | `health`, `governance`, `otel` |

The first group takes `-data <dir>` and needs no server, no network, and no key. The second takes `-addr <url>` and `-key <api key>`, because what they read or write lives behind the server rather than in a file.

## Keys and the first account

```bash
automaton identity claim -data <dir> -email you@example.com

automaton apikey create -data <dir> -project acme [-name <label>] [-role admin|agent|approver|viewer] [-expires <duration>]
automaton apikey list   -data <dir>
automaton apikey revoke -data <dir> -id ak_...
```

`apikey create` prints the plaintext once and stores only a digest of it. `-role` defaults to `agent`. [Claiming a deployment](../deploying/claiming-a-deployment.md) is the longer version.

## Health

```bash
automaton health -url http://127.0.0.1:8080 [-timeout 5s] [-ready]
```

Without `-ready` it asks whether the process is alive. With it, whether the process wants traffic. A draining node answers the first and refuses the second. The command exists because the deployment image carries no shell and no `curl`, so the healthcheck has to be a binary that is already in the container.

## Retention and erasure

```bash
automaton retention sweep   -project acme -data <dir> [-json]
automaton retention sweep   -deployment  -data <dir> [-json]
automaton retention history -project acme -data <dir> [-limit 20]

automaton erase -data <dir> -project acme -handle col_... -reason <why> [-cascade]
```

A sweep applies the declared windows once. Collections past their window are erased by destroying their key. The payload fields of tool calls, job log entries and trigger events past theirs are replaced with a redaction record holding the original byte count, field count and digest. Every identifier, timestamp, status, error code, count and link survives, and no row is deleted, so the [audit record](../administering/the-audit-record.md) stays whole while the data inside it goes.

A window of zero days means keep forever, so a project that declared no retention is a project a sweep does nothing to. Both commands need the vault key present, because destroying a collection's key means unsealing it first.

## The outbound audit

```bash
automaton egress denials -data <dir> -project acme [-since 168h] [-limit 50]
automaton egress hosts   -data <dir> -project acme [-since 168h] [-limit 50]
```

Which hosts were refused, and which hosts a project actually reached. Both read the audit database directly, so they answer while the deployment is down, which is when the question usually gets asked. [Hardening](./hardening.md) covers what to do with the answers.

## Governance, against a running server

```bash
automaton governance spend       -addr <url> -key <api key> [-group-by day|toolkit|entity] [-since <duration>]
automaton governance attribution -addr <url> -key <api key> -chain <hop[,hop...]> [-limit 100]
automaton governance providers   -addr <url> -key <api key> [-closed] [-toolkit <slug[,slug...]>]
automaton governance measurement -addr <url> -key <api key> -job <job id>
```

Spending against ceilings, which principal chain a call is attributed to, which providers are holding or refusing traffic, and how one job's work was measured. These address the server because the module behind them owns no database of its own, so there is nothing on disk to open.

## Exporting traces to your own collector

```bash
automaton otel get    -addr <url> -key <api key>
automaton otel set    -addr <url> -key <approver key> -endpoint <collector base url> [-sampling 1.0] [-attr key=value] [-disabled]
automaton otel export -addr <url> -key <api key>
```

Writing a destination needs an approver key, and `export` needs a live exporter, which is why these go through the server rather than editing a table behind its back. Pointing this at your own observability stack is how atmon's traces end up beside everything else you already watch.

## Catalog snapshots

```bash
automaton snapshot create  -data <dir> [-project acme]
automaton snapshot list    -data <dir>
automaton snapshot envs    -data <dir> -project acme
automaton snapshot pin     -data <dir> -project acme -env prod (-snapshot snp_... | -latest)
automaton snapshot promote -data <dir> -project acme -from staging -to prod -scorecard <file>
```

Freezing which apps and actions a project sees, and moving that pin deliberately. [Upgrades](../deploying/upgrades.md) is where this usually matters.

## Adding a connector from a specification

```bash
automaton import spec    -spec <openapi.json|yaml> -slug <slug> -category <category> [-base-url <url>]
automaton import gate    -dir <staging dir>
automaton import promote -dir <staging dir> [-ack-destructive]
automaton import status
```

Turning an OpenAPI document into an app definition, measuring the result before it is served, and promoting it once it passes. `-ack-destructive` is a deliberate acknowledgement that the import created actions classed as destructive, so a class you did not mean to create cannot arrive quietly.

For a project adding tools of its own rather than the deployment adding them for everybody, the console's Build screen is the path, and it is documented in the product documentation.

## What is not on this page

The binary carries a handful of further subcommands used for developing and measuring atmon itself rather than for operating a deployment: documentation generation, ranking replay, scorecards, dry runs, tuning, and the Postgres copy. They ship because it is one binary. They are not part of the operator surface, they are not covered by the compatibility promise the commands above carry, and nothing in a normal deployment needs them.