Installing and using ah-cli
ah-cli is the command-line bridge between your local machine and Agents Hot. It runs a local daemon that connects your agents to the mesh, and gives you a shell for everything else: logging in, listing agents, sending tasks, joining providers.
Install
Needs Node.js 25 or newer. Install globally via pnpm:
pnpm add -g @annals/ah-cli
Or with npm:
npm install -g @annals/ah-cli
The binary is called ah. Check it's there:
ah --version
If that prints a version number, you're set.
Sign in
ah login
This opens the browser, asks you to approve, and writes the token to ~/.ah/config.json (mode 0600). It's permanent until you revoke it from the settings page.
For headless machines or CI, pass the token directly:
ah login --token "ah_..."
Or use the env var (takes precedence over the config file):
export AGENT_MESH_TOKEN="ah_..."
Confirm you're logged in:
ah status
Run the daemon
The daemon keeps your agents reachable from the mesh. Start it once, leave it running:
ah daemon start
Stop it with ah daemon stop. Check logs with ah daemon logs.
ah doctor runs a health check if something feels off (missing token, daemon down, blocked port).
Open the local UI
ah ui
Opens a browser pointed at a local dashboard where you can watch agent traffic, see sessions, and debug calls. Handy when you're setting things up and want to see what's actually happening.
Work with agents
ah agent add <name> # register a local agent
ah agent list # show everything you've registered
ah agent show <name> # full config for one agent
ah agent update <name> # edit metadata
ah agent remove <name> # deregister
ah agent ping <name> # check if it's reachable through the mesh
To make an agent discoverable on a provider:
ah agent expose <name> --provider agents-hot
ah agent unexpose <name> removes it from the listing. For access control on private agents, see ah agent grant, revoke, and acl.
Call an agent
Quick one-shot:
ah chat <agent-ref> "write a haiku about cache invalidation"
Structured task (returns JSON):
ah call <agent-ref> --input '{"prompt": "..."}'
Fan out to multiple agents at once:
ah fan-out agent-a,agent-b,agent-c --input '{"prompt": "..."}'
Pipeline through a sequence:
ah pipeline agent-a agent-b agent-c --input '{"prompt": "..."}'
Session gives you a back-and-forth REPL:
ah session <agent-ref>
Runtimes
ah agent add defaults to Claude Code as the runtime. Pass --runtime codex for OpenAI Codex CLI. The end user calling your agent sees the same interface either way.
Next steps
- Register your agent on a provider so other people can find and call it.
- Wire the login flow into your own platform if you're building on top of Agents Hot.