Metadata-Version: 2.4
Name: kamiwaza-cli
Version: 2.0.0
Summary: Operator CLI for Kamiwaza deployments (cross-substrate).
Author: Kamiwaza Engineering
License-Expression: Apache-2.0
Project-URL: Documentation, https://docs.kamiwaza.ai
Keywords: kamiwaza,cli,operator,diagnose,support-bundle
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: kamiwaza-sdk<1.5,>=1.4
Requires-Dist: click<9,>=8.3.3
Requires-Dist: authlib<2,>=1.9.1
Requires-Dist: cryptography<51,>=50.0.1
Requires-Dist: rich<16,>=13.7
Requires-Dist: PyYAML<7,>=6.0
Requires-Dist: jsonschema<5,>=4.20
Requires-Dist: dnspython<3,>=2.9.2
Requires-Dist: textual<9,>=8.0
Provides-Extra: k8s
Requires-Dist: kr8s<1,>=0.20; extra == "k8s"
Requires-Dist: dpkt<2,>=1.9; extra == "k8s"
Provides-Extra: dev
Requires-Dist: pytest<9,>=8.1; extra == "dev"
Requires-Dist: pytest-httpx<0.31,>=0.30; extra == "dev"
Requires-Dist: pytest-asyncio<0.24,>=0.23; extra == "dev"
Requires-Dist: pytest-cov<6,>=5.0; extra == "dev"
Requires-Dist: ruff<1,>=0.5; extra == "dev"
Requires-Dist: commitizen<4,>=3.20; extra == "dev"
Requires-Dist: pytest-playwright<1,>=0.4; extra == "dev"
Dynamic: license-file

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

```bash
uv tool install "kamiwaza-cli==2.0.0"
# or
pipx install "kamiwaza-cli==2.0.0"
```

Requires Python 3.11+.

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

```bash
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:

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

See [`docs/ui.md`](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

```bash
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`](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.

```bash
# 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)

```bash
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](https://github.com/kamiwaza-internal/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)

```bash
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

```bash
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:

```bash
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:

```bash
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.

```bash
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`](docs/commands.md).

## Documentation

- [`docs/getting-started.md`](docs/getting-started.md) — fresh laptop → first `kamiwaza diagnose`
- [`docs/commands.md`](docs/commands.md) — every subcommand, flag, exit code
- [`docs/support-bundle.md`](docs/support-bundle.md) — operator guide for the bundle pipeline
- [`docs/publishing-bundle-spec.md`](docs/publishing-bundle-spec.md) — publish a deployment-specific spec at the well-known path
- [`docs/oidc-client-setup.md`](docs/oidc-client-setup.md) — wire up the deployment's identity provider
- [`docs/runbooks/`](docs/runbooks/) — one runbook per canonical diagnose failure
- [`specs/`](specs/) — the spec-kit source of truth for every feature (`spec.md` / `plan.md` / `tasks.md` / `contracts/`)

## Development

```bash
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/`) are gated on
`KAMIWAZA_TEST_ENDPOINT` + `KAMIWAZA_TEST_TOKEN` per Constitution
Principle VII; 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/                 spec-kit source of truth (001–004)
tests/                 unit / integration / browser / perf / fixtures
docs/                  operator-facing reference + runbooks
.specify/              spec-kit templates + constitution
scripts/               developer scripts (fault sweeps, host-file verifier)
demo/                  local demo harness for the spec-003 dashboard
```

Design detail, hard rules, and the reuse contract live in
[`CLAUDE.md`](CLAUDE.md). The constitution is at
[`.specify/memory/constitution.md`](.specify/memory/constitution.md).

Platform installation and upgrades use the Deploy repository's native install interface
with a KKS-prepared substrate. The former `kamiwaza cluster sync` command has been
removed (ENG-11941); see [cluster installation guidance](docs/commands.md#platform-installation).

## License

Apache-2.0.
