Configuration & profiles

The CLI stores configuration in ~/.config/kapacitor/config.json. You don’t usually edit it by hand — kapacitor config set and the profile commands cover everything. This page documents what’s in there and how the resolution order works.

Config keys

kapacitor config show
kapacitor config set <key> <value>

Key	Default	Description
server_url	(none)	Your tenant URL, e.g. https://acme.kapacitor.ai. Set by kapacitor setup.
default_visibility	org_public	private, org_public, or public. Applied to every new session you create.
excluded_repos	(empty)	Comma-separated owner/repo list. Sessions in these repos are silently skipped.
daemon.claude_path	"claude"	Path to the Claude CLI binary, used by the daemon.
daemon.codex_path	"codex"	Path to the Codex CLI binary, used by the daemon.
disable_session_guidelines	false	If true, the CLI suppresses SessionStart guideline injection for your sessions.

Visibility values:

Value	Who sees the session
private	Only the owner.
org_public	Anyone in the org that owns the repo (when the repo is recognised as an org repo). Personal repos fall back to private.
public	Anyone signed in to the tenant.

See Visibility & sharing for how the per-session share popover layers on top of these.

Path exclusions

Separate from excluded_repos. kapacitor ignore matches the working directory (and any session whose cwd lives under it), regardless of git remote:

kapacitor ignore .                     # current directory
kapacitor ignore ~/code/secret
kapacitor ignore --list
kapacitor ignore --remove ~/code/secret

Symlinks are resolved on both the stored entry and the session’s reported cwd, so a worktree symlinked into another location matches its real target.

Entries are stored on the active profile, so switching profiles with kapacitor use switches the ignore list with you.

Profiles

Profiles let you target multiple tenants from one machine — say, a company tenant for work repos and a personal one for OSS. Each profile stores its own server_url, visibility default, daemon settings, and ignore list.

kapacitor profile add work --server-url https://acme.kapacitor.ai
kapacitor profile add oss --server-url https://cap.oss.dev --remote "github.com/myorg/*"
kapacitor profile list
kapacitor profile show work
kapacitor profile remove work

The --remote flag binds a profile to a git remote pattern. When you cd into a repo whose origin matches, that profile activates automatically.

Switching

kapacitor use work                  # bind 'work' to the current repo or directory
kapacitor use work --global         # set as the global default
kapacitor use work --save           # write .kapacitor.json (commit it for team-wide binding)

Without --global, use binds the profile to the current git repo root (or the current directory if not in a repo). With --save, it writes a .kapacitor.json you can commit so the whole team uses the same profile.

Resolution order

When the CLI needs to decide which profile to use, it consults these sources in order:

1. --server-url CLI flag
2. KAPACITOR_URL environment variable
3. KAPACITOR_PROFILE environment variable
4. .kapacitor.json in the repo root (or current directory if not in a repo)
5. Git remote pattern matching from --remote flags
6. Directory binding from kapacitor use
7. Global active profile (or default)

The first source that yields a profile wins.

Environment overrides

A few keys can be overridden by environment variables — useful for one-shot daemon launches or CI:

KAPACITOR_URL=https://acme.kapacitor.ai kapacitor recap <id>
KAPACITOR_PROFILE=work kapacitor status
KAPACITOR_CLAUDE_PATH=/opt/claude/bin/claude kapacitor daemon
KAPACITOR_CODEX_PATH=/opt/codex/bin/codex   kapacitor daemon

Env vars take precedence over the profile’s config.