Skip to main content

kamiwaza-cli

The kamiwaza operator CLI — a standalone cross-substrate command-line tool for Kamiwaza deployments. Talks to control-plane, data-store, identity, ingress, model-serving, and batch-execution components through the kamiwaza-sdk; adds OIDC login and local context management, a k9s-style operator cockpit (kamiwaza ui) with matching one-shot resource verbs, model acquisition + provider configuration, cluster PKI/DNS tooling, and a configurable support-bundle pipeline with an offline diagnostic dashboard viewer on top.

Install

Install from PyPI as an isolated tool, pinned to a release:

uv tool install "kamiwaza-cli==2.0.1"
# or
pipx install "kamiwaza-cli==2.0.1"

Requires Python 3.11+.

Kamiwaza engineers with access to the source repository can install it for development:

git clone git@github.com:kamiwaza-mde/kamiwaza-cli.git
cd kamiwaza-cli
python -m pip install -e ".[dev]"

Optional extras

The interactive operator console (kamiwaza ui) is part of the base install. Kubernetes-native resource kinds stay behind an extra so the base stays lean:

uv tool install "kamiwaza-cli[k8s]==2.0.1"    # + Kubernetes-native kinds (orchestrated)
# or
pipx install "kamiwaza-cli[k8s]==2.0.1"

See docs/ui.md. The k8s extra adds in-process Kubernetes access (no external tools) and only activates on orchestrated deployments with usable cluster credentials.

Quickstart

kamiwaza login                         # OIDC flow against the deployment
kamiwaza context list                  # see registered deployments
kamiwaza status                        # one-page cluster status (exit 0 = HEALTHY)
kamiwaza diagnose                      # health check across components
kamiwaza logs control-plane --since 10m
kamiwaza support-bundle collect -o bundle.tar.gz
kamiwaza support-bundle view bundle.tar.gz    # offline dashboard in your browser
kamiwaza ui                            # interactive k9s-style cockpit

See docs/getting-started.md for the workstation-to-first-diagnose walkthrough.

Login

kamiwaza login is OAuth 2.0 Authorization Code + PKCE against your deployment's Keycloak realm. On a workstation it opens a browser; you sign in with your Keycloak credentials, approve, and the browser closes. Token + refresh-token are cached on disk (~/.kamiwaza/contexts/<name>/token.json, mode 0600); subsequent commands silently re-use them and silently refresh as needed.

# 1. Register the deployment (once per workstation):
kamiwaza context add prod --endpoint https://kamiwaza.prod.example/ --use

# 2. Log in:
kamiwaza login
# → browser opens → Keycloak login page → enter credentials → approve.

# 3. Use any authenticated command — no per-command auth dance:
kamiwaza diagnose
kamiwaza logs control-plane --since 10m

One-time deployment setup: register the CLI's OIDC client

kamiwaza login needs a public OIDC client named kamiwaza-cli registered in your deployment's Keycloak realm. Production deployments should ship this in their installer (Helm chart / Terraform); for ad-hoc deployments you can register it once by hand. In the bundled debug container this is automatic — see "Debug container shortcut" below.

Option A — Keycloak Admin UI (90 seconds)

  1. Open https://<your-deployment>/admin/master/console/ and log in as admin (password in the kamiwaza/keycloak-admin cluster secret).
  2. Top-left dropdown → switch realm to kamiwaza.
  3. Clients → Create client:
    • Client type: OpenID Connect
    • Client ID: kamiwaza-cli
    • Next
  4. Capability config:
    • Client authentication: OFF (public client; required for PKCE)
    • Authentication flow: tick Standard flow and Device authorization grant; untick the rest
    • Next
  5. Login settings:
    • Valid redirect URIs: http://127.0.0.1:*/callback, http://localhost:*/callback
    • Web origins: +
    • Save
  6. Open the new client → Advanced tab → Proof Key for Code Exchange Code Challenge Method: S256 → Save.

Option B — kcadm (one shell-out, scriptable)

KCADMIN=$(kubectl -n kamiwaza get secret keycloak-admin -o jsonpath='{.data.password}' | base64 -d)
KCPOD=$(kubectl -n kamiwaza get pod -l app.kubernetes.io/name=keycloak -o name | head -1)

kubectl -n kamiwaza exec "$KCPOD" -- /opt/keycloak/bin/kcadm.sh \
    config credentials \
    --server http://localhost:8080 \
    --realm master --user admin --password "$KCADMIN"

kubectl -n kamiwaza exec "$KCPOD" -- /opt/keycloak/bin/kcadm.sh \
    create clients \
    --target-realm kamiwaza \
    --set clientId=kamiwaza-cli \
    --set publicClient=true \
    --set 'redirectUris=["http://127.0.0.1:*/callback","http://localhost:*/callback"]' \
    --set 'webOrigins=["+"]' \
    --set standardFlowEnabled=true \
    --set 'attributes={"oauth2.device.authorization.grant.enabled":"true","pkce.code.challenge.method":"S256"}'

Debug container shortcut

When kamiwaza login runs inside the Kamiwaza debug container (jump pod, ephemeral kubectl debug, or DaemonSet shell), the container's kamiwaza wrapper auto-provisions the kamiwaza-cli client on the realm if it's missing. It uses the pod's existing RBAC to read the kamiwaza/keycloak-admin secret and exec into the Keycloak pod's kcadm.sh. Idempotent (probes the realm first), runs once per pod lifetime, no operator interaction. Outside the debug pod the wrapper is a transparent passthrough — see Options A/B above for your workstation.

From a headless environment (SSH, in-pod, no browser)

kamiwaza login --device-code
# → prints "visit https://kamiwaza.test/realms/kamiwaza/device?user_code=XXXX-XXXX"

Open that URL on any device with a browser, enter the code, approve. The CLI is polling and finishes automatically.

Multiple contexts

kamiwaza context add prod --endpoint https://kamiwaza.prod.example/
kamiwaza context add staging --endpoint https://stg.example/

kamiwaza --context prod diagnose      # one-off override
kamiwaza context use staging          # switch the active context

Tokens are scoped per context — logging in against staging doesn't disturb prod credentials.

TLS — private CAs and dev clusters

For deployments using a private CA, pin the bundle on the context once:

kamiwaza context add prod \
    --endpoint https://kamiwaza.prod.example/ \
    --ca-bundle /etc/ssl/private/kamiwaza-prod-ca.pem \
    --use

Stored at ~/.kamiwaza/contexts/<name>/ca.pem (mode 0600), auto-loaded for every command — no KAMIWAZA_CA_BUNDLE env var dance. Mirrors aws --ca-bundle and gcloud --certificate-authority.

For local-dev clusters with self-signed certs you don't want to bother pinning:

kamiwaza context add dev \
    --endpoint https://kamiwaza.dev.local/ \
    --insecure-skip-tls-verify --use

kubectl-style flag — disables verification entirely for that context. Production contexts should always pin a bundle instead.

Agent and script contract

kamiwaza schema describes the installed command tree without credentials, configuration, or a platform connection. Use kamiwaza schema context list to inspect one command's required arguments, options, types, and choices. The JSON schema_version is 1.0; it is an installed-CLI discovery format, not a claim of full CLI Spec or CLI Agent Spec conformance.

kamiwaza schema
kamiwaza schema context list
kamiwaza --output json --non-interactive --no-color context list

Place global flags before the command path. Commands with a platform target also accept --context NAME. JSON successes write data to stdout. JSON errors write a single envelope to stderr with a stable kind, summary, next_step, and exit_code; always check process status. Some diagnostic and support-bundle commands use nonzero outcomes for findings, not failed changes.

--non-interactive refuses terminal prompts and editors. Without a TTY, commands requiring input also refuse; supply existing command-specific flags only after reviewing consequences. There is no global --yes, --dry-run, or --no-pager: no pager runs automatically. The schema does not certify a command's side effects, result shape, or retry safety. Inspect the command's help and current target state before a mutation; never retry uncertain writes blindly. Never pass credentials as CLI arguments.

Commands

Command Purpose
kamiwaza schema [path ...] Discover installed commands and flags offline as JSON
kamiwaza login / logout OIDC login (Auth Code + PKCE or --device-code); discard tokens (--all)
kamiwaza context * Register / switch between multiple deployments
kamiwaza status / events One-page cluster status (exit 0 = HEALTHY); recent Kubernetes Warning events
kamiwaza diagnose Run the built-in health checks across canonical components
kamiwaza dns check|resolve Read-only DNS troubleshooting; resolve a name with the cause
kamiwaza logs <component> Stream logs from a named component
kamiwaza restart <component> Restart a component (live-integration-tested)
kamiwaza kinds / get / describe / edit / delete / action Universal resource verbs over every kind the cockpit manages
kamiwaza model search|pull|status Acquire models — search a hub, download weights, or register a provider model
kamiwaza provider add|list|show|remove Configure model providers (e.g. AWS Bedrock)
kamiwaza certs * Cluster PKI: inventory, renew, rotate-ca, install, trust anchors, TLS test
kamiwaza user * Identity-management operations against the deployment's user surface
kamiwaza support-bundle collect|view|analyze|list-* Redact-aware bundle pipeline + offline dashboard viewer
kamiwaza ui Interactive command center (k9s-style TUI)
kamiwaza version CLI + SDK version info

Full reference: docs/commands.md.

Documentation

Development

python -m pip install -e ".[dev]"
pytest tests/unit/kamiwaza_cli                   # default test suite
pytest -m browser tests/browser                  # dashboard Playwright tests (requires `playwright install chromium`)
ruff check kamiwaza_cli tests/unit/kamiwaza_cli
ruff format kamiwaza_cli tests/unit/kamiwaza_cli

Integration tests (tests/integration/kamiwaza_cli/) need KAMIWAZA_TEST_ENDPOINT and KAMIWAZA_TEST_TOKEN; they are skipped by default.

Architecture

The CLI is a single Python package (kamiwaza_cli/) installed as the kamiwaza console script. Entry point is kamiwaza_cli.cli:main.

Layout at the repo root:

kamiwaza_cli/          Python package source
specs/                 feature specifications
tests/                 unit / integration / browser / perf / fixtures
docs/                  operator-facing reference + runbooks
scripts/               developer scripts (fault sweeps, host-file verifier)
demo/                  local demo harness for the spec-003 dashboard

The former kamiwaza cluster sync command has been removed; platform installation and upgrades are outside this CLI. See cluster installation guidance.

License

Apache-2.0.

Metadata

Release files for kamiwaza-cli 2.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kamiwaza-cli 2.0.1
File Size Uploaded Provenance Actions
kamiwaza_cli-2.0.1.tar.gz 667.4 kB With provenance Details for kamiwaza_cli-2.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kamiwaza-cli 2.0.1
File Interpreter ABI Platform Actions
kamiwaza_cli-2.0.1-py3-none-any.whl Python 3 none any Details for kamiwaza_cli-2.0.1-py3-none-any.whl

Total release size: 1.5 MB

Release files / kamiwaza_cli-2.0.1.tar.gz

Download URL kamiwaza_cli-2.0.1.tar.gz
Size 667.4 kB
Tags Source
SHA-256 checksum
How to use checksums
119328aefa21d1db2418346b1bddd3a75829fbfcfee915d8d2e98c3b898b75f2
BLAKE2b-256 checksum
How to use checksums
e0693a676afaea759100b3349af1b2cffa63dc64db4ffd6e650b265427aa2411
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / kamiwaza_cli-2.0.1-py3-none-any.whl

Download URL kamiwaza_cli-2.0.1-py3-none-any.whl
Size 810.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5c1a95bea90a1b045d6281c6cf277930137d2eeec6510de6f507c36da5b87221
BLAKE2b-256 checksum
How to use checksums
badac16ac9a850bf36c9eca556177e2e522538eb54fa1a325812373f779bcae2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for kamiwaza-cli 2.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for kamiwaza_cli-2.0.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.0.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page