docs / configuration

Configuration

The PromptConduit CLI reads its configuration from ~/.config/promptconduit/config.json, with environment variables taking precedence over the file. Named environments let you switch between local, staging, and production API keys with one command.

You rarely need to edit configuration by hand. promptconduit init writes everything a normal setup needs (see Quick Start), and every setting below has a config set flag. This page is the reference for what those settings mean, where the CLI keeps its files, and how to fix the usual misconfigurations. Command syntax is in the CLI Reference.

Set API Key

promptconduit config set --api-key="sk_your_key_here"

Most setups don't need this. promptconduit login saves your key via a browser sign-in, and promptconduit init runs the full guided setup. Use config set for CI or scripted environments. Both login and init --api-key also turn local-only mode off, since signing in means you want events sent.

The Config File

The file is JSON, created with mode 0600 in a directory with mode 0700. If XDG_CONFIG_HOME is set, the file lives at $XDG_CONFIG_HOME/promptconduit/config.json instead. promptconduit config path prints the exact location. Fields that are unset or false are omitted when the CLI writes the file.

A single-account setup uses flat, top-level fields:

{
  "api_key": "sk_your_key_here",
  "api_url": "https://api.promptconduit.dev",
  "timeout_seconds": 30,
  "event_log_retention_days": 90,
  "disable_telemetry": true
}

With named environments, the active one is selected by current_env:

{
  "current_env": "prod",
  "environments": {
    "local": {
      "api_key": "sk_local_key",
      "api_url": "http://localhost:8787",
      "debug": true
    },
    "prod": {
      "api_key": "sk_prod_key",
      "api_url": "https://api.promptconduit.dev"
    }
  },
  "disable_telemetry": true,
  "event_log_retention_days": 60
}

Precedence

Settings resolve as environment variables, then the config file, then built-in defaults. A few details matter in practice:

• PROMPTCONDUIT_API_KEY and PROMPTCONDUIT_API_URL override the file independently. Setting only the key keeps the file's URL, which is how a prod key ends up pointed at a local server (see Troubleshooting).
• When current_env names an existing environment, the CLI takes api_key, api_url, and debug from that environment and ignores the top-level copies. Top-level local_only, disable_*, and event_log_retention_days still apply to every environment as global defaults.
• The opt-out variables can only switch things off. For example, PROMPTCONDUIT_LOCAL_ONLY=1 forces local-only mode, but PROMPTCONDUIT_LOCAL_ONLY=0 does not undo local_only: true in the file. Change the file with config set instead.
• Command flags such as login --api-url apply to that one run and are not saved.

Local-only

Capture works with no account. To stay local even after setting a key:

promptconduit config set --local-only=true
# or at install time:
promptconduit install claude-code --local-only

In local-only mode (or with no API key) every hook event is still written to ~/.promptconduit/events.jsonl, and the local features keep working: promptconduit cost, graph, sessions, the editor extension, and local skills. Nothing is sent to the platform and automatic transcript sync is skipped. Turn sending back on with promptconduit config set --local-only=false. promptconduit config show prints the effective mode on its Mode: line.

View Current Config

promptconduit config show
promptconduit config path

config show prints the resolved values after environment variables are applied: API URL, masked API key, auto-update, usage ping, event log, retention, mode, the config file path, and the active environment. It also warns when PROMPTCONDUIT_API_KEY is set without PROMPTCONDUIT_API_URL.

Multi-Environment Setup

Manage separate keys for local development, staging, and production.

# Create environments
promptconduit config env add local \
  --api-key=sk_local_key \
  --api-url=http://localhost:8787 \
  --debug

promptconduit config env add prod \
  --api-key=sk_prod_key \
  --api-url=https://api.promptconduit.dev

# Switch environments
promptconduit config env use local
promptconduit config env use prod
promptconduit config set-env prod   # shortcut for "config env use"

# List and remove environments
promptconduit config env list
promptconduit config env remove local

env add requires --api-key; --api-url defaults to the production API. The first environment you add becomes active automatically. Adding a name that already exists replaces it.

Hooks run a fresh promptconduit hook process for every event and read the config file each time, so an environment switch applies from the next event on. Environment variables are different: an AI tool passes its own environment to hooks, so a variable you export or unset only takes effect in a new session started after the change. Queued retries are kept per API URL, so events that failed against prod are only ever replayed to prod.

Environment Variables

Prefer the config file over environment variables when using multi-environment setups. Mixing both can cause mismatches (e.g., prod API key with local URL).

Where Files Live

The CLI uses two directories. The config directory holds settings and CLI state. The data directory, ~/.promptconduit/, holds what your AI tools produced and is where local readers like the editor extension look. XDG_CONFIG_HOME moves only the first one.

Config directory: ~/.config/promptconduit/

Data directory: ~/.promptconduit/

Retention and Pruning

Local hook history in events.jsonl is kept for event_log_retention_days (30 by default). Everything inside the window is always kept. Older records are trimmed automatically only once the file grows past about 500 MB, oldest first, and the trim runs in a detached background process so hooks never wait on it. The file is not size-rotated, so recent history is never lost to a rotation.

# Keep 90 days instead of 30
promptconduit config set --event-log-retention-days=90

# Never prune
promptconduit config set --event-log-retention-days=-1

# See what is past the window, then remove it now
promptconduit prune --dry-run
promptconduit prune

prune only removes records older than the window. With retention set to keep forever it does nothing. The editor extension and cost history read the same file, so a short window also limits how far back they can show.

Auto-update

Interactive commands check GitHub for a newer release at most once every 24 hours, with a 5-second timeout. When one exists, the CLI prints a notice and starts promptconduit upgrade in the background, so the next invocation runs the new version. Hooks, upgrade, watch, collect, cost, graph, sessions, and resume never run the check. After an upgrade the CLI also updates the bundled editor extension if one is installed. The same daily cycle refreshes the public model rate card used for cost.

# Opt out (also stops the rate-card refresh)
promptconduit config set --disable-auto-update=true

# Or per shell
export PROMPTCONDUIT_AUTO_UPDATE=0

# Upgrade by hand
promptconduit upgrade --check
promptconduit upgrade

Self-upgrade needs write access to the directory holding the binary. If that directory is not writable, upgrade exits with an error and tells you to re-run the installer from Installation.

Usage Ping

Release builds send one anonymous ping per day: a random install ID, CLI version, OS and CPU architecture, installed tool hooks, the editor extension version, and whether you are signed in. No prompts, paths, or repository names. Nothing is sent until an interactive command has shown a one-time notice, and the ping is off when CI is set. Opt out with promptconduit config set --disable-telemetry=true, DO_NOT_TRACK=1, or PROMPTCONDUIT_TELEMETRY=0.

Debug Mode

# Enable via config
promptconduit config set --debug=true

# Enable via env var
PROMPTCONDUIT_DEBUG=1 promptconduit test

# Read the CLI log
promptconduit logs              # last 50 lines
promptconduit logs --follow
promptconduit logs --path       # ~/.config/promptconduit/logs/promptconduit.log

With environments in use, debug is read from the active environment. Set it with config env add <name> --debug; the top-level config set --debug value is ignored while an environment is active.

Troubleshooting

Events go to the wrong server, or return 401

Usually PROMPTCONDUIT_API_KEY is exported in your shell profile while the URL comes from the config file. Run promptconduit config show; it warns about exactly this. Unset the variable and use the config file or named environments, then start a new AI tool session so hooks stop inheriting it.

config set --api-key had no effect

If current_env is set, the active environment's key wins over the top-level key that config set writes. Update the environment with config env add <name> --api-key=..., or run promptconduit login, which saves the key into the active environment.

Nothing is captured after install

Restart the AI tool or start a new session. Tools load their hook configuration at startup. Then check promptconduit status for the hook count and promptconduit events -n 5 for the latest captured events. Tool-specific notes are in Supported Tools.

Captured locally but not on the dashboard

promptconduit status shows the mode and the sent, failed, and dropped counts. If it says local-only, set a key or turn local_only off. If sends are failing, promptconduit events --errors shows why, promptconduit watch shows the HTTP responses, and promptconduit events flush replays the queue once the cause is fixed.

Multiple binaries on PATH

Hooks call the absolute binary path recorded at install time. promptconduit status warns when several copies exist and says which one your hooks use. Remove the extras, or re-run promptconduit install <tool> from the copy you want to keep.