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 — for zcode the format is <providerId>/<modelId>[$<reasoningLevel>] (e.g. account:zai-individual-coding-plan/GLM-5.3-Flash$low)
--harness opencode|dsh|zcode Worker runtime; default opencode. zcode bridges ZCode Protocol to ACP and drives GLM on the z.ai coding plan (see the ACP bridge)
--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

atamaia ask — global search

One query, fanned out across the default domains, results grouped per domain:

atamaia ask harness protocol          # grouped per-domain hits, printed
atamaia ask "where does retry happen" # graph hits: lexical AND semantic (embeddings)
atamaia ask old memory --domains all  # sweep everything, including memory stores

The default fan-out (#742) is the shared corpus: Tasks, Docs, Facts and Graph — the graph group delegates to the code-graph search, so behavioural questions match semantically, not just by identifier. The memory-class domains (Memories, AgentMemories, PersonalMemories, Reflections) and admin-class ones (Providers, Models, StandingRules, Messages) are opt-in via --domains a,b or --domains all; memory domains search your own identity only unless memoryScope=readable is passed on the API.

Under the hood this is GET /api/search?q=<query>, which returns { groups: [{ domain, status, total, results: [{ id, title, snippet, score, … }] }] } — a group whose scope you lack reports SkippedNoScope instead of results; a domain you did not ask for is simply absent.

See also

Last updated