Ankra CLI

A command-line interface for the Ankra Platform that allows you to manage Kubernetes clusters, operations, stacks, manifests, addons - and tap into platform-wide insights.

Declare a cluster's platform in one file, apply it, and watch it converge:

When something is wrong, the same CLI reads the live cluster and explains it - including where to fix it so the next deploy does not revert you:

_{Both GIFs are generated by docs/demo/record.sh against a local mock of the Ankra API - no account, no network, and every cluster, name and answer in them is fabricated.}

📖 Documentation lives at docs.ankra.ai. The complete CLI command reference - every command, flag, and default - is generated from this repository on each release, so it never drifts from the shipped CLI. Start with the CLI overview for installation and authentication guides. This README covers installing the CLI and developing it; for how to use any command, the docs are canonical.

Installation

Homebrew (Recommended for macOS and Linux)

brew install ankraio/tap/ankra

Upgrades then flow through Homebrew as usual:

brew update && brew upgrade ankra

A Homebrew-managed ankra refuses to self-update via ankra upgrade and points you at brew upgrade ankra instead, so Homebrew stays the single owner of the binary.

Quick Install Script

For macOS and Linux without Homebrew, use the universal installer:

bash <(curl -sL https://github.com/ankraio/ankra-cli/releases/latest/download/install.sh)

This script will:

• Auto-detect OS & architecture
• Download the correct binary
• Handle macOS security attributes
• Install to /usr/local/bin

Manual Installation

1. Download the binary for your platform from the latest release:

   • ankra-cli-darwin-amd64 (macOS Intel)
   • ankra-cli-darwin-arm64 (macOS Apple Silicon)
   • ankra-cli-linux-amd64 (Linux x86_64)
   • ankra-cli-linux-arm64 (Linux ARM64)
   • ankra-cli-windows-amd64.exe (Windows x86_64)
   • ankra-cli-windows-arm64.exe (Windows ARM64)

2. Make it executable and install:

   chmod +x ankra-cli-*
   sudo mv ankra-cli-* /usr/local/bin/ankra

3. For macOS: Remove quarantine attribute:

   xattr -d com.apple.quarantine /usr/local/bin/ankra

Upgrading

Homebrew installs upgrade with brew update && brew upgrade ankra.

For script or manual installs, the CLI can update itself:

ankra upgrade                       # upgrade to the latest release
ankra upgrade --check               # report whether a newer release is available
ankra upgrade --version v0.2.5      # install (or roll back to) an exact release
ankra upgrade --skills=false        # upgrade without refreshing the installed agent skills

The agent skills (ankra skills install) ship inside the binary, so an upgrade offers to refresh the copies your assistants already carry; --yes takes the offer and --skills=false declines it.

Downloads are verified against the published SHA-256 checksum and the running binary is replaced atomically; if it lives somewhere you cannot write (such as /usr/local/bin), re-run with sudo ankra upgrade. Pre-release (beta) builds are opt-in via ankra config beta enable or a one-off ankra upgrade --beta; the quick-install script can also pin one directly with install.sh --version <pre-release-tag>. See the upgrade and config reference pages for all flags and the beta-channel details.

Deprecations

Commands scheduled for removal are tracked in DEPRECATIONS.md, including the version they are removed in and the replacement to use. Running a deprecated command also prints a warning at runtime.

Getting Started

Authenticate with the browser-based login, then select a cluster to work with:

ankra login                     # opens your browser, saves the token to ~/.ankra.yaml
ankra cluster select            # pick the cluster subsequent commands act on
ankra cluster stacks list       # browse stacks in the active cluster
ankra cluster apply -f cluster.yaml

Alternatively provide a token directly via the ANKRA_API_TOKEN environment variable, the token: key in ~/.ankra.yaml, or the global --token flag. ankra logout clears saved credentials. The global --org flag runs a single command against a different organisation, and ankra cluster subcommands accept --cluster <name|id> to target a cluster - neither changes your saved selection.

Every command that reads or returns data also supports machine-readable output via the shared -o json|yaml flag, so scripts and AI agents never have to parse tables or prose.

Command Reference

The full reference - every subcommand, flag, and default - lives at docs.ankra.ai/reference/cli, one page per command family:

Command	Description
ankra agents	Inspect and control AI agent runs
ankra ai	Manage AI provider settings and the model catalog
ankra application	Manage applications
ankra charts	Browse Helm charts
ankra chat	AI-powered chat for troubleshooting and assistance
ankra cluster	Cluster operations: stacks, manifests, addons, operations, variables, access, SOPS encryption, agent status, upgrade, the auto-upgrade opt-out (cluster agent auto-upgrade enable|disable - fence an agent off from the fleet rollout for a freeze window; agent upgrade still applies a release on demand) and pipeline-step CI settings (cluster agent ci get|set - how many Ankra Pipelines steps the cluster's agent runs at once and the storage class their workspaces use, stored on the platform so an agent upgrade no longer renders the setting away), provider (Hetzner/OVH/UpCloud/DigitalOcean) lifecycle
ankra completion	Generate or install shell completion scripts
ankra config	Manage Ankra CLI settings
ankra credentials	Manage credentials (platform, provider API, SSH keys)
ankra delete	Delete a resource
ankra deployments	List and inspect releases deployed to host deploy targets, with how every host fared (deployments list --environment, deployments get <id>)
ankra helm	Manage Helm registries and credentials
ankra login	Authenticate with the Ankra platform
ankra logout	Revoke the login token and remove saved credentials
ankra openclaw	Integrate Ankra with the OpenClaw assistant
ankra org	Manage organisations, members, roles, org variables, DNS, and MCP tool servers
ankra pipeline	Run, watch and manage Ankra Pipelines: connect, list, get and disconnect pipeline repositories (optionally linking an application and a CI cluster override), dispatch a run, list and inspect runs, wait on or watch any run - including the push and pull request runs a webhook started - by its id or by commit, branch and trigger (get --wait, get --watch -o json for one JSON object per state change, --head-sha … --latest, exit codes that carry the outcome), follow a running step's logs live (--follow waits for a step that has not started yet, saying what it is blocked on; --replay also shows what it printed before you connected) or read a concluded step's whole log - its archived copy where the organisation's backup vault produced one, and otherwise replayed from the platform's retained log stream, cancel or re-run, list and download stored artifacts, read a run's persisted scan findings, validate .ankra/pipeline.yaml (each planned step is printed with the egress tier it resolved to, so a build planned with no egress is visible before the run), manage the definition and its schedules, and inspect or approve a stored definition's protected-authority approval state (pipeline definitions get|approve - there is no lookup route for a definition's id yet, so find one from pipeline get's authority_definition_id field on a run whose authority changed)
ankra profile	Open profile authentication settings (MFA, passkeys) in the browser
ankra registry	Manage the organisation's Ankra registry: create, list, get, rotate and revoke robot accounts on its project (registry robots create <name> --scope push|pull, or --permission resource:action for exactly the rights a job needs, with --expires-in-days for a login that should lapse; the secret is printed once, with the docker login that uses it, and the login is stored as the managed credential ankra-harbor-robot-<name>). registry robots list also shows the robots Ankra manages (ci, pull, one per application), read-only. registry projects create|list|delete manages extra registry projects, and registry robots create --project <name> binds a robot to one of them so it reaches only that project
ankra services	Set up, inspect and retire managed services (PostgreSQL, Valkey, OpenSearch, VictoriaMetrics, VictoriaLogs, ...): browse the catalogue (services packages list|get), declare a cluster's placement policy (services policy get|set) and bind consumer namespaces (services consumers bind|list|get), then services setup <name> --package <package> --consumer <id> prepares the platform's review, shows the plan and confirms it by its digest only after a yes or --yes (--review-only stops before confirming). services list|get show deployment state, health, readiness and the connection (endpoints and the credentials Secret's name and keys; values are never shown). services delete <name> --acknowledge-data-loss reviews and confirms the retirement the same way, resuming an open review and following it with --wait; services reviews and services retirements list, read and confirm your open reviews
ankra skills	Install Ankra Agent Skills into Cursor or Claude Code
ankra migrate	Convert a docker-compose file, Dockerfile, or running containers into Ankra cluster and stack definitions, and export their databases for a restore into the cluster; extensible with ankra-module-<name> executables
ankra stack-profiles	Manage reusable stack profiles
ankra support	Create and track Ankra support requests
ankra targets	Host deploy targets: mint single-use join tokens, register a machine as root on the host (downloads and checksum-verifies ankra-host-agent, then installs its systemd service), and list, get or revoke targets
ankra tokens	Manage API tokens
ankra cost	Read cloud cost: fleet rollup, cluster estimates and pricing settings
ankra upgrade	Upgrade the Ankra CLI to the latest release

The CLI is also self-documenting: ankra --help lists every command family and ankra <command> --help shows the flags for any subcommand - the same help text the published reference is generated from.

Build from Source

Prerequisites: Go 1.25+

git clone https://github.com/ankraio/ankra-cli.git
cd ankra-cli
go test ./...
go build -o ankra

Project Structure

ankra-cli/
├── cmd/                    # Cobra command implementations
│   ├── services.go         # APIClient interface definition
│   └── root.go             # Root command, config, auth
├── internal/client/        # HTTP API client
│   ├── client.go           # Client struct and constructor
│   ├── helpers.go          # Shared HTTP helpers (getJSON, parseJSON)
│   ├── clusters.go         # Cluster operations
│   ├── organisations.go    # Organisation management
│   └── ...                 # Addons, stacks, tokens, credentials, chat, etc.
├── internal/migrate/       # `ankra migrate`: module contract, registry, external-module protocol
│   └── docker/             # Built-in module: compose, Dockerfile, live daemon -> Kubernetes
├── examples/modules/       # A complete external migrate module, for module authors
├── tools/gendocs/          # Generates the docs.ankra.ai CLI reference
├── testing/stack_test/     # YAML fixtures for testing
├── main.go                 # Entry point
├── go.mod
├── install.sh
└── README.md               # This file

Testing

The project uses Go's standard testing package with table-driven tests, net/http/httptest for API client tests, and t.TempDir() for filesystem tests. No external test dependencies.

Run all tests

go test ./...

Run with race detection and coverage

go test -race -count=1 -coverprofile=coverage.out ./...
go tool cover -func=coverage.out

Test architecture

Layer	Location	Strategy
Pure functions	cmd/*_test.go	Table-driven unit tests for YAML parsing, URL detection, conflict resolution
API client	internal/client/*_test.go	httptest-based tests with canned JSON responses for every endpoint
Command E2E	cmd/e2e_test.go	Mock-based tests via the APIClient interface, verifying command output
Clone/encrypt	cmd/clone_integration_test.go	Filesystem tests with t.TempDir() for stack cloning and YAML round-trips

CI runs go test -race on every push via GitHub Actions.

Contributing

1. Fork the repo
2. Create a feature branch
3. Run go test -race ./... and ensure all tests pass
4. Open a pull request

Command documentation is generated, not hand-written: tools/gendocs renders the published CLI reference from the cobra command tree, and .github/workflows/docs-sync.yml opens a PR against ankraio/ankra-docs on every release tag. To improve the docs for a command, improve its Short/Long help text and flag descriptions in cmd/.

Troubleshooting

• Ensure ankra is in your PATH
• Verify ANKRA_API_TOKEN is set (or run ankra login)
• Check connectivity: ankra cluster list
• Visit the documentation for detailed guides
• Check the Ankra Platform status for any service outages

Learn More

• Platform Overview: ankra.ai
• Documentation: docs.ankra.ai
• CLI Command Reference: docs.ankra.ai/reference/cli
• Blog & Tutorials: ankra.ai/blog
• Community: community.ankra.ai

Support

• Issues: https://github.com/ankraio/ankra-cli/issues
• Documentation: docs.ankra.ai
• Community Slack: community.ankra.ai
• Email: hello@ankra.io