> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ankra CLI

> Comprehensive guide for installing, configuring, and using the Ankra CLI to manage clusters, chat with AI, browse charts, and automate platform operations.

## 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

### Single Command Installation (Recommended)

```bash theme={null}
bash <(curl -sL https://github.com/ankraio/ankra-cli/releases/latest/download/install.sh)
```

After installation, verify with:

```bash theme={null}
ankra --version
```

### Direct Download

Download the binary directly from [GitHub Releases](https://github.com/ankraio/ankra-cli/releases/).

```bash theme={null}
chmod +x ankra
mv ankra ~/bin/ankra  # or /usr/local/bin/ankra
```

### Upgrading the CLI

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.

```bash theme={null}
# 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)                                                             |

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

#### 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:

```bash theme={null}
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

### SSO Login (Recommended)

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

```bash theme={null}
ankra login
```

This will:

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

Your credentials are saved to `~/.ankra.yaml`.

To logout and clear credentials:

```bash theme={null}
ankra logout
```

### Environment Variables (Alternative)

You can also use environment variables:

```bash theme={null}
export ANKRA_API_TOKEN=your-token-here
export ANKRA_BASE_URL=https://platform.ankra.app  # optional
```

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

## Quick Start

```bash theme={null}
# 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 helm releases`, `cluster metrics ...`) default to `-o table` and accept `json`/`yaml` as alternatives.

```bash theme={null}
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, ...}`.

## 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:

<Card title="CLI Command Reference" icon="terminal" href="/reference/cli/index">
  Browse all 18 command families: cluster, credentials, tokens, profile, org, chat, skills, and more.
</Card>

Highlights:

| Task                                      | Command                                 |
| ----------------------------------------- | --------------------------------------- |
| Apply an ImportCluster manifest           | `ankra cluster apply -f cluster.yaml`   |
| Watch operations                          | `ankra cluster operations list`         |
| Chat with the AI about live cluster state | `ankra chat "why is my pod crashing?"`  |
| Clone a stack between clusters            | `ankra cluster stacks clone`            |
| Encrypt secrets with SOPS                 | `ankra cluster encrypt -f secrets.yaml` |
| Provision a Hetzner cluster               | `ankra cluster hetzner create`          |
| Mint a kubeconfig context                 | `ankra cluster kubeconfig write`        |
| Manage 2FA and passkeys                   | `ankra profile auth status`             |

## Configuration

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

```yaml theme={null}
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):

1. `--token` flag (explicit CLI argument)
2. Config file token (saved by `ankra login`)
3. `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:**

```bash theme={null}
which ankra  # verify installation location
echo $PATH   # check PATH includes ankra location
```

**Authentication errors:**

```bash theme={null}
ankra logout  # clear credentials
ankra login   # re-authenticate
```

**Check version:**

```bash theme={null}
ankra --version
```

**Get help:**

```bash theme={null}
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](https://join.slack.com/t/ankra-community/shared_invite/zt-3a5rem8f8-cUho4epX2MoLT83bFf~VSA)
* **Email:** [hello@ankra.ai](mailto:hello@ankra.ai)
* **GitHub:** [ankraio/ankra-cli](https://github.com/ankraio/ankra-cli)

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