The Atamaia CLI

atamaia is a single .NET global tool that wraps authentication, raw API access, and agent dispatch for the Atamaia platform.

Install

dotnet tool install --global Atamaia.Cli
# later:
dotnet tool update --global Atamaia.Cli

Make sure ~/.dotnet/tools is on your PATH (or shim it: ln -s ~/.dotnet-tools/atamaia ~/bin/atamaia).

Configuration (environment)

Variable Meaning Default
ATAMAIA_URL Which environment to talk to http://localhost:5000
ATAMAIA_IDENTITY Which identity you act as — (unset = your user credential)

For the hosted service: export ATAMAIA_URL=https://api.atamaia.ai. For local development leave the default — these point at different databases, and tokens minted for one never authenticate against the other.

Identity keys

Durable keys live at ~/.config/atamaia/acp-keys/<name>.key (mode 0600). They are password-equivalent: never commit them, never paste them into a chat or a brief, never give a worker your own key — mint a scoped key per identity instead.

atamaia-auth exchanges a durable key for a short-lived JWT and caches it per host (~/.cache/atamaia/token-<hash>.json), so dev and prod tokens never collide.

Commands

atamaia-auth

Prints a bearer token for the configured environment and identity:

TOKEN=$(ATAMAIA_IDENTITY=ash atamaia-auth)
curl -H "Authorization: Bearer $TOKEN" "$ATAMAIA_URL/api/agent/runs/801/files"

atamaia-call METHOD /path [json-body]

Authenticated API call — the everyday driver. GET /health is unauthenticated; most agent read endpoints accept an identity JWT.

atamaia-call POST /api/projects/1/tasks '{"title":"…","kind":"Bug","subsystem":"Agent"}'

atamaia acp run — dispatch an agent worker

atamaia acp run   --brief ./brief.md   --cwd /path/to/workdir   --identity worker-name   --mode build   --trace ./run.trace   --timeout 3600
Flag Meaning
--brief FILE The task file the worker executes (see the ACP bridge)
--cwd DIR The worker's sandbox — writes outside it are denied unless --allow-outside names them
--identity NAME Identity key the worker uses; --no-mcp runs with no platform tools at all
--mode plan|build plan disallows edit tools; build is full access
--trace FILE Always set one. A dispatch buffers its narration until it exits — without a trace there is nothing to watch
--model ID Override the worker's model
--timeout SEC Hard wall-clock limit

atamaia acp watch / atamaia acp ps

Watch a live or finished dispatch, and list sessions:

atamaia acp watch --trace ./run.trace --follow
atamaia acp ps --all

See also