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

# CLI Changelog

> Release history for the Ankra CLI

<Update label="v0.4.0">
  # Cluster Access (RBAC) and Provider-Agnostic Cloud Verbs

  Per-user cluster access management, cloud-agnostic lifecycle verbs that auto-detect the provider, and the deprecation of the provider-specific equivalents.

  ## Cluster access (RBAC)

  `ankra cluster access list | grant | revoke` manages who can reach a cluster's Kubernetes API through the Ankra kube gateway (the access used by `cluster kubeconfig` and `cluster kube-token`). A grant maps an organisation member (by email) to a Kubernetes role - `view`, `edit`, `admin`, or `cluster-admin` - cluster-wide or limited to one namespace with `--namespace`. `list` shows each grant's RBAC reconcile status; `revoke` accepts a grant ID or an email (revoking every grant that member has on the cluster). Managing access requires organisation admin rights.

  ```bash theme={null}
  ankra cluster access grant user@example.com --cluster prod --role edit --namespace staging
  ankra cluster access list --cluster prod
  ankra cluster access revoke user@example.com --cluster prod
  ```

  ## Provider-agnostic cloud cluster verbs

  New cloud-agnostic verbs detect the provider (Hetzner, OVH, UpCloud) automatically from the cluster, so you no longer pick a provider namespace:

  * `ankra cluster upgrade <cluster_id> <target_version>` - upgrade the Kubernetes (k3s) version.
  * `ankra cluster scale <cluster_id> <worker_count>` - scale the default worker pool.
  * `ankra cluster node-group <list|add|scale|upgrade|delete>` - manage node groups.
  * `ankra cluster k3s-versions` - list the k3s versions available for `cluster upgrade`, with the stable channel highlighted.

  `ankra cluster deprovision` now accepts a cluster ID **or** name (previously name-only) and routes cloud clusters to the provider-specific teardown so cloud resources are released.

  ## Agent Skills for Claude Code

  `ankra skills install | list | uninstall` gained an `--editor` flag so the curated Agent Skills can target Claude Code as well as Cursor. It defaults to `cursor` (`.cursor/skills`, unchanged); pass `--editor claude-code` to install into `.claude/skills`, for both the personal (`~/…`) and `--project` scopes.

  ```bash theme={null}
  ankra skills install                        # ~/.cursor/skills (default)
  ankra skills install --editor claude-code   # ~/.claude/skills
  ```

  ## Support review before submit

  `ankra support create` now shows the AI review before submitting: the reasons a request was flagged, clarifying questions that would speed up triage, and any existing ticket that may already track the same problem. When the review flags the request or finds a possible duplicate you're asked to confirm; `--force` skips the prompt, and `-o json|yaml` callers get a `--force`-guidance error instead of a prompt.

  ## Isolated `--config` state

  `--config <file>` now fully isolates per-invocation state: a config file with an unfamiliar or missing extension is parsed as YAML (instead of reading empty and dropping the saved token), and the active-cluster selection is keyed to the explicit `--config` path rather than `$HOME`, so parallel runs against different config files no longer clobber each other. If you previously ran with `--config` and relied on the `$HOME`-keyed selection, re-run `ankra cluster select` once.

  ## Deprecated

  The provider-specific `ankra cluster {hetzner,ovh,upcloud} upgrade | scale | node-group | deprovision` commands are deprecated in favour of the cloud-agnostic verbs above. They still work and now print a runtime warning pointing at the replacement; they are scheduled for removal in v0.5.0. OVH's `node-group labels` / `node-group taints` remain - they have no provider-agnostic equivalent yet.
</Update>

<Update label="v0.3.0">
  # kubectl, Metrics, Support, Stack Profiles, and Cluster Validation

  The first stable v0.3.0 release rounds out end-to-end terminal control of an Ankra cluster: connect kubectl directly, query metrics, file support tickets, manage reusable stack profiles, validate and stage cluster YAML, and self-update the CLI.

  ## Connect kubectl directly

  `ankra cluster kubeconfig add | remove | list` and `ankra cluster kube-token` wire kubectl straight to an Ankra cluster through the kube gateway. `kube-token` prints a short-lived Kubernetes `ExecCredential` for use as a credential plugin; `kubeconfig add` writes an `ankra-*` context (exec-based by default, or `--embed-token`) with atomic `0600` writes that leave foreign entries untouched and use collision-safe context naming.

  ```bash theme={null}
  ankra cluster kubeconfig add --cluster prod --use
  kubectl get pods
  ```

  ## Cluster metrics

  `ankra cluster metrics query | query-range` proxies a PromQL query (instant or range) to the cluster's Prometheus metrics source, with `table | json | yaml` output for ad-hoc inspection and CI.

  ```bash theme={null}
  ankra cluster metrics query 'up'
  ankra cluster metrics query-range 'rate(node_cpu_seconds_total[5m])' --range 6h --step 5m
  ```

  ## Support requests

  `ankra support create | list | get | comment | attach | close` opens and tracks Ankra support requests from the CLI, including image/screenshot attachments. Each request goes through a mandatory AI review; use `--force` to submit a request the reviewer flags.

  ## Stack profiles

  `ankra stack-profiles list | export-iac | import` manages reusable, organisation-level stack profiles as `ClusterInfrastructureAsCode` YAML (export a profile version, import one from a file).

  ## Validate and stage cluster YAML

  * `ankra cluster validate -f cluster.yaml` runs the offline `apply --dry-run` checks plus server-side chart-existence, plaintext-secret, and parent-reference validation, with CI-friendly exit codes and `--strict-secrets`.
  * `ankra cluster draft -f cluster.yaml` stages every stack as a reviewable draft instead of applying it - nothing is deployed by the command.
  * `ankra cluster apply` gained offline dependency-tree and referenced-file validation, and `--dry-run` for `apply` / `delete cluster` is fully offline (no token), so it drops into pre-merge CI.

  ## Self-update and beta channel

  `ankra upgrade` downloads, SHA-256-verifies, and atomically swaps the binary, with `--version` pinning for upgrade, downgrade, and rollback (`--allow-unverified` for releases that predate published checksums). `ankra config beta enable|disable|status` opts into pre-release builds with semver-aware precedence (a stable release outranks its release candidates).

  ## Cloud create parity and OVH commands

  * `cluster ovh | upcloud | hetzner create` gained `--external-cloud-provider` (per-cloud CCM + CSI) and `--include-networking` (Traefik + cert-manager), installed by default and reconciled directly, and committed to Git when `--gitops-credential-name` / `--gitops-repository` / `--gitops-branch` are set.
  * OVH reached web-UI parity: `ovh regions`, `ovh stop` / `ovh start`, `ovh access-info`, `ovh ssh-keys get|set`, `ovh node-group labels|taints`, and `ovh control-plane` / `ovh nodes`.

  ## Operations and machine-readable output

  `ankra cluster operations list` gained `--watch` / `-w` (with a configurable `--interval`), and both `operations list` and `operations steps` gained `-o json|yaml`. A shared `-o json|yaml` flag now spans the commands that read or return data.

  ## Security

  `ankra cluster encrypt manifest | addon` no longer produces files that only look encrypted: a dotted `--key` (e.g. `data.password`) is normalised to its last segment, and after every encryption the CLI verifies the target value is real `ENC[...]` ciphertext - hard-failing before any write or stack PATCH when SOPS encrypted nothing.
</Update>

<Update label="v0.2.5">
  # Variables, Live-Cluster SOPS, Dependency Parents, and Multi-Org

  Rounds out stack CRUD from the CLI: template variables at every scope, SOPS encryption against live clusters, dependency-parent editing, read/delete commands, a global organisation override, and offline-installable Agent Skills.

  ## Variables (org / cluster / stack scopes)

  Full CRUD for the template variables substituted into stack manifests and addon values at deploy time, at three scopes:

  * `ankra org variables list|get|set|delete` - organisation-wide, available to every cluster.
  * `ankra cluster variables list|get|set|delete [--cluster <name|id>]` - per cluster; shadows org variables on that cluster.
  * `ankra cluster stacks variables list|get|set|delete <stack>` - per stack; the most specific scope.

  `set` is an upsert (create or update). Values can be read from stdin with `-` for piping secrets, `list` / `get` support `-o json|yaml`, and `delete` prompts for confirmation (`--yes` to skip). Resolution at deploy time is **stack > cluster > organisation** - a more specific scope shadows less specific ones for the same name.

  ## SOPS encrypt/decrypt against live clusters

  `ankra cluster encrypt` and `ankra cluster decrypt` now operate directly on a live cluster, with no local `cluster.yaml` required.

  * `ankra cluster encrypt manifest <name> --key <key> [--cluster <name|id>]`
  * `ankra cluster encrypt addon --name <addon> --key <key> [--cluster <name|id>] [--stack <stack>]`
  * `ankra cluster decrypt manifest <name> [--cluster <name|id>]`
  * `ankra cluster decrypt addon --name <addon> [--cluster <name|id>] [--stack <stack>]`

  Cluster mode fetches the current content, runs it through the SOPS API, and (for encrypt) pushes the result back via the partial-stack PATCH with `encrypted_paths` updated. The `-f cluster.yaml` file mode is unchanged for GitOps workflows; the two modes are mutually exclusive and cluster mode is the default. `decrypt addon` is new, bringing the addon variant to parity with manifests.

  ## Dependency parents on upgrade

  `ankra cluster addons upgrade` and `ankra cluster manifests upgrade` now edit the dependency parents that control deployment ordering inside a stack, without re-applying the whole `cluster.yaml`:

  * `--add-parent name=<n>,kind=<manifest|addon>` - repeatable; `kind` defaults to `manifest`.
  * `--remove-parent name=<n>,kind=<manifest|addon>` - repeatable; removing the last parent clears the link.
  * `--set-parent name=<n>,kind=<manifest|addon>` - replaces ALL parents; mutually exclusive with `--add-parent` / `--remove-parent`.

  ## Read and delete

  * `ankra cluster addons values <name>` - print an addon's current Helm values (decoded; `-o raw` for the base64 form).
  * `ankra cluster manifests get <name>` - print a manifest's current YAML (decoded; `-o raw` for the base64 form).
  * `ankra cluster manifests delete <name>` - disconnect a manifest from its stack and remove its resources; the owning stack is resolved automatically and a confirmation prompt protects the operation (`--yes` to skip, `--dry-run` to preview).

  ## Run a command against another organisation

  A global `--org <name|id>` flag (or the `ANKRA_ORG` environment variable) runs a single command against any organisation you belong to, without changing your selected organisation:

  ```bash theme={null}
  ankra --org "Acme Corp" cluster list
  export ANKRA_ORG="Acme Corp"   # scope a whole shell session
  ```

  The override is per request and never changes the `ankra org switch` selection. You must be an active member of the target organisation.

  ## Install Ankra Agent Skills

  `ankra skills` installs the curated Ankra Agent Skills into a Cursor/Claude skills directory. The skills are embedded in the binary, so installation works offline and is versioned with the release.

  ```bash theme={null}
  ankra skills list                  # list available skills (marks installed ones)
  ankra skills install               # install all into ~/.cursor/skills (personal)
  ankra skills install --project .   # install into ./.cursor/skills (project)
  ankra skills install ankra-gitops  # install only named skills
  ankra skills uninstall             # remove all Ankra skills
  ```

  Use `--force` to overwrite existing skills and `--source <dir>` to install from a local directory instead of the embedded copy. This is separate from `ankra openclaw skill`, which generates a per-cluster SKILL.md.
</Update>

<Update label="v0.2.4">
  # Surgical Addon and Manifest Upgrades

  Two new subcommands for in-place updates that go through the same partial-stack endpoint as the UI. Atomic, locked, single git commit per invocation.

  ## Addon Upgrade

  * `ankra cluster addons upgrade <addon> --chart-version <version>` - bump the chart version.
  * `ankra cluster addons upgrade <addon> --set <key>=<value>` - mutate a single Helm values field (helm-style; supports dotted paths, `[idx]` indexing, and `[key=value]` list selectors such as `env[name=LOG_LEVEL].value`).
  * `ankra cluster addons upgrade <addon> --values-from-file <path>` - replace the entire values document.
  * `ankra cluster addons upgrade <addon> --registry-name`, `--registry-url`, `--registry-credential-name` - atomically retag the addon's registry.
  * `ankra cluster addons upgrade <addon> --namespace <new>` - destructive Helm reinstall in a new namespace; requires `--yes` or an interactive confirmation.

  `--set` and `--values-from-file` are mutually exclusive: `--set*` MUTATES the existing values document, `--values-from-file` REPLACES it. Use `--set-string` to force a value to remain a string, and `--set-file key=path` to load a value from a file.

  ## Manifest Upgrade

  * `ankra cluster manifests upgrade <manifest> --from-file <path>` - replace the manifest content.
  * `ankra cluster manifests upgrade <manifest> --manifest -` - read manifest YAML from stdin.
  * `ankra cluster manifests upgrade <manifest> --set <key>=<value>` - mutate a single path in the manifest YAML (helm-style; supports dotted paths, `[idx]` indexing, and `[key=value]` list selectors such as `containers[name=app].image`).
  * `ankra cluster manifests upgrade <manifest> --target-kind <kind> --target-name <name>` - with `--set`, pick which document to edit when the manifest holds multiple Kubernetes resources.
  * `ankra cluster manifests upgrade <manifest> --namespace <new>` - change the manifest's namespace.

  `--set*` MUTATE the existing manifest and are mutually exclusive with `--from-file` / `--manifest -`, which REPLACE it. Use `--set-string` to force a value to remain a string, and `--set-file key=path` to load a value from a file.

  ## Addon and manifest field selectors

  Both `addons upgrade` and `manifests upgrade` `--set` paths can address a list item by a stable field instead of a numeric index - for example `env[name=LOG_LEVEL].value=debug` or `spec.template.spec.containers[name=app].image=nginx:1.27`. A selector that matches nothing fails with a clear error rather than guessing.

  ## Common Options

  * `--cluster <name|id>` - defaults to the active selection.
  * `--stack <name>` - addons only, required when the same addon name exists in multiple stacks. Manifest names are globally unique on a cluster, so `manifests upgrade` has no `--stack` flag.
  * `--dry-run` - print before/after without writing.
  * `-o json|yaml` - machine-readable output (the `--dry-run` envelope is `{before, after, notices}`).

  ## Example: bump `image.tag` for the website addon

  ```bash theme={null}
  ankra cluster addons upgrade website \
    --set image.tag=1.0.146 \
    --cluster website-demo
  ```

  ## Example: bump a Deployment image tag in a manifest

  ```bash theme={null}
  ankra cluster manifests upgrade web \
    --set 'spec.template.spec.containers[name=app].image=nginx:1.27' \
    --cluster website-demo
  ```
</Update>

<Update label="v0.2.0">
  # Helm, Kubernetes Resources & Security Hardening

  Helm management, Kubernetes resource access, direct cluster selection, and client hardening.

  ## Helm Release Commands

  Commands for managing Helm releases in the active cluster:

  * `ankra cluster helm releases` - List Helm releases (`--namespace`, `--all-namespaces`, `--output json`)
  * `ankra cluster helm uninstall <release> --namespace <ns>` - Uninstall a Helm release

  ## Helm Registry Commands

  * `ankra helm registries list` - List Helm registries
  * `ankra helm registries get <name>` - Get registry details
  * `ankra helm registries create --name <name> --url <url>` - Create a registry
  * `ankra helm registries delete <name>` - Delete a registry

  ## Helm Credential Commands

  * `ankra helm credentials list` - List registry credentials
  * `ankra helm credentials create --name <name>` - Create a credential with secure prompts
  * `ankra helm credentials delete <name>` - Delete a credential

  ## Kubernetes Resource Commands

  Commands for accessing Kubernetes resources in the active cluster:

  * `ankra cluster pods` - List pods (`--namespace`, `--all-namespaces`, `--output json`)
  * `ankra cluster resources <kind>` - Get resources by kind (`--namespace`, `--name`, `--output json`)
  * `ankra cluster logs <pod>` - Stream pod logs (`--namespace`, `--container`, `--follow`, `--tail`, `--previous`)

  ## Cluster Selection & Info

  * `ankra cluster select <name>` - Select a cluster directly by name without the interactive picker
  * `ankra cluster info [name]` - Show cluster details (defaults to selected cluster; replaces `cluster get`)

  ## Security & Reliability

  * HTTP client timeouts and response body size limits
  * URL encoding for all API path and query parameters
  * Config file permissions restricted to owner-only (0600)
  * Machine ID hashed with SHA-256
  * Browser URL validation before opening
</Update>

<Update label="v0.1.129">
  # Node Groups, UpCloud & OVH

  Node group management commands and new UpCloud/OVH commands for cluster and credential management.

  ## Node Group Commands

  Available for all three providers (`hetzner`, `ovh`, `upcloud`):

  * `ankra cluster <provider> node-group list <cluster_id>` - List node groups
  * `ankra cluster <provider> node-group add <cluster_id> --name <name> --instance-type <type> --count <n>` - Add a group
  * `ankra cluster <provider> node-group scale <cluster_id> <group_name> <count>` - Scale a group
  * `ankra cluster <provider> node-group upgrade <cluster_id> <group_name> <instance_type>` - Upgrade instance type
  * `ankra cluster <provider> node-group delete <cluster_id> <group_name>` - Delete a group

  ## UpCloud Commands

  **Credentials**:

  * `ankra credentials upcloud list` - List UpCloud API credentials
  * `ankra credentials upcloud create --name <name>` - Create credential with secure token prompt
  * `ankra credentials upcloud ssh-key list` - List SSH key credentials
  * `ankra credentials upcloud ssh-key create --name <name> --generate` - Create SSH key

  **Clusters**:

  * `ankra cluster upcloud create` - Create an UpCloud cluster
  * `ankra cluster upcloud deprovision <cluster_id>` - Deprovision a cluster
  * `ankra cluster upcloud workers <cluster_id>` - Get worker count
  * `ankra cluster upcloud scale <cluster_id> <count>` - Scale workers
  * `ankra cluster upcloud k8s-version <cluster_id>` - Get Kubernetes version
  * `ankra cluster upcloud upgrade <cluster_id> <version>` - Upgrade Kubernetes version

  ## OVH Commands

  **Credentials**:

  * `ankra credentials ovh list` - List OVH API credentials
  * `ankra credentials ovh create --name <name> --project-id <id>` - Create credential with secure prompts
  * `ankra credentials ovh ssh-key list` - List SSH key credentials
  * `ankra credentials ovh ssh-key create --name <name> --generate` - Create SSH key

  **Clusters**:

  * `ankra cluster ovh create` - Create an OVH cluster
  * `ankra cluster ovh deprovision <cluster_id>` - Deprovision a cluster
  * `ankra cluster ovh workers <cluster_id>` - Get worker count
  * `ankra cluster ovh scale <cluster_id> <count>` - Scale workers
  * `ankra cluster ovh k8s-version <cluster_id>` - Get Kubernetes version
  * `ankra cluster ovh upgrade <cluster_id> <version>` - Upgrade Kubernetes version
</Update>

<Update label="v0.1.127">
  # OVH Cloud Support

  OVH Cloud commands for cluster and credential management.

  ## OVH Credential Commands

  * `ankra credentials ovh list` - List OVH API credentials
  * `ankra credentials ovh create --name <name> --project-id <id>` - Create credential with secure prompts
  * `ankra credentials ovh ssh-key list` - List SSH key credentials
  * `ankra credentials ovh ssh-key create --name <name> --generate` - Create SSH key

  ## OVH Cluster Commands

  * `ankra cluster ovh create` - Create an OVH cluster with configurable control planes, workers, networking, and gateway
  * `ankra cluster ovh deprovision <cluster_id>` - Deprovision a cluster
  * `ankra cluster ovh workers <cluster_id>` - Get worker count
  * `ankra cluster ovh scale <cluster_id> <count>` - Scale workers
  * `ankra cluster ovh k8s-version <cluster_id>` - Get Kubernetes version
  * `ankra cluster ovh upgrade <cluster_id> <version>` - Upgrade Kubernetes version
</Update>

<Update label="v0.1.125">
  # SOPS Encryption & API Tokens

  New SOPS encryption commands and API token management.

  ## SOPS Encryption

  * `ankra cluster sops-config` - Display the SOPS encryption configuration
  * `ankra cluster encrypt manifest <name> --key <key> -f <file>` - Encrypt a manifest key
  * `ankra cluster encrypt addon --name <addon> --key <key> -f <file>` - Encrypt an addon key
  * `ankra cluster decrypt manifest <name> -f <file>` - Decrypt a manifest

  ## API Tokens

  * `ankra tokens list` - List API tokens
  * `ankra tokens create <name>` - Create a token
  * `ankra tokens revoke <id>` - Revoke a token
  * `ankra tokens delete <id>` - Delete a revoked token
</Update>