Commands

This reference covers the public commands and options in CLI v1.1.1. Internal recording hooks and watcher entry points are omitted. Square brackets mark optional arguments; angle brackets mark values to replace.

For your first installation, follow Setup CLI. For everyday agent workflows, start with Session recap and recall or Working with hosted agents.

Help and shared options

kcap help
kcap --help
kcap <command> --help
kcap --version

Option or command	Behavior
`help`, `--help`, `-h`	Show the top-level command list when used immediately after `kcap`. `kcap help <command>` still shows top-level help.
`<command> --help`, `<command> -h`	Show that command’s embedded help where available. Subcommand arguments do not change which help page is selected. For harness usage in v1.1.1, use `kcap harness help`; its `--help` route has no embedded page.
`--version`, `-v`	Print the CLI version when used immediately after `kcap`.
`--server-url <url>`	Override the resolved server URL for the invocation. Takes precedence over `KCAP_URL`, profile selection, and repository configuration. `setup` and `profile add` also use this value when saving configuration.
`--no-update-check`	Suppress the automatic update lookup/notice for this invocation. This is separate from explicitly running `kcap update`.

Put the command first and keep its required positional arguments in the documented order. v1.1.1 does not remove shared options before command-specific parsing: a --server-url value can be mistaken for a positional argument, and commands with strict parsers can reject shared flags. Prefer KCAP_URL for a server override when using such commands, especially session commands with an omitted ID. There is no global --profile option; use KCAP_PROFILE to override profile resolution. See Configuration & profiles for the complete precedence rules.

Setup and auth

`setup`

Configure a server, sign in, choose visibility, install detected agent integrations, name the daemon, and optionally import history.

kcap setup [<tenant>] [options]

<tenant> must immediately follow setup. A workspace slug expands to https://<tenant>.kcap.ai; a URL or host is used as supplied. Without a server argument, interactive setup discovers your workspaces. Supported servers can continue setup in the browser. See Setup CLI for the walkthrough.

Option	Behavior
`--server-url <url>`	Configure an existing server. Takes precedence over the positional tenant.
`--org <name>`	Organization name for a new hosted workspace. Requires `--slug`.
`--slug <slug>`	Permanent hostname for the new workspace, `<slug>.kcap.ai`. Requires `--org`. Lowercased and trimmed; 1–40 letters, digits, or single internal hyphens; reserved names are rejected.
`--no-prompt`	Use supplied values and defaults, install detected integrations, and import eligible history from the current repository. Requires a server argument, or `--org` and `--slug`. Authentication can still require browser or device-code approval.
`--github`	Use GitHub for workspace discovery instead of organization SSO. For an explicit server, its advertised authentication provider determines sign-in.
`--device`	Use a device code for SSO or GitHub sign-in. Redirected input also selects device-code sign-in; during an interactive browser sign-in, press `d` to switch.
`--default-visibility <value>`	With `--no-prompt`, choose `private`, `project`, `org_public`, or `public`; default `org_public`. Interactive setup obtains this choice from the browser or terminal.
`--daemon-name <name>`	With `--no-prompt`, set the daemon name; default is the lowercase OS username. Interactive setup prompts for the name.
`--use-provider-api-key <value>`	With `--no-prompt`, retain or scrub provider API keys for headless agent calls. Accepts `true`, `1`, `yes`, `on`, or `false`, `0`, `no`, `off`. Omission preserves the profile setting, initially `false`. See the version-specific restriction below.
`--skip-import`	Skip the terminal import offer and the automatic current-repository import under `--no-prompt`.
`--plugin-scope <value>`	Legacy Claude scope: `user` uses the default; `project` writes at the current Git root and requires a Git working tree; `skip` aliases `--skip-claude-hooks`. Prefer `plugin install --project` for project installs.

--org and --slug cannot be combined with a server argument or --github. They create a workspace only for an account that does not already have one; an unavailable or invalid slug ends the run. Non-interactive creation also requires --no-prompt.

In v1.1.1, setup applies --use-provider-api-key only when the corresponding ANTHROPIC_API_KEY or OPENAI_API_KEY is present and that agent’s hooks have not been skipped. Otherwise it preserves the existing value. Use kcap config set use_provider_api_key true or false to change the setting directly.

Agent installation defaults to user scope. These flags opt out of individual components; a command-line opt-out also takes precedence over a browser selection.

Option	Component skipped
`--skip-claude-hooks`	Claude Code plugin installation.
`--skip-codex-hooks`	Codex hooks and associated setup.
`--skip-codex-network-access`	Codex sandbox network allowlist changes. MCP registration can still update `~/.codex/config.toml`.
`--skip-cursor-hooks`	Cursor capture hooks.
`--skip-cursor-mcp`	Cursor MCP registration.
`--skip-copilot-hooks`	Copilot CLI capture hooks.
`--skip-copilot-mcp`	Copilot CLI MCP registration.
`--skip-copilot-instructions`	Copilot CLI steering instructions.
`--skip-gemini-hooks`	Gemini CLI capture hooks.
`--skip-gemini-mcp`	Gemini CLI MCP registration.
`--skip-gemini-instructions`	Gemini CLI steering instructions.
`--skip-kiro-hooks`	Kiro capture agent installation.
`--skip-kiro-mcp`	Kiro MCP registration.
`--skip-kiro-skills`	Kiro-specific skills.
`--skip-pi-hooks`	Pi capture extension.
`--skip-pi-mcp`	Pi MCP bridge extension.
`--skip-pi-instructions`	Pi steering instructions.
`--skip-opencode-hooks`	OpenCode capture plugin.
`--skip-opencode-mcp`	OpenCode MCP registration.
`--skip-opencode-instructions`	OpenCode steering instructions.
`--skip-antigravity-hooks`	Antigravity capture plugin.
`--skip-antigravity-mcp`	Antigravity MCP registration.
`--skip-antigravity-instructions`	Antigravity steering instructions.
`--skip-antigravity-skills`	Antigravity-specific skills.

The terminal’s final import step requires a Git repository with a resolvable origin and satisfied authentication requirements. In --no-prompt mode it imports that repository’s history automatically; add --skip-import to opt out.

`login`, `logout`, and `whoami`

kcap login [--discover] [--github] [--device]
kcap logout
kcap whoami

Command or option	Behavior
`login`	Sign in to the configured server using its advertised authentication provider. With no configured server, discover your workspaces and save the chosen workspace as the active profile.
`login --discover`	Run workspace discovery even when a server is already configured.
`login --github`	Select GitHub for discovery instead of organization SSO. Does not override an explicitly configured server’s provider.
`login --device`	Use device-code sign-in. Redirected input does this automatically; interactive browser sign-in can switch with `d`.
`logout`	Delete locally stored credentials for all profiles, including legacy credentials. No command-specific options.
`whoami`	Show the effective profile’s stored identity, provider, expiry, and server, then check whether that server accepts the stored token. Does not refresh it. No command-specific options.

whoami exits 1 when credentials are missing, rejected, or issued for another server. It exits 0 when the server accepts them, when the server needs no authentication, or when verification is inconclusive because the server or endpoint is unavailable. Check its message as well as its exit code.

Tokens are stored per profile in ~/.config/kcap/tokens/<profile>.json, or under KCAP_CONFIG_DIR when set. Most authenticated operations refresh expired credentials automatically. See Machine credentials for unattended authentication.

`status`

kcap status [--no-update-check]

Report CLI version/update availability, server reachability, authentication, each agent integration, and daemon state. It also identifies detected agents that have not been configured for capture. The global --no-update-check option suppresses the version lookup. v1.1.1 produces text output and has no JSON mode.

Harness detection and reminders

kcap harness list
kcap harness dismiss <vendor> [<vendor> ...]
kcap harness dismiss --all
kcap harness reset <vendor> [<vendor> ...]
kcap harness reset --all

Vendor IDs are claude, codex, cursor, copilot, gemini, kiro, pi, opencode, and antigravity.

Subcommand	Options and behavior
`list`	Show detected, configured, and dismissed state for every supported agent. No command-specific options or JSON mode.
`dismiss`	Stop setup reminders for the named agents. `--all` dismisses only agents currently detected but unconfigured; it does not preemptively dismiss agents installed later.
`reset`	Clear dismissal and previous-offer state for the named agents so they can be offered again. `--all` clears every saved agent entry.

These commands manage reminders, not integrations. Use plugin install to configure capture, or kcap config set disable_harness_nudge true to disable all harness setup reminders for the profile.

Session lookup

List sessions

kcap sessions
kcap sessions --all --mine
kcap sessions --repo acme/api --limit 50 --json
kcap sessions --touching src/app.ts

Option	Meaning
`--active`, `--ended`, `--all`	Choose one session state. Default: `--active`.
`--repo <owner/name\|hash>`	Repository name or 16-character hexadecimal repository hash. Defaults to the current checkout’s origin.
`--mine`	Only sessions owned by you.
`--touching <path>`	Match recorded Edit/Write attempts containing this path. This does not cover every possible edit, such as changes made through a shell command.
`--limit <n>`	Number of results, from 1 to 100. Default: 20.
`--json`	Print JSON instead of a table.

Read a recap or transcript

kcap recap [sessionId]
kcap recap --repo
kcap recap --chain --full [sessionId]
kcap recap --per-turn <sessionId>
kcap recap --get-turn <N> <sessionId>

The default recap shows the stored plan, summary, and per-turn outline. For recap, errors, validate-plan, and eval, an omitted session ID is resolved from KCAP_SESSION_ID, then CODEX_THREAD_ID. Pass one explicitly when running outside an agent session.

Option	Meaning
`--repo`	Recent session summaries for the current repository; no session ID needed.
`--full`	Read the full transcript instead of the summary.
`--chain`	Include the continuation chain; can be combined with `--full`.
`--per-turn`	List turns with their indexes and summaries.
`--get-turn <N>`	Read the full transcript for the turn index returned by `--per-turn`.

Use a session ID or meta-session slug for normal recap and error lookup. The per-turn commands address one concrete session; use its session ID. Choose repository, per-turn, or ordinary recap mode separately.

Errors and plan evidence

kcap errors [sessionId]
kcap errors --chain [sessionId]
kcap validate-plan [sessionId]

errors extracts tool-call errors; --chain includes continuation sessions. validate-plan collects the recorded plan, task status, and work evidence for an agent to assess. It has no command-specific options.

More: Session recap and recall, Errors and plan validation.

Titles and summaries

kcap set-title "Fix the checkout regression"
kcap generate-whats-done <sessionId>
kcap generate-whats-done <sessionId> --codex

These commands normally support the recording integrations. set-title changes the current session’s title, resolving its identity only from KCAP_SESSION_ID or CODEX_THREAD_ID; it does not take a session ID argument. Titles longer than 120 characters are shortened.

generate-whats-done requires an explicit session ID before any options. It uses local Claude to generate and store a summary; --codex uses Codex instead. Diagnostics go to ~/.config/kcap/logs/<sessionId>-whatsdone.log (under $KCAP_CONFIG_DIR when overridden).

Recording control

One session

kcap hide [sessionId]
kcap disable [sessionId]

hide makes the session owner-only while recording continues. disable stops recording and deletes its server data, including recorded subagent data; deletion is irreversible and does not delete the local agent transcript. Neither command asks for confirmation. Both accept a session GUID, dashed or dashless, or resolve it from the agent environment when omitted; meta-session slugs are not accepted.

Allowed and ignored directories

kcap allow <path>
kcap allow --list
kcap allow --remove <path>
kcap ignore <path>
kcap ignore --list
kcap ignore --remove <path>

Both commands update the active profile. allow limits capture to the listed directories and their descendants; an empty list permits all paths. ignore excludes a directory and its descendants. --list shows entries and --remove removes one. Paths can use . or ~.

These rules apply to live capture and imports. Ignore rules take precedence. If allowed_repos is also configured, a session must match both the allowed directory and repository rules.

More: Capture scope, Visibility and sharing.

Importing past sessions

kcap import                                      # interactive scope picker
kcap import --discover                           # inspect local history without uploading
kcap import --discover --json
kcap import --repo . --claude --codex
kcap import --repo acme/api --repo acme/web --yes
kcap import --org acme --since 2026-01-01 --yes
kcap import --all --private --yes

Choose one scope: --all, --org, or one or more --repo arguments. An interactive run can choose a scope in the picker. Non-interactive imports require both an explicit scope and --yes.

Option	Meaning
`--all`	All repositories discovered in local history.
`--org [owner]`	Repositories with this Git remote owner. Without a value, reuse the owner remembered for the profile, or choose one interactively. This is a repository owner, not a Capacitor profile name.
`--repo <owner/name>`	Import one repository; repeat to select several. `--repo .` and `--repo current` select the current checkout’s origin.
`--yes`, `-y`	Skip confirmation. Does not choose a scope.
`--private`	Make imported sessions owner-only.
`--claude`, `--codex`, `--cursor`, `--copilot`, `--gemini`, `--kiro`, `--pi`, `--opencode`, `--antigravity`	Select history sources. Combine flags to include several; with none, use all available sources.
`--since <YYYY-MM-DD>`	Only sessions starting on or after this date.
`--cwd <path>`	Filter by recorded working directory, within the selected scope.
`--session <id>`	Filter to one session, within the selected scope.
`--min-lines <n>`	Minimum transcript line count. Default: 15.
`--skip-title`	Skip local title generation for Claude and Codex imports. Other sources do not run this local title generation.
`--generate-summaries`	Also generate what’s-done summaries for supported sessions using locally installed Claude or Codex.
`--reimport`	Re-upload OpenCode sessions despite the local import ledger, for example after deleting server data. Has no effect on other sources.
`--discover`	Report local history without uploading; no server configuration, login, or scope is required. Vendor filters still apply. Reports available date windows rather than filtering the report with `--since`.
`--json`	Machine-readable discovery output. Requires `--discover`; it is not an upload output mode.

Allow and ignore rules also apply. Re-running an import resumes from server watermarks; OpenCode additionally uses its local ledger.

OpenCode reads ~/.local/share/opencode/opencode.db. Its first import downloads a small SQLite native library into ~/.cache/kcap; set KCAP_SQLITE_NATIVE_BASE_URL to use a mirror. Antigravity imports both GUI and agy CLI history under ~/.gemini; these transcripts do not include per-generation cost.

More: Import your history.

Remap moved working directories

kcap remap <from> <to>
kcap remap --list
kcap remap --remove <from>
kcap remap '~/dev/worktrees/*/api' ~/dev/api

Remaps let imports attribute an old transcript directory to its current repository. They are stored globally across profiles. --list shows mappings; --remove removes the exact stored source pattern. Adding a mapping does not itself import anything.

The source can be a directory prefix or contain one * spanning exactly one path segment. Quote patterns so the shell does not expand them. The most specific match wins, with literal paths preferred over wildcard patterns on a tie. Remaps apply even if the old path still exists and do not chain.

More: Renamed repo directories.

Evaluations and review

kcap eval [sessionId]
kcap eval --model opus --chain [sessionId]
kcap eval --questions safety,tests_written [sessionId]
kcap eval --skip efficiency [sessionId]
kcap eval --list-questions
kcap review <pr-url-or-owner/repo#N>

eval runs a local LLM judge against recorded work and stores the result. The question catalog comes from the server.

Option	Meaning
`--model <name>`	Claude judge model: `haiku`, `sonnet`, or `opus`. Default: `sonnet`.
`--chain`	Evaluate the full continuation chain.
`--threshold <bytes>`	Tool-result compaction threshold. Server default: 2,000 bytes; capped at 200,000.
`--questions <csv>`	Include the named question IDs or categories. Categories: `safety`, `plan_adherence`, `quality`, `efficiency`.
`--skip <csv>`	Exclude the named question IDs or categories. Mutually exclusive with `--questions`.
`--list-questions`	Print the current catalog and exit; no session ID required.

review opens a local Claude review with MCP context for a pull request or merge request. It takes a GitHub/GitLab URL or owner/repo#N and has no command-specific options. For an independent hosted reviewer and repeated review rounds, use Flows.

More: Evaluations, PR review.

Curation and skills

Prefer Docs and skills for reviewed guidance delivered on demand. Run the following commands inside a Git repository with an origin remote.

kcap skills sync
kcap skills sync --dry-run
kcap curate apply
kcap curate apply --dry-run
kcap curate apply --yes

Command / option	Meaning
`skills sync`	Synchronize this repository’s approved, server-managed skills into user-level agent skill directories. Removes only previously managed skills withdrawn by the server.
`skills sync --dry-run`	Preview changes without writing files.
`skills sync --auto`	Quiet, throttled mode used by session-start hooks; refreshes at most once per six hours. For a manual refresh, omit it.
`curate apply`	Preview and confirm write-back of promoted guidelines into managed blocks in `CLAUDE.md` and/or `AGENTS.md`.
`curate apply --dry-run`	Preview write-back without changing files or prompting.
`curate apply --yes`, `curate apply -y`	Apply without confirmation.

Automatic skill refresh is opt-in through kcap config set skills.auto_sync true for Claude session start. Use Curation write-back for rules that belong in repository instruction files.

Projects

`repos`

kcap repos
kcap repos add <path>
kcap repos remove <path>

Manage the local paths offered in the daemon’s launch dialog. The bare command lists paths by most recent use. Paths can be relative, including .; add requires an existing directory. remove removes the saved entry, not the directory. There are no command-specific options.

`projects` and `project`

kcap projects
kcap project <slug>

projects lists the projects you can see, including repository/member counts and your role. project shows metadata, repositories, and members; owners and administrators also see pending invites and join requests. Both require Team or Enterprise and have no command-specific options.

Daemon

The daemon connects your machine to Capacitor and hosts coding agents. kcap daemon manages that background process; kcap agent manages the coding agents it runs. Dashboard launches use separate worktrees. A local kcap agent start uses your current directory unless you add --worktree. See Hosted agents and daemons and Working with hosted agents.

`daemon start`, `stop`, `restart`, and `status`

kcap daemon start [options]
kcap daemon stop [--name <name>] [--yes]
kcap daemon restart [--name <name>] [--when-idle | --force]
kcap daemon status [--name <name>]

start runs in the foreground by default. Separate names let several daemons run on one machine. For commands that resolve a default daemon name, precedence is --name, KCAP_DAEMON_NAME, the profile’s daemon.name, then the lowercase OS username (with machine name and daemon as fallbacks).

Start option	Description
`--name <name>`	Name this daemon. Uses the resolution order above when omitted.
`--server-url <url>`	Override the configured server URL.
`--max-agents <n>`	Maximum concurrent hosted coding agents. Nonnegative integer; `0` means unlimited. Uses profile `daemon.max_agents`, otherwise `5`, when omitted. In v1.1.1, `KCAP_MAX_AGENTS` overrides even an explicit flag.
`--log-file <path>`	Write logs to this file instead of the console. Detached starts use the configuration directory’s `daemon.log` by default.
`--log-level <level>`	`trace`, `debug`, `information`, `warning`, `error`, `critical`, or `none` (case insensitive). Aliases: `trce`, `dbug`, `info`, `warn`, `fail`, `crit`. A valid flag overrides `KCAP_DAEMON_LOG_LEVEL`; otherwise the default is `information`.
`-d`, `--detach`	Start in the background and log to a file.

Command	Option	Description
`stop`	`--name <name>`	Stop only this daemon. Without it, stop the sole daemon immediately or ask before stopping several.
`stop`	`--yes`, `-y`	Skip the confirmation when stopping several daemons.
`restart`	`--name <name>`	Restart only this daemon; otherwise target all running daemons.
`restart`	`--when-idle`	Queue the restart until no hosted agents or evaluation are running; return immediately.
`restart`	`--force`	Restart immediately, including while busy; running agents are terminated. Takes precedence over `--when-idle` if both are supplied.
`status`	`--name <name>`	Show one daemon; otherwise list all known running daemons and installed services.

A bare restart runs immediately only when idle. status includes the running daemon’s version and any pending restart. After an update, macOS and Linux daemons detect the replacement binary and restart when idle; Windows processes use the old version until restarted.

`daemon logs` and `daemon doctor`

kcap daemon logs
kcap daemon doctor [--clean]

logs prints the last 50 lines of daemon.log, plus the startup/stderr capture daemon.out.log when it contains output. It has no command-specific options in v1.1.1: it does not accept a daemon selector or follow the log. Service installs use separate daemon-<name>.log files.

doctor reports daemon lock/PID state, installed services, duplicate Claude MCP registrations, and stale registered binary paths.

Option	Description
`--clean`	Remove stale daemon entries and canonical duplicate Claude MCP registrations. Held locks and customized same-name MCP entries are preserved. Stale MCP binary paths are reported for repair through setup/update.

`daemon service`

Install the daemon as a per-user service that starts at login and restarts after a crash: launchd on macOS, systemd on Linux, or a Scheduled Task on Windows. Installation captures the shell’s PATH and relevant environment and pins the selected profile.

kcap daemon service install [options]
kcap daemon service uninstall [--name <name>]
kcap daemon service start [--name <name>] [--verify]
kcap daemon service stop [--name <name>]
kcap daemon service ensure [--name <name>] [--profile <profile>] [--json]
kcap daemon service status [--name <name>] [--json]

Applies to	Option	Description
All service actions	`--name <name>`	Select the service/daemon name; uses the daemon-name resolution order above.
`install`, `ensure`	`--profile <profile>`	Pin this profile; defaults to the resolved profile.
`install`	`--max-agents <n>`	Persist the agent limit in the service command. Nonnegative integer; `0` is unlimited. Otherwise use daemon configuration defaults.
`install`	`--no-start`	Register the service without starting it. Incompatible with `--verify`.
`install`, `start`	`--verify`	macOS/launchd only. Wait for readiness and service ownership; install also verifies the version. Failure rolls back the attempted service operation and exits nonzero.
`install`	`--replace`	Take over an existing service registration through the verified transaction. Requires `--verify`.
`install`	`--retire <id>`	Remove an old service ID during a rename. Requires `--replace --verify`; the old unit must use the same profile and differ from the new ID. A live daemon under the new name remains a conflict.
`ensure`, `status`	`--json`	Print a machine-readable result. `status` exits nonzero when service state cannot be determined.

uninstall stops and removes the service. stop leaves it installed: it can return at the next login or with service start.

ensure installs a missing service, starts a stopped service, or reports that it is already enabled. New installations through ensure seed launch consent to prompt. On macOS, it requires a resolvable profile and uses readiness/ownership verification. Ambiguous or conflicting states are reported without taking them over. Linux and Windows use ordinary install/start and report verified: false in JSON.

`daemon shim ensure`

kcap daemon shim ensure [--json]

Check whether kcap resolves in your login shell. If it is missing on macOS, offer an administrator prompt to link /usr/local/bin/kcap to this CLI and check the shell again. An existing conflicting entry is not overwritten. Installation is unsupported on other platforms; an already working command is still recognized.

Option	Description
`--json`	Print the outcome and reason as JSON. Success requires the shell to resolve `kcap`.

`daemon consent`

Consent controls launches requested through the server, including dashboard agents, PR reviews, and flow participants. The daemon owner is always allowed. Local kcap agent start requests bypass this policy. For other requesters, the first matching rule wins; otherwise the policy’s default applies. prompt denies when approval times out or no approval UI is attached.

kcap daemon consent show [--name <name>]
kcap daemon consent set-default <allow|deny|prompt> [--name <name>]
kcap daemon consent allow [match options] [--name <name>]
kcap daemon consent deny [match options] [--name <name>]
kcap daemon consent remove <index> [--name <name>]
kcap daemon consent log [-n <count>] [--name <name>]

show displays the default, prompt timeout, and indexed rules. allow and deny append rules. remove uses the zero-based index printed by show. These operations require a running daemon; log reads the decision log directly and works while it is stopped. Use show to inspect the effective default: existing policies are retained, ordinary unseeded daemons default to allow, and service ensure seeds new policies to prompt.

Applies to	Option	Description
All consent commands	`--name <name>`	Select the daemon; uses the daemon-name resolution order above.
`allow`, `deny`	`--requester <user>`	Match a requester identity. Omitted means any requester.
`allow`, `deny`	`--kind <kind>`	Match `agent`, `review`, or `review-flow`. Omitted means any kind.
`allow`, `deny`	`--repo <path>`	Match an exact repository path or a prefix glob such as `/work/*`. Omitted means any repository.
`allow`, `deny`	`--vendor <vendor>`	Match the vendor token, normalized to lowercase. Omitted means any vendor.
`log`	`-n <count>`	Number of lines to print. Positive integer; defaults to `20` (also used for invalid/nonpositive input). No long alias.

allow and deny require at least one match option. Every supplied field must match. There is no CLI option for changing the prompt timeout.

`daemon reviewer affirm`

kcap daemon reviewer affirm --vendor <vendor> [--name <name>]

Record the installed reviewer build as the minimum version the selected daemon may run. Versions at or above that floor are admitted. Running the command with an older installed build deliberately lowers the floor. Restart a running daemon to apply the change. Affirming a version does not enable or disable the reviewer.

Option	Description
`--vendor <vendor>`	Required. `kiro`, `gemini`, `antigravity`, or `opencode` (case insensitive). The installed binary must report an identifiable version.
`--name <name>`	Select the daemon whose minimum version is recorded; uses the daemon-name resolution order above.

These unattended reviewers are enabled by default when available. Their daemon environment opt-out variables are KCAP_KIRO_UNATTENDED_REVIEWER, KCAP_GEMINI_UNATTENDED_REVIEWER, KCAP_ANTIGRAVITY_UNATTENDED_REVIEWER, and KCAP_OPENCODE_UNATTENDED_REVIEWER; set the relevant variable to 0 to disable it. A service captures its environment at installation, so reinstall the service after changing such a variable.

Hosted agents

`agent`

kcap agent
kcap agent ls [--daemon <name>]
kcap agent start <claude|codex> [options] [-- <agent-args>]
kcap agent attach <agent-id> [--daemon <name>]
kcap agent stop <agent-id> [--force] [--daemon <name>]
kcap agent stop --all [--yes] [--force] [--daemon <name>]

The local agent commands are Unix-only in v1.1.1. agent without a subcommand lists agents. start requires a configured server and automatically starts the selected daemon if needed. The local start path supports claude and codex; other harnesses can have separate dashboard or reviewer support.

Applies to	Option	Description
`start`, `ls`, `attach`, `stop`	`--daemon <name>`	Select a daemon. Otherwise uses `KCAP_DAEMON_NAME`, the profile’s daemon name, and the normal daemon-name fallbacks.
`start`	`--worktree`	Create a throwaway Git worktree. Without it, run in your current directory.
`start`	`--private`	Omit hosted-agent registration and output streaming to the web UI; answer permissions in the terminal. This does not disable ordinary session recording by installed hooks.
`start`	`-d`, `--detach`	Start without attaching and print the agent ID. Otherwise attach your terminal.
`start`	`--`	Pass everything after this separator to the vendor CLI. Put Capacitor options before it.
`stop`	`--all`	Stop this daemon’s agents, including private agents. Cannot be combined with an agent ID.
`stop`	`--force`	Permit stopping a review or review-flow agent, or include them under `--all`. Otherwise they are protected.
`stop`	`--yes`, `-y`	Skip the confirmation for `--all`.

Agent IDs accept a unique prefix. Detach with Ctrl-Q, then d; the daemon keeps the agent running. attach gives a read-only terminal view for review and review-flow agents. Stopping a flow participant with --force leaves the flow without that participant.

Machine credentials

`machine create`, `list`, and `revoke`

kcap machine create <name> [--visibility <visibility>] [--role <role>]
kcap machine list
kcap machine revoke <service-id>

Create and manage identities for headless recording. These commands require Capacitor administrator rights. Creation also requires the organization owner or administrator role for issuing the credential. Machines cannot be administrators or project members. See Machine credentials for runner setup.

Create option	Description
`--visibility <visibility>`	`private`, `org_public`, or `public`. Defaults to a compatible profile `default_visibility`, otherwise `org_public`. Selects the value printed in runner setup instructions; it does not configure the runner remotely.
`--role <role>`	Requested Capacitor role; default `member`. The server enforces the permitted role and does not grant a machine administrator privileges.

create prints the secret once to stdout and setup information, including the client ID, to stderr. Store it securely when creating the machine; it cannot be retrieved later. The runner uses KCAP_CLIENT_ID, KCAP_CLIENT_SECRET, and KCAP_URL, with its visibility configured on the runner itself. list provides the service ID used by revoke; revoke disables that identity’s authentication. list and revoke have no command-specific options.

MCP servers (for agents)

`mcp`

These commands start stdio MCP servers for an agent or MCP client. They are normally registered by setup or plugin installation and require access to a configured, authenticated Capacitor server.

Command	Purpose
`kcap mcp review [--owner <owner> --repo <repo> --pr <number>]`	PR implementation context.
`kcap mcp judge --session <session-id>`	Evaluation facts for a specific session; registered separately when needed.
`kcap mcp sessions`	Search and inspect recorded sessions.
`kcap mcp flows [--driver <vendor>]`	Start and manage hosted review and other agent flows.
`kcap mcp memory`	Search and manage repository, project, and organization memory.
`kcap mcp workitems`	Declare work-item attachments, relationships, and unfinished work.
`kcap mcp plans`	Record and inspect plan documents and tasks.
`kcap mcp analytics`	Query the governed Insights views. Requires Team or Enterprise.

Applies to	Option	Description
`review`	`--owner <owner>`	Repository owner for the startup PR context. Supply with `--repo` and `--pr`.
`review`	`--repo <repo>`	Repository name for the startup PR context. Supply with `--owner` and `--pr`.
`review`	`--pr <number>`	Integer PR number. The explicit startup context is used only when all three PR options are supplied and the number parses; otherwise resolve from Git.
`judge`	`--session <session-id>`	Required session to bind.
`flows`	`--driver <vendor>`	Integration registration hint for the harness running this MCP server, independent of the reviewer. Recognized tokens: `claude`, `codex`, `cursor`, `copilot`, `gemini`, `kiro`, `opencode`, `antigravity`. Normally stamped by the integration or inferred from Claude/Codex session environment.

Start repository-aware servers from the relevant repository directory. The commands without options in the table have no command-specific CLI flags. See The installed harness for automatic registration and Shared memory for memory workflows.

mcp flow-result is an internal server launched for hosted flow participants; it has no user-facing CLI options.

Hooks and plugin

`plugin install` and `plugin remove`

kcap plugin install [<target>] [--project] [--if-installed] [options]
kcap plugin remove [<target>] [--project]

With no target flag, these commands manage the Claude Code plugin. Target flags are mutually exclusive: run the command separately for each agent.

Target flag	Integration
No target flag	Claude Code plugin, including its packaged hooks, skills, and MCP configuration.
`--codex`	Codex hooks, shared agent skills, and user-level MCP registration. Installation also configures sandbox network access unless skipped.
`--cursor`	Cursor hooks, MCP registration, and shared agent skills.
`--copilot`	Copilot CLI hooks, MCP registration, steering instructions, and shared agent skills.
`--gemini`	Gemini CLI hooks and MCP entries merged into its settings, steering instructions, and shared agent skills.
`--kiro`	Clone the default Kiro agent with capture hooks, select it as default, register MCP servers, and install Kiro-specific skills. Requires `kiro-cli` for cloning. Removal restores the previous default agent.
`--pi`	Pi capture extension, MCP bridge extension, steering instructions, and shared agent skills.
`--opencode`	OpenCode capture plugin, MCP registration, steering instructions, and shared agent skills.
`--antigravity`	Antigravity capture plugin, MCP registration, steering instructions, and skills under `~/.gemini/skills`.
`--skills`	Only the packaged skills under `~/.agents/skills/`, without hooks or MCP registration.

Option	Applies to	Behavior
`--project`	`install`, `remove`	Use `.claude/settings.local.json` or `.codex/hooks.json` under the current directory for Claude or Codex hooks. Run at the repository root for a repository-wide install. Skills remain user-wide; other targets ignore this option.
`--if-installed`	`install`	Refresh only a previously installed target, identified by an installation marker or existing integration. Used during upgrades; fresh systems are left alone and refresh failures do not fail npm installation. Automatic upgrade refreshes use user scope.
`--skip-codex-network-access`	`install --codex`	Skip sandbox network policy changes. MCP registration still runs. The refresh-only path also leaves network policy unchanged.
`--skip-cursor-skills`	`install --cursor`	Skip shared skills.
`--skip-cursor-mcp`	`install --cursor`	Skip MCP registration.
`--skip-copilot-skills`	`install --copilot`	Skip shared skills.
`--skip-copilot-mcp`	`install --copilot`	Skip MCP registration.
`--skip-copilot-instructions`	`install --copilot`	Skip steering instructions.
`--skip-gemini-skills`	`install --gemini`	Skip shared skills.
`--skip-gemini-mcp`	`install --gemini`	Skip MCP registration.
`--skip-gemini-instructions`	`install --gemini`	Skip steering instructions.
`--skip-kiro-mcp`	`install --kiro`	Skip MCP registration.
`--skip-kiro-skills`	`install --kiro`	Skip skills under `~/.kiro/skills`.
`--skip-pi-skills`	`install --pi`	Skip shared skills.
`--skip-pi-mcp`	`install --pi`	Skip the MCP bridge extension.
`--skip-pi-instructions`	`install --pi`	Skip steering instructions.
`--skip-opencode-skills`	`install --opencode`	Skip shared skills.
`--skip-opencode-mcp`	`install --opencode`	Skip MCP registration.
`--skip-opencode-instructions`	`install --opencode`	Skip steering instructions.
`--skip-antigravity-mcp`	`install --antigravity`	Skip MCP registration.
`--skip-antigravity-instructions`	`install --antigravity`	Skip steering instructions in the shared `~/.gemini/GEMINI.md`.
`--skip-antigravity-skills`	`install --antigravity`	Skip skills under `~/.gemini/skills`.

Restart the affected agent after installation. Codex also requires you to trust its hooks: accept the next CLI launch prompt or use /hooks; in the desktop app, use Settings → Hooks.

plugin remove --codex also removes shared agent skills and legacy ~/.codex/skills/kcap-* entries. User-scope removal unregisters Codex MCP servers; project-scope removal preserves the user-wide servers. Codex sandbox network policy is retained. Use plugin remove --skills to remove shared skills independently. See The installed harness for integration locations and the packaged skill inventory.

Configuration and profiles

`profile`

kcap profile add <name> --server-url <url> [--remote <pattern> ...] [--no-probe]
kcap profile list
kcap profile show [<name>]
kcap profile remove <name>

Subcommand or option	Behavior
`add <name>`	Create a profile. The name must not already exist; adding does not activate it.
`add --server-url <url>`	Required server URL.
`add --remote <pattern>`	Repeatable Git remote pattern for automatic profile selection. Matches the complete normalized `host/owner/repo`, case-insensitively; `` matches within one path segment. For example, `github.com/acme/`.
`add --no-probe`	Skip the server reachability check. Default: probe the URL before saving; a failed probe warns but still saves.
`list`	List profiles, server URLs, remote patterns, and the global active profile. No command-specific options.
`show [<name>]`	Show one profile’s details; omission selects the stored global active profile. No command-specific options.
`remove <name>`	Remove a profile and its local directory bindings. The `default` profile cannot be removed. Removing the active profile selects `default`. No command-specific options.

Profile creation and config set server_url normalize URLs and trim trailing slashes. Without a scheme, the probe tries HTTPS then HTTP. With --no-probe, loopback hosts default to HTTP and other hosts to HTTPS.

`use`

kcap use <profile-name> [--global] [--save]

The profile must already exist. By default, bind it locally to the Git repository root, or the current directory outside a repository.

Option	Behavior
`--global`	Set the global active profile instead of creating a local directory binding. Existing repository bindings still take precedence when resolving a profile.
`--save`	Also write the profile name and server URL to `.kcap.json` at the Git root or current directory for team sharing. Can be combined with `--global`.

See Configuration & profiles for resolution order and .kcap.json.

`config`

kcap config show
kcap config set <key> <value> [--no-probe]
kcap config unset <key>

show prints the complete saved configuration, its path, and effective telemetry state. It has no command-specific options. set and unset modify the stored global active profile, regardless of repository selection or KCAP_PROFILE; use kcap use <name> --global first to choose their target. telemetry is machine-wide.

--no-probe applies to config set server_url and skips the reachability check. The only keys accepted by unset are flows.reviewer_vendor and skills.auto_sync.

Key	Values and default	Meaning
`server_url`	URL; initially unset	Capacitor server.
`daemon.name`	String; default OS username	Default hosted-agent daemon name.
`daemon.max_agents`	Integer; default `5`; `0` means unlimited	Maximum concurrent hosted coding agents.
`daemon.claude_path`	Nonempty executable path/name; default `claude`	Claude executable used by the daemon.
`daemon.codex_path`	Nonempty executable path/name; default `codex`	Codex executable used by the daemon.
`default_visibility`	`private`, `project`, `org_public`, `public`; default `org_public`	Default session visibility.
`disable_session_guidelines`	`true` / `false`; default `false`	Skip guideline injection at session start.
`disable_memory_index`	`true` / `false`; default `false`	Skip the shared-memory index at session start.
`disable_workitems_nudge`	`true` / `false`; default `false`	Skip the work-items reminder at session start.
`disable_plans_nudge`	`true` / `false`; default `false`	Skip the plans reminder at session start.
`disable_coordination_notices`	`true` / `false`; default `false`	Skip in-session coordination notices about overlapping work.
`disable_harness_nudge`	`true` / `false`; default `false`	Skip new-agent setup reminders in sessions and CLI output.
`use_provider_api_key`	`true` / `false`; default `false`	Retain `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` in headless agent spawns instead of scrubbing them.
`excluded_repos`	Comma-separated `owner/repo` values; default empty	Exclude repositories from capture and import.
`allowed_repos`	Comma-separated `owner/repo` values; default empty	Restrict capture and import to listed repositories. Empty permits all, subject to exclusions.
`update_check`	`true` / `false`; default `true`	Enable update checks and related CLI, dashboard, and agent reminders.
`flows.reviewer_vendor`	Nonempty vendor ID; default unset	Preferred reviewer when a flow definition names no vendor. Trimmed and lowercased; unknown vendors warn but are saved for server validation.
`skills.auto_sync`	`true` / `false`; default `false`	Refresh server-managed skills in the background at Claude session start.
`telemetry`	`on` / `off`, also `true` / `false`, `1` / `0`, `yes` / `no`; default `on`	Machine-wide pseudonymous CLI usage reporting. Environment overrides still apply.

The known reviewer IDs are claude, codex, copilot, cursor, gemini, kiro, opencode, pi, and antigravity. Boolean configuration keys accept true or false; the broader toggle spellings apply only where listed. Clear a repository list with an empty quoted value, such as kcap config set excluded_repos "".

Other stored fields are managed through their own commands: use allow/ignore for path lists, remap for history-path remapping, profile add --remote for remote patterns, and update --beta/--stable for the update channel. They are not additional config set keys.

Other

`update`

kcap update [--check] [--beta | --stable]

For a global npm installation, install the current release for your channel and refresh opted-in plugins. Other installation methods print update guidance; an app-bundled CLI is updated through the app. Stable updates are capped at the connected server’s version; beta can run ahead.

Option	Description
`--check`	Print one JSON result without installing. Includes `current`, `latest`, `newer`, `channel`, and `install_tag`.
`--beta`	Select and save the beta channel for the resolved profile.
`--stable`	Select and save the stable channel (`latest`), the default for fresh profiles. Takes precedence if both channel flags are supplied.

A channel flag also persists when combined with --check. Windows npm updates can move locked executables aside; running processes continue using their old version until restarted.

`feedback`

kcap feedback (--bug | --feedback) [-m <text>]

Send a bug report or product feedback to Kurrent support using your signed-in identity. Replies arrive by email.

Option	Description
`--bug`	Submit a bug report. Exactly one of `--bug` and `--feedback` is required.
`--feedback`	Submit product feedback.
`-m <text>`, `--message <text>`	Message to send. Required with redirected/noninteractive stdin. Otherwise enter lines at the prompt and finish with an empty line. Empty messages are rejected.

`cleanup`

kcap cleanup

Stop tracked watcher processes, remove their stale PID files, and purge auxiliary watcher files. This operates on all tracked watchers, including running ones; it is not limited to processes proven orphaned. It has no command-specific options.

Uninstall

kcap uninstall [--project] [--keep-config] [--yes]

Remove local Capacitor integration: uninstall daemon services, stop daemons and watchers, remove supported agent integrations and shared skills, and delete the configuration directory. Unrelated entries in shared files are preserved. This command does not remove the CLI package itself; remove that separately with the package manager used to install it.

Option	Behavior
`--project`	Also remove Claude and Codex hooks at the current Git repository root. Requires a Git working tree. Other repositories and hooks installed under subdirectories are not traversed.
`--keep-config`	Preserve the config directory, including profiles, tokens, and capture lists.
`--yes`, `-y`	Skip the confirmation prompt. Default: prompt, with cancellation as the default answer.

On a cleanup failure, uninstall exits 1 and preserves the configuration directory so you can retry. For selective removal, use plugin remove with one target flag.

Service status