CLI commands

The korva CLI is the orchestrator for everything — initialise workspaces, manage editors, run sentinel, activate licenses, manage teams, sync skills, and operate the vault. Built on Cobra, runs everywhere the binary runs.

Updated: 2026-05-15

The korva CLI is your primary interface to everything Korva. It’s a single Cobra binary that ships with the install. Run korva --help for the live tree.

Lifecycle commands

Command	Purpose
`korva init`	Initialise `~/.korva/`, generate IDs, write per-project `korva.config.json`. Add `--admin --owner [email protected]` to also generate `admin.key`.
`korva setup [editor]`	Auto-configure MCP for one or every supported IDE. Idempotent. Use `--all` to do them all in one shot.
`korva status`	Snapshot of the current install — vault running, license tier, project count, last sync.
`korva doctor`	13+ health checks. Use after install or when something feels off.
`korva update`	Self-update by downloading the latest GitHub release, verifying SHA256 and atomically replacing binaries.

Vault server

Command	Purpose
`korva vault start`	Start `korva-vault` in the background, write PID, poll `/healthz` until reachable (5 s timeout).
`korva vault stop`	Send SIGINT to the PID, remove `vault.pid`.
`korva vault status`	Process state + HTTP reachability.
`korva vault logs`	Print the path to `vault.log` for `tail -f`.
`korva vault clean [--dry-run] [--project NAME]`	Deduplicate observations using `GROUP BY (project, type, lower(trim(content)))`, keep the oldest. Works without the server running.

Sentinel

Command	Purpose
`korva sentinel install`	Install pre-commit + post-commit Git hooks in the current repo.
`korva sentinel check`	Run the validator over staged files without committing.
`korva sentinel run --hook=pre-commit`	Internal — invoked by the Git hook itself.

Cloud connect (Teams)

Command	Purpose
`korva connect <url> <key>`	Connect this workstation to your organization’s Korva Teams portal. Stores the endpoint and authenticates with the provided license key. Enables shared skills, private scrolls, and team analytics.
`korva connect --status`	Show current connection state, portal URL, and tier.
`korva connect --disconnect`	Remove the stored portal connection (data stays local).

Example: korva connect https://portal.korva.dev K0RVA-XXXX-XXXX-XXXX-XXXX

License

Command	Purpose
`korva license activate <key>`	POST to the licensing endpoint, verify the JWS RS256 token, persist to `~/.korva/license.key` (mode 0600), start the 24 h heartbeat.
`korva license status`	Tier, expiry, last heartbeat, grace remaining.
`korva license deactivate`	Release the seat (returns to Community tier, no data deleted).

Admin (requires admin.key)

Command	Purpose
`korva admin init`	Bootstrap admin.key on a fresh install.
`korva admin rotate-key`	Rotate admin.key (current key required via stdin for safety).

Lore

Command	Purpose
`korva lore list`	Show installed scrolls — curated and team.
`korva lore add`	Interactive scroll authoring (template, frontmatter, triggers).

Teams (requires admin.key)

Command	Purpose
`korva teams sync`	Pull the team profile from its private Git repo.
`korva teams status`	Active profile + override summary.
`korva teams list`	List teams managed on this instance.
`korva teams create "<name>" --owner <email>`	Create a team.
`korva teams members <team_id>`	List members.
`korva teams invite <email> --team <team_id>`	Generate an invite token (shown once).
`korva teams add-member <team_id> <email> [--role admin]`	Promote / add directly.
`korva teams remove-member <team_id> <email>`	Revoke membership.

Auth (team members)

Command	Purpose
`korva auth redeem <invite-token>`	Exchange an invite token for a `session_token`, persisted to `~/.korva/session.token` (mode 0600).
`korva auth status`	Show current session identity.
`korva auth logout`	Delete the session token locally and revoke remotely.

Hive

Command	Purpose
`korva hive push`	Flush the local outbox once.
`korva hive status`	Pending / sent / rejected / failed counts + worker state.
`korva hive enable / disable`	Toggle sync (writes config).
`korva hive retry`	Re-enqueue rows in `failed` status.
`korva hive rotate-key`	Generate a new 32-byte Hive API key.

Sync

Command	Purpose
`korva sync`	Combined: pull team profile + flush vault outbox + sync skills. Use `--vault`, `--profile`, `--skills` flags to scope.
`korva sync --vault --quiet`	Used by the post-commit Git hook.

Observations (CLI access to the vault)

Command	Purpose
`korva obs list [--project] [--type] [--limit]`	List observations.
`korva obs search <query> [--cloud]`	Full-text search (optionally including Hive).
`korva obs get <id>`	Print one by ULID.

Skills

Command	Purpose
`korva skills list`	List team-distributed skills.
`korva skills sync`	Pull updated skills from `/team/skills/sync` (delta).
`korva skills history <id>`	Show skill version history.
`korva skills hook install`	Add a `PreToolUse` hook in `~/.claude/settings.json` so Claude Code auto-syncs skills before each session.
`korva skills hook remove`	Remove the auto-sync hook.

Auto-update check

Every command runs an opportunistic, non-blocking GitHub releases check on its first invocation in 24 h. Set KORVA_NO_UPDATE_CHECK=1 to disable.