agentctl (CLI)
The command-line client — sign in, create and manage tasks, follow logs, and control the local worker — plus how to use it in CI with an API token.
Sign in
Terminal
agentctl login --server https://orchestration.example.com # through the browser: password, Google, GitHub, SSO
agentctl login --server https://orchestration.example.com --email you@example.com # password (AO_PASSWORD / AO_MFA_CODE or prompt)
agentctl logout--no-browser only prints the link.
Control plane
| Command | Purpose |
|---|---|
agentctl status | Overview of the current organization |
agentctl project list | Projects |
agentctl task list [--status S1,S2] [--project ID] | Tasks |
agentctl task create --project ID --title T --prompt P [--priority HIGH] [--knowledge-file FILE] | New task |
… --review-head BRANCH [--review-base main] | Review a branch instead of changing code |
… --plan | Break the goal into tasks |
agentctl task apply-plan <id> | Create the tasks a completed plan proposes |
agentctl task show <id> | Details |
agentctl task cancel|retry|pause|resume <id> | Actions |
agentctl task input <id> --text "answer" | Answer a question |
agentctl logs <taskId> [--output] | Timeline |
agentctl agent list, agentctl provider list | Agents and providers reported by workers |
Local worker
| Command | Purpose |
|---|---|
agentctl worker status | Worker state |
agentctl worker connect --server <url> | --hosted [--name N] | Pair (--hosted only in builds with a hosted service) |
agentctl worker disconnect | Unpair |
agentctl doctor | Diagnostics |
agentctl update | Update status |
Options: --json for machine-readable output, --org <id> to pick an organization.
CI and scripts
Set AO_SERVER, AO_TOKEN (a personal API token from Settings → Your account → API tokens) and AO_ORG instead of
logging in. A token works only in its organization, with the role it was created with, capped at its owner's current
role.