CLI Reference

Look up the main kimbap commands, flags, and examples in one place.

Version

kimbap --version

Print the CLI version. Release builds show the tagged version, and may also include build metadata like commit/date.

Example:

kimbap --version

Action execution

kimbap call <service>.<action>

Run an installed action by name.

Flags are derived from the action's input schema. Each flag corresponds to an input field defined in the service manifest. Required fields without defaults must be provided.

Syntax:

kimbap call <service>.<action> [--<arg> <value> ...]

Examples:

kimbap call github.list-repos --sort updated
kimbap call github.create-issue --owner acme --repo api --title "fix bug" --body "details"
kimbap call slack.post-message --channel C123 --text "hello"

kimbap search <query>

Search installed actions by keyword or description. Results match action names, descriptions, and service names.

Syntax:

kimbap search <query>

Examples:

kimbap search "send message"
kimbap search "list repos"
kimbap search refund

Action discovery

kimbap actions list

List all installed actions across all services.

Flags:

Examples:

kimbap actions list
kimbap actions list --service github
kimbap actions list --service stripe

kimbap actions describe <service>.<action>

Show the full schema for an action, including input field types, required fields, auth requirements, and risk level.

Syntax:

kimbap actions describe <service>.<action>

Example:

kimbap actions describe stripe.list-charges
kimbap actions describe github.create-issue

Service management

kimbap service install <file|name>

Install a service manifest. Accepts a path to a local YAML file or a built-in service name from the official registry.

Syntax:

kimbap service install <file|name>

Examples:

kimbap service install my-service.yaml
kimbap service install github
kimbap service install stripe

kimbap service generate

Generate a service manifest from an OpenAPI 3.x spec.

Remote OpenAPI URLs must use https://. Plain http:// is allowed only for localhost/loopback sources such as http://127.0.0.1:8080/openapi.yaml.

When --openapi points at a local file, relative file $ref patterns such as ./schemas/pet.yaml#/Pet are supported, including nested refs across split-file specs. Remote URL sources do not resolve external ref trees.

Syntax:

kimbap service generate --openapi <path-or-url> [--name <service>] [--tag <tag> ...] [--path-prefix <prefix> ...] [--output file.yaml] [--install]

Flags:

Examples:

kimbap service generate --openapi ./openapi.yaml
kimbap service generate --openapi ./openapi.yaml --output my-service.yaml  # split-file refs supported for local files
kimbap service generate --openapi https://api.example.com/openapi.yaml --output my-service.yaml
kimbap service generate --openapi http://127.0.0.1:8080/openapi.yaml --name local-api --install
kimbap service generate --openapi ./openapi.yaml --tag admin --path-prefix /v1/admin --output admin-api.yaml

When --install is set, the command installs the manifest instead of printing YAML. In text mode it prints an install success message; in JSON mode it returns a structured install payload.

kimbap service validate <file>

Parse and validate a service manifest without installing it. Reports all errors found, not just the first.

Catches:

• Schema errors and unknown fields
• Invalid or missing base_url
• Missing required top-level fields
• Duplicate argument names within an action
• Type mismatches in argument definitions
• Invalid risk level values

Syntax:

kimbap service validate <file>

Example:

kimbap service validate my-service.yaml

kimbap service list

List all installed services, their versions, and their action counts.

Example:

kimbap service list

kimbap service remove <name>

Uninstall a service manifest by name.

Syntax:

kimbap service remove <name>

Example:

kimbap service remove my-service

kimbap service export-agent-skill <name>

Export a SKILL.md file for a given service to stdout. This file is formatted for AI agent consumption and describes available actions, input schemas, and usage examples.

Syntax:

kimbap service export-agent-skill <name>

Example:

kimbap service export-agent-skill github
kimbap service export-agent-skill stripe > ./skills/stripe.md

Credential management

kimbap vault set <key>

Store a secret in the encrypted vault. Secrets are never accepted as inline CLI arguments to avoid shell history exposure.

Flags:

Examples:

printf '%s' "$TOKEN" | kimbap vault set github.token --stdin
kimbap vault set stripe.api_key --file ./key.txt

kimbap vault list

List vault key metadata: names, last-used timestamps, and last-rotated timestamps. Secret values are never shown.

Example:

kimbap vault list

kimbap vault rotate

Rotate a stored credential. Prompts for the new value via stdin or --file.

Syntax:

kimbap vault rotate <key>

Example:

printf '%s' "$NEW_TOKEN" | kimbap vault rotate github.token --stdin

kimbap link <service>

Link a service to vault credentials or an OAuth connector. kimbap will look up the correct vault keys or connector tokens when executing actions for that service.

Use --stdin or --file to supply a credential inline during the link step, skipping a separate vault set call.

Syntax:

kimbap link <service> [--stdin | --file <path>]

Flags:

Examples:

kimbap link github
kimbap link stripe
printf '%s' "$GITHUB_TOKEN" | kimbap link github --stdin
kimbap link stripe --file ./stripe-key.txt

OAuth connectors

kimbap auth list

Show connector health and token state for all linked providers. Includes expiry status and whether the token is valid.

Example:

kimbap auth list

kimbap auth status [provider]

Show connector health and token state.

• With a provider argument: show one provider.
• Without a provider argument: show all providers.

Syntax:

kimbap auth status
kimbap auth status <provider>

Example:

kimbap auth status notion
kimbap auth status slack

kimbap auth providers list

List all bundled OAuth providers available in the built-in registry.

Example:

kimbap auth providers list

kimbap auth connect <provider>

Authenticate with an OAuth provider. Starts the appropriate flow (device code or browser redirect) and persists the resulting token.

Bundled providers: canva, canvas, figma, notion, slack, stripe, zendesk, zoom.

Syntax:

kimbap auth connect <provider>

Example:

kimbap auth connect slack
kimbap auth connect notion

kimbap auth revoke <provider>

Revoke an active OAuth session and remove the stored token for that provider.

Syntax:

kimbap auth revoke <provider>

Example:

kimbap auth revoke github
kimbap auth revoke slack

Policy

kimbap policy set --file <path>

Load a policy document from a YAML file. Replaces the active policy entirely.

Syntax:

kimbap policy set --file <path>

Example:

kimbap policy set --file ./policy.yaml

Example policy document:

version: "1.0.0"
rules:
  - id: allow-github-read
    priority: 10
    match:
      agents: [repo-bot]
      actions: [github.list-repos, github.list-pull-requests]
    decision: allow

  - id: approve-stripe-refunds
    priority: 20
    match:
      agents: [billing-bot]
      actions: [stripe.create-refund]
    decision: require_approval

  - id: deny-destructive
    priority: 5
    match:
      risk: critical
    decision: deny

Policy decisions:

Match fields:

Rules are evaluated in ascending priority order. The first matching rule wins.

kimbap policy get

Print the active policy document to stdout.

Example:

kimbap policy get

Approval

kimbap approve list

List all pending approval requests with their IDs, action names, requesting agents, and creation times.

Example:

kimbap approve list

kimbap approve accept <id>

Approve a held action, allowing it to proceed.

Expired approvals and already-resolved approvals return distinct error codes so callers can distinguish between the two cases.

Syntax:

kimbap approve accept <id>

Example:

kimbap approve accept req_01HX...

Audit (Advanced)

kimbap audit tail

Show a recent snapshot of audit log entries (non-streaming). Error messages in audit records are capped at 256 characters.

Example:

kimbap audit tail

kimbap audit export

Export audit records for a required date range as newline-delimited JSON (or CSV).

Syntax:

kimbap audit export --from <date> --to <date> [--format jsonl|csv]

Accepted date formats for --from / --to: RFC3339 or YYYY-MM-DD.

Example:

kimbap audit export --from 2026-03-01 --to 2026-03-31
kimbap audit export --from 2026-03-01 --to 2026-03-31 --format csv > audit-202603.csv

Runtime modes

kimbap run -- <cmd>

Run an agent subprocess inside a kimbap-controlled environment. The subprocess gets no direct access to vault secrets. Credentials are injected server-side by the proxy or daemon, not passed through environment variables or files.

Syntax:

kimbap run -- <command> [args...]

Example:

kimbap run -- python agent.py
kimbap run -- node ./agent/index.js

kimbap proxy

Start an HTTP/HTTPS proxy that intercepts outbound requests, classifies them against installed action patterns, and injects credentials server-side before forwarding.

Route matching uses specificity-based priority: exact paths take precedence over parameterized paths, which take precedence over wildcard patterns.

Default listen address is 127.0.0.1:7788 (configurable via proxy_addr in config, or KIMBAP_PROXY_ADDR).

Example:

kimbap proxy

Then in the agent's environment:

export HTTPS_PROXY=http://127.0.0.1:7788
python agent.py

kimbap serve

Start a persistent HTTP server that exposes the action runtime over a local HTTP API.

Flags:

The /console route is disabled by default. Enable it via --console flag or by setting console.enabled: true in ~/.kimbap/config.yaml. Do not expose this endpoint on a network interface in production.

Examples:

kimbap serve
kimbap serve --addr 127.0.0.1:8080
kimbap serve --port 9000 --console

kimbap daemon (Advanced)

Start a persistent runtime daemon that keeps the execution pipeline warm to avoid cold-start overhead on every kimbap call. Exposes /call, /health, and /shutdown endpoints over a Unix domain socket.

Example:

kimbap daemon

Agent configuration

kimbap agents setup

Install global Kimbap discovery hints for detected AI agent environments.

• Default: installs global hints and runs service sync into the target project directory.
• Use --no-sync to skip the sync step.
• With --with-profiles: also installs project-level operating rules files.

Example:

kimbap agents setup
kimbap agents setup --with-profiles

kimbap agents sync

Sync installed services to detected agent skill directories. Generates a SKILL.md file per service in each discovered agent directory.

Example:

kimbap agents sync

kimbap agents status

Show the sync status for all known AI agent environments: which agents were detected, which skill files exist, and which are stale.

Example:

kimbap agents status

kimbap agents setup --with-profiles

Install global discovery hints and agent operating profiles. Writes a KIMBAP_OPERATING_RULES.md file into the target project directory (default .) under agent-specific subfolders.

Profiles installed per agent:

Example:

kimbap agents setup --with-profiles
kimbap agents setup --with-profiles --profile-dir /path/to/project

Code generation (Advanced)

kimbap generate ts

Generate TypeScript input interfaces for installed actions.

Flags:

Examples:

kimbap generate ts
kimbap generate ts --service github -o ./types/github.ts
kimbap generate ts --service stripe -o ./types/stripe.ts

kimbap generate py

Generate Python TypedDict input types for installed actions.

Flags:

Examples:

kimbap generate py
kimbap generate py --service stripe -o ./types/stripe.py
kimbap generate py --service github -o ./types/github.py

Other advanced commands

The following commands are hidden from kimbap --help and intended for advanced use cases. They are available but not required for normal operation.

kimbap token (Advanced)

Manage agent access tokens. Use kimbap token --help for full usage.

kimbap alias (Advanced)

Manage action aliases. Use kimbap alias --help for full usage.

kimbap completion (Advanced)

Generate shell completion scripts. Use kimbap completion --help for full usage.

Additional command families

These command groups are available in the CLI and are useful in day-to-day operations. Use each group's --help output for full flag coverage.

Status and inspection

• kimbap status
• kimbap actions describe <service>.<action>
• kimbap service outdated

Service lifecycle

• kimbap service enable <name>
• kimbap service disable <name>
• kimbap service remove <name>
• kimbap service update <name|all>
• kimbap service verify <name>
• kimbap service sign <path>
• kimbap service generate ...

Vault and links

• kimbap vault get <key>
• kimbap vault delete <key>
• kimbap link list

Policy and approvals

• kimbap policy eval --file <path>
• kimbap approve deny <id> --reason "..."

Auth and agents

• kimbap auth reconnect <provider>
• kimbap auth doctor <provider>
• kimbap auth providers describe <provider>
• kimbap agents uninstall-global

Setup and diagnostics

kimbap init

Bootstrap a fresh kimbap installation. Creates the data directory, initializes the vault, and optionally installs services.

In dev mode (--mode dev), a vault master key is auto-generated. In production, set KIMBAP_MASTER_KEY_HEX before running init.

Flags:

Examples:

kimbap init --services all
kimbap init --services all --with-agents
kimbap init --services all --with-agents --agents-project-dir /path/to/project
kimbap init --services github,stripe --force
kimbap init --no-services

kimbap doctor

Run environment diagnostics. Checks configuration file, data directory, vault status, services directory, and policy file. Reports pass/fail for each check with actionable error messages.

Example:

kimbap doctor

Configuration reference

Configuration is read from environment variables or ~/.kimbap/config.yaml. Environment variables take precedence over the config file.

Risk levels

Risk levels are declared per-action in service manifests. Policy rules can match on risk level to apply blanket decisions across action categories.

Approval hints are suggestions to the policy engine. Active policy rules always take precedence.