Ankra CLI

What is Ankra CLI?

The Ankra CLI is a powerful command-line interface for interacting with the Ankra platform. It enables you to manage clusters, chat with AI about your infrastructure, browse Helm charts, manage credentials, deploy stacks, and automate platform operations directly from your terminal.

Installation

Homebrew (recommended for macOS and Linux)

brew install ankraio/tap/ankra

The formula lives in the ankraio/homebrew-tap tap and is bumped automatically on every stable release. Upgrade later with Homebrew as usual:

brew update && brew upgrade ankra

Install script

For macOS and Linux without Homebrew - and for CI runners - use the universal installer:

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

It detects your OS and architecture, verifies the download against its published SHA-256 checksum, strips the macOS quarantine attribute where needed, and installs to /usr/local/bin/ankra. Pin an exact release by appending --version <tag>. After installing either way, verify with:

ankra --version

Direct Download

Download the binary directly from GitHub Releases.

chmod +x ankra
mv ankra ~/bin/ankra  # or /usr/local/bin/ankra

Upgrading the CLI

If you installed with Homebrew, upgrade through Homebrew:

brew update && brew upgrade ankra

A Homebrew-managed binary refuses ankra upgrade and points you at brew upgrade ankra instead, so the two upgrade paths never fight over the same file. For script and manual installs, the CLI can update itself in place with ankra upgrade (aliased as ankra self-update). The downloaded binary is verified against its published SHA-256 checksum before it replaces the running executable.

# Upgrade to the latest stable release
ankra upgrade

# Check whether a newer release exists without installing
ankra upgrade --check

# Pin an exact version (also works as a downgrade / rollback)
ankra upgrade --version v0.3.0

Flag	Description
`--version <tag>`	Install an exact release (e.g. `v0.3.0` or `0.3.0`); installs whether newer or older, so it doubles as a rollback
`--check`	Report whether a newer release is available without installing
`--beta`	Include pre-release versions for this run (overrides the saved channel)
`--force`	Reinstall even if already on the target version
`-y, --yes`	Skip the confirmation prompt
`--allow-unverified`	Install even when no checksum is published (insecure)

If the binary lives in a root-owned location, run sudo ankra upgrade or re-run the install script.

Beta (pre-release) channel

Opt in to release candidates (such as v0.3.0-rc.1) so ankra upgrade resolves the newest release including pre-releases:

ankra config beta enable    # opt in
ankra config beta status    # show current channel
ankra config beta disable   # back to stable only

The channel preference is stored locally in ~/.ankra/settings.json (separate from your credentials).

Authentication

The easiest way to authenticate is using browser-based SSO:

ankra login

This will:

Open your browser to the Ankra login page
After you authenticate, save your credentials locally
You can then use all ankra CLI commands

Your credentials are saved to ~/.ankra.yaml. To logout and clear credentials:

ankra logout

Environment Variables (Alternative)

You can also use environment variables:

export ANKRA_API_TOKEN=your-token-here
export ANKRA_BASE_URL=https://platform.ankra.app  # optional
export ANKRA_PROJECT=payments                     # optional: the project every command acts in

Add to your shell profile (~/.zshrc or ~/.bashrc) for persistence.

Quick Start

# 1. Login with SSO
ankra login

# 2. List your clusters
ankra cluster list

# 3. Select a cluster to work with
ankra cluster select

# 4. Start chatting with AI about your infrastructure
ankra chat "What's the status of my deployments?"

Machine-readable output (`-o json|yaml`)

Commands that read or return data support structured output via the shared -o/--output flag, so scripts and AI agents never have to parse tables or prose:

-o json prints the result as indented JSON; -o yaml emits the same data as YAML.
The kubectl-style commands (cluster get ..., cluster describe, cluster events, cluster logs, cluster top ..., cluster helm releases, cluster metrics ...) default to -o table and accept json/yaml as alternatives.

ankra cluster list -o json
ankra cluster operations list -o json
ankra cluster get pods -o json
ankra org list -o json

Write commands (reconcile, provision, deprovision, scaling, node groups, token creation, …) also accept -o json and emit the API result - including operation IDs - so automation can poll ankra cluster operations list <id> -o json for completion. Asynchronous writes submitted without --wait emit {"submitted": true, ...}.

Projects

ankra project, the global --project flag and ANKRA_PROJECT, ankra tokens create --project, ankra org invite --role project and the cost and usage project options require Ankra CLI v0.49.0 or later. Check with ankra --version and upgrade with ankra upgrade. Projects themselves are already on for every organisation on the new portal: older CLIs act in your current project, the one the console shows.

Every command acts in one project of your current organisation: the one --project or ANKRA_PROJECT names, else the one ankra project switch saved on this machine for this organisation, else your current project as the console shows it. ankra project manages projects and your place in them:

# Where am I, and what else is there
ankra project current
ankra project list

# Switch - every command after this acts in payments, in the console too
ankra project switch payments

# Create, inspect, rename, delete (the Default project cannot be deleted)
ankra project create "Payments" --slug payments --description "The payments team"
ankra project get payments
ankra project rename payments "Payments platform"
ankra project delete old-team --yes

# Who reaches a project, and through which role
ankra project members payments

# Move a resource into another project, or make a shared kind organisation-wide
ankra project move --kind cluster --id prod-eu-1 --to payments
ankra project move --kind application --id storefront --to payments
ankra project move --kind credential --id <credential-id> --to org-wide

# Invite someone who reaches only one project
ankra org invite [email protected] --role project --project payments --project-role operator

A project is named by its slug, its name or its id; --id on a move also takes a cluster or application name. ankra project switch saves the project on this machine for the organisation you are in (ankra org switch forgets it), and it applies only when you act with your ankra login session, not with a token supplied by flag or environment variable; ankra project current says whether a flag, that saved selection or the platform’s current project decides. To act in another project for one command, use the global --project <slug|name|id> flag or the ANKRA_PROJECT environment variable. Like --org, it applies to every command and every request of the invocation, sent as X-Ankra-Project-Id, without moving your current project:

ankra cluster list --project payments
ANKRA_PROJECT=payments ankra cluster list

--role project on ankra org invite makes a project-only member of the project the global --project names; --project-role is admin, operator, member or viewer, member by default. ankra project move refuses with the platform’s code and sentence when the resource is already in that project (same_project), when operations are still running on a cluster (operations_in_flight), or when a DNS zone is bound to a cluster and follows it (follows_cluster). The kinds it accepts are listed on the Projects page. Tokens take a project at creation: ankra tokens create <name> --project payments mints a token pinned to that project, see API tokens. The fleet cost reads (ankra cost summary, savings, ledger, trend, events, reconcile and cost budgets list) cover the project you act in and take --all-projects for the whole organisation; ankra cost object project <project> prices one project, and ankra org usage --group-by project splits worker vCPU-hours by project. See Cloud Cost and Usage. In an organisation with projects off (one whose portal is not yet the new one; the new portal carries /next in its address), every ankra project command exits 3 and says so. ankra project is unrelated to ankra registry projects, which are the projects of your image registry. Because --project is now the global flag, two older local flags were renamed: ankra registry robots create --project is --registry-project, and ankra skills list|install|uninstall|clients --project <dir> is --dir <dir>. The old spellings still work on those commands for one minor release with a deprecation line, and there they still mean the registry project or the directory; use ANKRA_PROJECT to pick an Ankra project on those commands until the old flags are removed.

Command Reference

The full command reference - every command, subcommand, flag, and default - is generated from the CLI source on each release, so it never drifts:

CLI Command Reference

Browse all 32 command families: cluster, credentials, tokens, profile, org, chat, agents, application, skills, and more.

Every guide that shows an ankra command carries a CLI vX.Y.Z+ marker above it: the first stable release that shipped the command. Compare it with ankra --version; a marker newer than the latest stable release means a pre-release command, reachable through the beta channel. Highlights:

Task	Command	Since
Apply an ImportCluster manifest	`ankra cluster apply -f cluster.yaml`	v0.1.122
Switch the project every command acts in	`ankra project switch payments`	v0.49.0
Move a cluster into another project	`ankra project move --kind cluster --id prod-eu-1 --to payments`	v0.49.0
Watch operations	`ankra cluster operations list`	v0.1.122
Read the log a crash-looping container left behind	`ankra cluster logs my-pod -n default --previous`	v0.13.0
Ask one object why it is not ready	`ankra cluster describe pod my-pod -n default`	v0.13.0
See only the events for one object	`ankra cluster events --for pod/my-pod -n default`	v0.13.0
Find what just ate the memory	`ankra cluster top pods -A --sort-by memory`	v0.13.0
Chat with the AI about live cluster state	`ankra chat "why is my pod crashing?"`	v0.1.122
Confirm a write that agent-mode chat proposed	`ankra chat actions confirm <action_id>`	v0.9.0
Parse the AI’s answer in a CI job	`ankra chat --mode ask -o json "is anything degraded?"`	v0.21.0
Read one Secret’s values, audited	`ankra cluster get secrets db-credentials -n default --reveal -o yaml`	v0.21.1
Inspect what your AI agents are doing	`ankra agents runs`	v0.9.0
Answer the choice a blocked AI board ticket is waiting on	`ankra tickets decide T-8 --option a`	v0.13.0
See which of your vulnerabilities CISA lists as exploited in the wild	`ankra security findings --known-exploited`	v0.14.0
Read the fleet’s security posture and CISA KEV exposure	`ankra security overview`	v0.14.0
Read the platform’s advisory for a CVE - the parsed NVD/OSV record, CISA’s guidance, affected versions and your exposure	`ankra security advisory <cve>`	v0.14.0
Accept the risk of a finding with a reason and a review deadline, after a server-side preview	`ankra security dispositions create --occurrence <id> --disposition accepted_risk --reason "…"`	v0.15.0
Download the compliance evidence report an auditor asks for	`ankra security compliance export --format csv`	v0.15.0
Switch a cluster’s pod-security policies from audit to enforce	`ankra security policy-mode enforce --cluster production`	v0.15.0
Clone a stack between clusters	`ankra cluster stacks clone`	v0.1.124
Move a Docker deployment into a cluster	`ankra migrate up ./app --cluster production`	v0.14.0
Extend the CLI with plugins	`ankra plugins`	v0.14.0
Register a backup vault	`ankra backup vaults create`	v0.14.0
Encrypt a Secret’s keys with SOPS	`ankra cluster encrypt manifest db-secret --key password`	v0.1.123
Provision a Hetzner cluster	`ankra cluster hetzner create`	v0.1.124
Mint a kubeconfig context	`ankra cluster kubeconfig add my-cluster --use`	v0.3.0
Open your account’s 2FA and passkey settings	`ankra profile auth open`	v0.9.0

ankra migrate up is the one that does the most in a single call: it converts a Docker Compose deployment into a stack, applies it to a cluster, and restores the deployment’s PostgreSQL, MySQL and MariaDB data into it. Run it with --plan first to see what it found. See Move a Docker deployment into a cluster. The conversion is done by a module, and docker is only the built-in one: another source format is an executable named ankra-module-<name> that the CLI talks JSON to, installed with ankra migrate modules install <url> or placed on PATH, and Write an ankra migrate module is the contract. The CLI is also extensible beyond migration, kubectl style: an unknown command runs an executable named ankra-<command> from ~/.ankra/plugins or PATH, and ankra plugins lists what is installed.

Agent Skills

The CLI carries Ankra’s curated Agent Skills - SKILL.md files that teach your AI assistant (Claude Code, the Claude app, Cursor, Codex, GitHub Copilot, Windsurf, Gemini CLI and others) to manage Kubernetes the Ankra way. ankra skills install detects the assistants on your machine and installs into all of them. See the Agent Skills guide.

Configuration

The CLI stores configuration in ~/.ankra.yaml:

token: your-api-token
base-url: https://platform.ankra.app
token_id: token-uuid
token_name: ankra-cli-hostname-username

Token resolution priority (highest to lowest):

--token flag (explicit CLI argument)
Config file token (saved by ankra login)
ANKRA_API_TOKEN environment variable

The base URL can be overridden with --base-url or the ANKRA_BASE_URL environment variable.

Troubleshooting

Common Issues

PATH issues:

which ankra  # verify installation location
echo $PATH   # check PATH includes ankra location

Authentication errors:

ankra logout  # clear credentials
ankra login   # re-authenticate

Check version:

ankra --version

Get help:

ankra --help
ankra cluster --help
ankra chat --help

Error Messages

“No active cluster selected” Run ankra cluster select first
“Resource not found” Verify the resource name and selected cluster
“Unauthorized” Re-authenticate with ankra login

Support & Resources

Slack: Join Ankra Community
Email: [email protected]
GitHub: ankraio/ankra-cli

For more advanced usage, see the full documentation or contact support.

Get Started

Use Cases

Concepts

Create and Run Clusters

Ship Your App

Ankra Pipelines

Stacks and Add-ons

Observe and Troubleshoot

Ankra AI

Connect Tools

Source Control

Security and Access

Cost and Backups

Organisation and Account

Reference

What is Ankra CLI?

Installation

Homebrew (recommended for macOS and Linux)

Install script

Direct Download

Upgrading the CLI

Beta (pre-release) channel

Authentication

Environment Variables (Alternative)

Quick Start

Machine-readable output (`-o json|yaml`)

Projects

Command Reference

CLI Command Reference

Agent Skills

Configuration

Troubleshooting

Common Issues

Error Messages

Support & Resources

​What is Ankra CLI?

​Installation

​Homebrew (recommended for macOS and Linux)

​Install script

​Direct Download

​Upgrading the CLI

​Beta (pre-release) channel

​Authentication

​SSO Login (Recommended)

​Environment Variables (Alternative)

​Quick Start

​Machine-readable output (-o json|yaml)

​Projects

​Command Reference

CLI Command Reference

​Agent Skills

​Configuration

​Troubleshooting

​Common Issues

​Error Messages

​Support & Resources

What is Ankra CLI?

Installation

Homebrew (recommended for macOS and Linux)

Install script

Direct Download

Upgrading the CLI

Beta (pre-release) channel

Authentication

SSO Login (Recommended)

Environment Variables (Alternative)

Quick Start

Machine-readable output (`-o json|yaml`)

Projects

Command Reference

Agent Skills

Configuration

Troubleshooting

Common Issues

Error Messages

Support & Resources