Plan greenfield Akua CLI architecture and AXI UX

[robinbraemer]

Context

This issue was originally opened as a narrow Go module-path rename from github.com/cnap-tech/cli to github.com/akua-dev/cli. Scout findings showed that this is the wrong primary framing: the current CLI is CNAP-era Go code across binary name, module path, config paths, environment variables, auth assumptions, release metadata, update checks, and command implementation.

Captain decision: pivot this item to the greenfield Akua CLI plan.

Decisions

• Canonical binary: akua.
• Runtime: Bun + TypeScript.
• Packaging goal: Bun-produced self-contained CLI artifact.
• Repository: separate open-source akua-dev/cli repo.
• First release surface: public API commands only.
• Default output: adaptive.
  • Detect well-known coding-agent environment variables and standard automation signals such as non-TTY/CI, then emit compact agent-friendly structured output.
  • Otherwise default to human-friendly output.
• Legacy support: no compatibility requirement for the old cnap binary or github.com/cnap-tech/cli.
• OpenAPI source: include a mise task that fetches the latest public OpenAPI spec from the existing production endpoint https://api.akua.dev/v1/openapi.json.

Goal

Design and then implement a codegen-heavy Akua CLI that uses the current Akua public API/OpenAPI contract as its source of truth, with AXI-style behavior for coding agents: compact structured output, deterministic errors and exit codes, contextual next steps, safe automation defaults, and generated docs/tests.

Accepted Architecture Direction

• Use Bun/TypeScript for the new CLI.
• Generate the command model from the public OpenAPI spec plus a small curated CLI overlay.
• Keep the first implementation focused on public commands only.
• Use https://api.akua.dev/v1/openapi.json as the live production spec source.
• Add a mise task, for example mise run spec:fetch, that downloads the live spec into the repo for codegen.
• Prefer generated API/client code and generated command/docs artifacts over hand-written resource clients.
• Preserve a clear stdout/stderr contract:
  • success data on stdout,
  • progress/debug/warnings on stderr,
  • no spinners/prompts in agent/CI/non-TTY modes.
• Implement structured errors with request IDs, API status/code, validation paths, retry hints, and suggested next commands.
• Require explicit confirmation flags for destructive or unsafe noninteractive actions.

Non-Goals

• Do not rename the old Go module as a standalone migration.
• Do not preserve compatibility with the old cnap binary or github.com/cnap-tech/cli.
• Do not expose internal/admin/partner APIs in the first release.
• Do not mutate live infrastructure as part of CLI implementation.

Follow-Up Implementation Item

Implementation is tracked separately so this issue can remain the planning/spec anchor.

Next implementation issue: #13

Scout Report

Detailed scout report: data/akua-cli-greenfield-plan-scout/report.md in the Akua secondmate home.

[robinbraemer]

Captain decisions incorporated:

• akua is the canonical binary.
• Use Bun/TypeScript because Bun can produce a self-contained CLI.
• Keep the CLI in the separate open-source akua-dev/cli repo.
• First release exposes public commands only.
• Default output should adapt to coding-agent/automation environment signals, otherwise remain human-friendly.
• No legacy compatibility is required for old cnap or github.com/cnap-tech/cli.
• Include a mise task to fetch the public OpenAPI spec from https://api.akua.dev/v1/openapi.json.

I updated this issue from “rename Go module path” to the greenfield Akua CLI planning/spec anchor. Implementation should happen in a separate follow-up item; no CLI rewrite has started yet.