CLI usage¶

This page shows the day-to-day CLI patterns. The full subcommand and flag reference is generated from the Typer app and committed at cli_reference.md; refresh it with:

python docs/script/generate_reference_docs.py

For first-time setup, see quickstart.md.

Common commands¶

kneo config init --name research-agent-demo
kneo config show
kneo spec validate examples/research_agent.yaml
kneo spec lint examples/research_agent.yaml
kneo spec compile examples/research_agent.yaml
kneo spec migrate legacy_agent.yaml --output migrated_agent.yaml
kneo spec policy-report examples/research_agent.yaml --json
kneo spec validate examples/research_agent.yaml --env prod
kneo spec bundle sign examples/research_agent.yaml \
  --output bundles/research_agent.json \
  --approved-by release-manager --env prod
kneo spec bundle verify bundles/research_agent.json
kneo run examples/research_agent.yaml --input "Analyze Nvidia AI business"
kneo runs get <run_id>
kneo runs cancel <run_id>
kneo runs trace <run_id>
kneo runs checkpoints <run_id>
kneo runs replay <run_id>
kneo runs checkpoint-diff <run_id> --from-sequence 1 --to-sequence 3
kneo human get <continuation_id>
kneo human resume <continuation_id> --request-id <request_id> --approve

Talking to a service¶

For one-off service-backed calls, set environment variables:

export KNEO_SERV_API_KEY=<api-key>
kneo run examples/research_agent.yaml \
  --service-url http://127.0.0.1:8000 \
  --input "hello"

Profiles¶

For multiple service environments, store named profiles instead of re-typing URLs and tokens:

kneo config profile set local \
  --service-url http://127.0.0.1:8000 --api-key <api-key>
kneo config profile set staging \
  --service-url https://staging.example.com --api-key <api-key> --no-activate
kneo config profile list
kneo config profile use staging

kneo spec validate examples/research_agent.yaml --profile staging
kneo run examples/research_agent.yaml --profile staging --input "hello"
kneo runs get <run_id> --profile staging
kneo human list --profile staging

Profiles live at ~/.kneo_serv/profiles.json with owner-only file permissions. Set KNEO_SERV_PROFILES_PATH to use a different location (handy in tests). The CLI reports whether a profile is authenticated but never prints stored API keys.

Service-connection precedence is:

--service-url (plus the API key from --profile, when given).
An explicit --profile.
service.default_url from .kneo/config.yaml.
The currently active CLI profile.
Local in-process execution.

Retry, timeout, and idempotency¶

Service-backed CLI commands honor retry and timeout settings:

export KNEO_SERV_CLIENT_TIMEOUT=120
export KNEO_SERV_CLIENT_RETRIES=2
export KNEO_SERV_CLIENT_RETRY_BACKOFF_SECONDS=0.25

Transient failures (408, 429, 5xx, plus network errors) are retried. Authentication, authorization, validation, and not-found failures fail fast with a clear message.

For retry-safe POSTs, set a stable idempotency key:

export KNEO_SERV_IDEMPOTENCY_KEY=<stable-client-generated-key>

The service replays the original response for duplicate POST /runs or human-task resume requests that carry the same key and payload.

Spec migration¶

Use kneo spec migrate to convert older or unversioned YAML specs to the current version: v1 shape:

kneo spec migrate legacy_agent.yaml --output migrated_agent.yaml
kneo spec migrate migrated_agent.yaml --check --json

Migration currently supports unversioned specs, v0, and v1. Unsupported future versions fail fast rather than being guessed.

Spec linting¶

kneo spec lint runs the same validator pipeline as kneo spec validate but filters output to warnings and errors only (info-severity diagnostics are dropped) and exits non-zero if any are found. Use it as a CI gate to catch deprecated fields, unsafe imports, shorthand tool selection without explicit permissions, network/shell/ filesystem-write capabilities without an allow-list, and missing human approvals on privileged surfaces — without having to filter spec validate output by hand.

# CI gate — fails the build if the spec carries any warnings or errors
kneo spec lint examples/research_agent.yaml
echo "exit=$?"

# Machine-readable output with summary counts
kneo spec lint examples/research_agent.yaml --json

The JSON envelope is:

{
  "clean": false,
  "warning_count": 3,
  "error_count": 0,
  "diagnostics": [
    {"severity": "warning", "code": "W_TOOL_POLICY_UNRESTRICTED", "path": "...", "message": "...", "suggestion": "..."}
  ]
}

Lint is intentionally stricter than validate (which prints diagnostics but does not exit non-zero on warnings). For the full diagnostic list including info-severity items, use kneo spec validate instead.

Policy reports¶

kneo spec policy-report emits a structured governance report covering memory, tool permissions, guardrails, MCP imports, and human-review requirements:

kneo spec policy-report examples/research_agent.yaml --json
kneo spec policy-report examples/research_agent.yaml \
  --profile staging --json

The report includes validation diagnostics, so CI can block on errors while still surfacing warnings such as unrestricted network tools or missing human approval steps.

When project config declares environments.<name>.policy_enforcement, spec commands and run --env <name> enforce the selected environment after overlays and defaults are applied.

Spec bundles¶

kneo spec bundle sign produces an approved deployment bundle with a canonical spec digest and an HMAC signature:

export KNEO_SERV_SPEC_SIGNING_KEY=<deployment-signing-key>
kneo spec bundle sign examples/research_agent.yaml \
  --output bundles/research_agent.prod.json \
  --approved-by release-manager \
  --env prod
kneo spec bundle verify bundles/research_agent.prod.json

Verification fails if the bundle contents are edited after signing, or if a different signing key is used.