Skip to main content

The Katonic CLI

The Katonic CLI is a small Python tool, installed as the katonic-admin command, for the people who run a self-hosted installation. The shorter katonic command belongs to the Python SDK and is not this tool. It verifies air-gap bundles, applies delta bundles, and carries catalog, pricing and telemetry updates between a running platform and Katonic. It is not a client for the public API: it has no chat, search or agent commands, never sends a kapi_ key, and plays no part in a developer's own calls. For the public API use the reference with any HTTP client; for tools inside an AI client use the Katonic MCP Server.

Who can use it: the team that operates the cluster. Day-one and day-two operations, including building and loading air-gap bundles, are done with ktctl, the platform operator's own tool, which the help centre documents under Install without internet access.

Install​

The tool lives in the platform repository as the katonic-cli package and is not published to a package index. Install it from a checkout of the repository:

pip install ./sdks/katonic-cli
katonic-admin --version

It needs Python 3.11 or later. It installs click and rich; without rich it prints plain text. Do not run pip install katonic: that name belongs to an older Katonic SDK from a previous generation of the product, not to this tool.

Commands​

CommandWhat it does
katonic-admin verify-bundle <bundle.tar.gz>Checks an air-gap bundle before deployment: the tarball opens, its manifest is present and is valid JSON with version, components and bundle_type, every image file the manifest lists is in the bundle, and each listed SHA-256 matches. --manifest names a different manifest file; --strict fails on warnings, such as no checksums to verify.
katonic-admin diff-manifest --from <version> --to <version>Prints the components upgraded, added and removed between two versions as a table, or as JSON with --output json.
katonic-admin apply-delta <delta.tar.gz>Applies a delta bundle: checks that the file is a tarball, imports each image archive with ctr images import, runs helm upgrade katonic ./chart in the namespace (katonic unless --namespace says otherwise) and waits up to ten minutes, then waits for the rollout with kubectl. --dry-run prints the steps instead; --skip-verify skips the check; --kubeconfig, or the KUBECONFIG variable, selects the cluster.
katonic-admin update-mcp-catalog <catalog.json>Sends each MCP server entry of a catalog file to the admin API, one request per entry. The file is a list of entries or an object with a servers list.
katonic-admin update-providers <pricing.json>Posts a provider pricing file, in the format of LiteLLM's model prices and context window file, to the admin API's provider sync.
katonic-admin export-telemetryReads usage metrics, error rates, published agents and models from the admin API and writes them to a JSON file, telemetry.json unless --output says otherwise, for Katonic support. User ids, email addresses, names and message content are replaced with hashes. --days records the window the export covers.

The three commands that talk to the platform take --api-url (the KATONIC_API_URL variable; http://localhost:8000 by default) and --api-key (the KATONIC_API_KEY variable, required), which is sent as a bearer token. The two update commands accept --dry-run, which lists what would be sent.

Limits and behaviour​

  • On the current build, diff-manifest prints a representative table for any pair of versions rather than comparing the two versions' manifests; the components it names are fixed.
  • apply-delta expects the chart at ./chart in the working directory and the ctr, helm and kubectl binaries on the path. It checks only that the file is a tarball before applying it, so run verify-bundle first.
  • On the current build the admin API has no routes at the paths the catalog, provider and telemetry commands call, so those commands cannot complete against a live platform; --dry-run shows what they would send. A connected platform receives catalog and pricing updates through OpsHub's catalog sync, and an air-gapped one through its seed bundle; see OpsHub, releases and licensing.
  • The katonic login command belongs to the Python SDK, not to this tool. The tool on this page has no login command and never stores an API key; put the key in your own configuration or environment instead.

Describes the platform as of .

Was this page helpful?