Port missing CLI commands from original AO (read + lifecycle surface)

[harshitsinghbhandari]

Summary

Tracking issue for porting the missing CLI commands from the original ComposioHQ/agent-orchestrator into this Go rewrite. Scope is limited to commands whose backend is already wired in the rewrite, plus a small set of one-route additions. Frontend/dashboard-only commands and features that depend on absent subsystems (review queue, plugin registry, notifier port, agent-reporting workflow) are explicitly out of scope here.

Status (2026-06-02)

Done — all 7 ready-to-add commands have shipped:

• session ls/get/kill/restore — merged in feat(cli): add ao session ls/get/kill/restore (#90) #92
• project ls/get/rm — merged in feat(cli): add ao project ls/get/rm (#90) #91
• AGENTS.md (bonus, repo-root) — merged in docs: add AGENTS.md #93

Follow-up #94 filed during review for Agent vs Harness terminology normalization.

Next up (tomorrow): the backend-needing tier (session rename, session cleanup route, orchestrator ls). The user has explicitly excluded ao open and ao status --watch from this issue's scope.

Context

A gap analysis cross-referenced the original's CLI surface (27 top-level commands, source in + "packages/cli/src" + of the upstream repo) against the current rewrite's HTTP + service layer. The rewrite already exposes the routes needed for ~70% of day-to-day commands; they just don't have CLI wrappers yet.

The rewrite's CLI prior to this issue was: + "start, stop, status, daemon, doctor, spawn, send, project add, version, completion" + (see + "backend/internal/cli/" + ).

Ready to add — backend exists, pure CLI work

• + "ao session ls" + → + "GET /api/v1/sessions" + (supports + "?project & active & orchestratorOnly & fresh" + ) — feat(cli): add ao session ls/get/kill/restore (#90) #92
• + "ao session get " + → + "GET /api/v1/sessions/{id}" + — feat(cli): add ao session ls/get/kill/restore (#90) #92
• + "ao session kill " + → + "POST /api/v1/sessions/{id}/kill" + — feat(cli): add ao session ls/get/kill/restore (#90) #92
• + "ao session restore " + → + "POST /api/v1/sessions/{id}/restore" + — feat(cli): add ao session ls/get/kill/restore (#90) #92
• + "ao project ls" + → + "GET /api/v1/projects" + — feat(cli): add ao project ls/get/rm (#90) #91
• + "ao project get " + → + "GET /api/v1/projects/{id}" + — feat(cli): add ao project ls/get/rm (#90) #91
• + "ao project rm " + → + "DELETE /api/v1/projects/{id}" + — feat(cli): add ao project ls/get/rm (#90) #91
• + "ao open [session-id]" + — excluded from this issue per user
• + "ao status --watch" + — excluded from this issue per user

All session subcommands ship with + "-p/--project" + flag as required. + "ls" + also got + "--all" + , + "--include-terminated" + , + "--json" + ; + "get" + got + "--json" + . + "kill" + / + "restore" + validate project scope client-side and return exit code 2 on mismatch.

Needs a small backend addition first (next, tomorrow)

Each needs one route (and sometimes a thin service method) before the CLI wrapper makes sense.

• + "ao session rename " + — + "PATCH /api/v1/sessions/{id}" + is registered as a 501 stub at + "backend/internal/httpd/controllers/sessions.go:114" + . Needs service method + store update.
• + "ao session cleanup [--project ]" + — + "service/session.Cleanup(projectId)" + exists internally; needs an HTTP route to expose it.
• + "ao orchestrator ls" + — + "POST /api/v1/orchestrators" + exists but there's no list route. Worth doing alongside + "session ls" + .
• + "ao session claim-pr " + — PR data is recorded but unexposed. Needs + "GET /api/v1/sessions/{id}/pr" + + a write path for claim.
• + "ao project set-default" + — no default-project concept in the domain today. Small but a design choice (config file vs DB column). Tracked as a design open question.

Enrich existing commands

• Extend + "ao doctor" + to match the original's coverage: agent-harness binary presence (claude, codex, aider, opencode), git version, zellij version, GitHub token validity. — feat(cli): enrich ao doctor (#90) #99
• Extend shell completions as new commands ship.

Explicitly out of scope (don't port)

Backend subsystem doesn't exist in the rewrite. Open separate issues if/when those land.

• + "ao batch-spawn" + — no batch-spawn orchestration.
• + "ao acknowledge" + , + "ao report" + , + "ao verify" + — Stage-3 agent reporting workflow; no reporting domain.
• + "ao review {run,execute,send,list}" + , + "ao review-check" + — no review queue service/store.
• + "ao notify test" + , + "ao setup {desktop,slack,discord,webhook,composio*,openclaw}" + — no notifier port/adapter.
• + "ao plugin {list,search,create,install,update,uninstall}" + — rewrite uses compile-time adapters; no plugin loader.
• + "ao events {list,search,stats}" + — + "changelog" + table exists, no FTS or query API.
• + "ao update" + — self-updater; package-manager territory.
• + "ao migrate-storage" + — migration from the TS-era JSON sessions; not relevant for a fresh rewrite.
• + "ao config {set,get}" + — rewrite is env-only by design.
• + "ao session remap" + — niche; defer until requested.

References

• Original CLI source: + "packages/cli/src" + in ComposioHQ/agent-orchestrator
• Rewrite CLI: + "backend/internal/cli/" +
• Rewrite HTTP routes: + "backend/internal/httpd/controllers/" +
• Rewrite services: + "backend/internal/service/" +
• Related: Normalize agent harness terminology #94 (harness terminology normalization)