Kimbap CLI Reference

Reference for the kimbap CLI. Covers the most commonly used commands and their flags.

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>

Execute a registered action.

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 alias set <shortcut> <service>.<action>

Create a standalone shortcut command (no kimbap call prefix needed at runtime). Many catalog services are installed with default shortcuts automatically; use this when you want to add or override one manually.

Syntax:

kimbap alias set <shortcut> <service>.<action>

Examples:

kimbap alias set geosearch open-meteo-geocoding.search
geosearch --name "San Francisco"

To remove it:

kimbap alias remove geosearch

kimbap search <query>

Search installed actions by keyword or description. Matches against 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:

Flag	Description
`--service <name>`	Filter results to a single service

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 <name|path-to-yaml|url>

Install a service manifest. Accepts a path to a local YAML file, an HTTPS URL, or a catalog service name from the service catalog.

Syntax:

kimbap service install <name|path-to-yaml|url> [--force] [--no-shortcuts]

Examples:

kimbap service install github
kimbap service install my-service.yaml
kimbap service install https://example.com/service.yaml
kimbap service install stripe
kimbap service install github --force
kimbap service install github --no-shortcuts

Install sets up eligible shortcut aliases by default. Use --no-shortcuts to skip.

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:

Flag	Description
`--openapi <path-or-url>`	OpenAPI 3.x spec file path or URL
`--name <service>`	Override the generated service name
`--tag <tag>`	Include only operations with a matching OpenAPI tag. Repeatable
`--path-prefix <prefix>`	Include only operations whose path starts with the given prefix. Repeatable
`--output <file>`	Write the generated YAML to a file instead of stdout
`--install`	Install the generated manifest immediately after generation

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 installed services, or list all catalog services with install/enable status. Output includes shortcut aliases per service in both text (SHORTCUTS column) and JSON (shortcuts field). With --available, JSON output also includes catalog metadata such as description, adapter, actions, auth_required, and triggers.

Syntax:

kimbap service list [--available]

Flags:

Flag	Description
`--available`	List all catalog services and show whether each one is installed/enabled

Example:

kimbap service list
kimbap service list --available

kimbap service search <query>

Search built-in catalog services before installation. Matches against service names, descriptions, trigger metadata, and action names/descriptions.

Syntax:

kimbap service search <query> [--limit N]

Flags:

Flag	Description
`--limit <n>`	Maximum number of matches to return. `0` means no limit

Examples:

kimbap service search github
kimbap service search "issue management"
kimbap service search geocoding --limit 5

kimbap service describe <name>

Describe a built-in catalog service before installation. Shows adapter type, auth summary, trigger metadata, action summaries, gotchas, recipes, and install status.

Syntax:

kimbap service describe <name>

Examples:

kimbap service describe github
kimbap service describe open-meteo-geocoding

kimbap service outdated

List installed services that are behind the current version in the service catalog.

Syntax:

kimbap service outdated

Example:

kimbap service outdated

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 link <service> is the recommended way to connect a service. It handles both API key storage and OAuth flows. Use vault set and auth connect for advanced or scripted scenarios.

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:

Flag	Description
`--stdin`	Read the secret value from stdin
`--file <path>`	Read the secret value from a file

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:

Flag	Description
`--stdin`	Read the credential value from stdin during linking
`--file <path>`	Read the credential value from a file during linking

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:

Decision	Behavior
`allow`	Action proceeds immediately
`deny`	Action is blocked and returns an error
`require_approval`	Action is held until a human approves it

Match fields:

Field	Description
`agents`	List of agent identifiers. Supports glob patterns.
`services`	List of service names. Supports glob patterns.
`actions`	List of `service.action` identifiers. Supports glob patterns.
`risk`	Risk level: `low`, `medium`, `high`, or `critical`

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:

Flag	Default	Description
`--addr`	config/default	API listen address override (e.g. `127.0.0.1:8080`)
`--port`	`0` (disabled)	Port override; when omitted, address comes from config/default
`--console`	disabled	Enable the embedded operations console at `/console`

The /console route is disabled by default. Enable it via --console flag or by setting console.enabled: true in your resolved config path ($XDG_CONFIG_HOME/kimbap/config.yaml or ~/.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.

Supported agent kinds: claude-code, opencode, codex, cursor, openclaw, nanoclaw.

Default: installs global hints only.
Use --sync --dir <path> to also run service sync into a project directory.
With --with-profiles: also installs project-level operating rules files.

Example:

kimbap agents setup
kimbap agents setup --sync --dir .
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.

Use --agent to scope sync to specific kinds: claude-code, opencode, codex, cursor, openclaw, nanoclaw, generic.

Example:

kimbap agents sync
kimbap agents sync --agent openclaw --dir "$HOME/.openclaw/workspace"
kimbap agents sync --agent nanoclaw --dir /path/to/nanoclaw

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.

Includes Cursor, OpenClaw, and NanoClaw when their environments are present.

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:

Agent	Install location
`claude-code`	`.claude/KIMBAP_OPERATING_RULES.md`
`opencode`	`.opencode/KIMBAP_OPERATING_RULES.md`
`cursor`	`.cursor/KIMBAP_OPERATING_RULES.md`
`openclaw`	`KIMBAP_OPERATING_RULES.md` (OpenClaw workspace root)
`nanoclaw`	`.claude/KIMBAP_OPERATING_RULES.md`
`codex`	`.codex/KIMBAP_OPERATING_RULES.md`

Example:

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

Note: generic is supported in kimbap agents sync (project-level sync), not in kimbap agents setup.

Code generation (Advanced)

kimbap generate ts

Generate TypeScript input interfaces for installed actions.

Flags:

Flag	Description
`--service <name>`	Limit output to a single service
`-o <path>`	Write output to a file instead of stdout

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:

Flag	Description
`--service <name>`	Limit output to a single service
`-o <path>`	Write output to a file instead of stdout

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 intended for advanced use cases.

kimbap token (Advanced)

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

kimbap completion (Advanced)

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

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:

Flag	Description
`--mode <mode>`	Runtime mode: `dev`, `embedded`, or `connected`
`--services <list>`	Comma-separated catalog service names, or `all`, `recommended` (legacy alias: `starter`), `select`
`--no-services`	Skip service installation entirely
`--no-shortcuts`	Skip automatic shortcut alias setup during init service installation
`--with-console`	Enable the `/console` route in the generated config
`--with-agents`	Run `agents setup` and `agents sync` after init (current directory by default)
`--agents-project-dir <path>`	Override project directory for agent sync
`--force`	Overwrite an existing config file

Examples:

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

Service lifecycle commands (service install, enable, disable, remove, update) also attempt automatic agent sync for the current project when agent configs are detected in text output mode. Use kimbap agents sync --dir <path> for explicit sync targeting, and for JSON output workflows.

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 discovered config file ($XDG_CONFIG_HOME/kimbap/config.yaml when set, otherwise ~/.kimbap/config.yaml). Environment variables take precedence over the config file.

Variable	Default	Description
`KIMBAP_DATA_DIR`	`~/.kimbap`	Data directory for the database, vault, and audit logs
`KIMBAP_MASTER_KEY_HEX`	auto-generated in dev mode	Hex-encoded 32-byte vault master key
`KIMBAP_DEV`	`false`	Dev mode: relaxed security checks and verbose logging
`KIMBAP_DATABASE_DRIVER`	`sqlite`	Database driver: `sqlite` or `postgres`
`KIMBAP_DATABASE_DSN`	`$KIMBAP_DATA_DIR/kimbap.db`	Database connection string
`KIMBAP_LOG_LEVEL`	`info`	Log verbosity: `trace`, `debug`, `info`, `warn`, `error`

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.

Level	Meaning	Approval hint
`low`	Read-only, no side effects, fully reversible	Auto-approve suggested
`medium`	Writes data, limited blast radius	Auto-approve suggested
`high`	Destructive or financially significant	Policy-dependent
`critical`	Irreversible or high blast radius	Approval recommended

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

FilesExpand file tree

cli-reference.md

Latest commit

History

cli-reference.md

File metadata and controls

Kimbap CLI Reference

Version

kimbap --version

Action execution

kimbap call <service>.<action>

kimbap alias set <shortcut> <service>.<action>

kimbap search <query>

Action discovery

kimbap actions list

kimbap actions describe <service>.<action>

Service management

kimbap service install <name|path-to-yaml|url>

kimbap service generate

kimbap service validate <file>

kimbap service list

kimbap service search <query>

kimbap service describe <name>

kimbap service outdated

kimbap service export-agent-skill <name>

Credential management

kimbap vault set <key>

kimbap vault list

kimbap vault rotate

kimbap link <service>

OAuth connectors

kimbap auth list

kimbap auth status [provider]

kimbap auth providers list

kimbap auth connect <provider>

kimbap auth revoke <provider>

Policy

kimbap policy set --file <path>

kimbap policy get

Approval

kimbap approve list

kimbap approve accept <id>

Audit (Advanced)

kimbap audit tail

kimbap audit export

Runtime modes

kimbap run -- <cmd>

kimbap proxy

kimbap serve

kimbap daemon (Advanced)

Agent configuration

kimbap agents setup

kimbap agents sync

kimbap agents status

kimbap agents setup --with-profiles

Code generation (Advanced)

kimbap generate ts

kimbap generate py

Other advanced commands

kimbap token (Advanced)

kimbap completion (Advanced)

Setup and diagnostics

kimbap init

kimbap doctor

Configuration reference

Risk levels