docs / cli-reference

CLI Reference

Full command reference for the PromptConduit CLI: onboarding, hook install, local cost and Session Graph, skill generation, transcript sync, and configuration. Every command supports --help.

Commands are grouped by task. Anything that reads local data (cost, graph, sessions, events, local skills) works with no account. Commands that talk to the platform (sync, insights, platform skills) need an API key from promptconduit login. If you have not installed the CLI yet, start with Installation and Quick Start. Settings and file locations are covered in Configuration.

Global Flags

Flag	Description
`-h`, `--help`	Show help for any command or subcommand

There is no --version flag; use promptconduit version.

Exit Behavior

Commands exit 0 on success and 1 on any error. A few cases are worth knowing when scripting:

test exits 0 without sending anything in local-only mode or when no API key is set. It exits 1 only when a configured request fails.
events flush exits non-zero when queued events could not be sent because of a server or credential failure, or when another process is already replaying the queue.
resume passes through the exit code of the claude process it runs.
init without a terminal fails unless you pass --local-only or --api-key, or a key is already configured.
The hook command your AI tools call always returns a continue response, even when capture or sending fails, so PromptConduit never blocks the tool. Failures are recorded in ~/.promptconduit/errors.log.

Setup

promptconduit init: Interactive setup: sign in (or stay local-only), detect installed AI tools, and install their hooks.
promptconduit login: Sign in through the browser and save your API key to config.
promptconduit status: Show mode, API key, hook installation per tool, and event send counters.
promptconduit test: Send a test request to verify API connectivity and authentication.
promptconduit version: Print version information.

Flag	Command	Description
`--local-only`	init	Local-only mode, no account or cloud sync
`--api-key <key>`	init	Save an API key directly and skip browser login
`--yes`	init	Non-interactive: install every detected tool
`--tools a,b`	init	Comma-separated tools to install, skipping the picker
`--no-browser`	login	Print the verification URL instead of opening a browser
`--api-url <url>`	login	Sign in against a different API for this run (not saved)

bash
# Guided setup
promptconduit init

# Scripted: local-only, Claude Code and Cursor
promptconduit init --local-only --tools claude-code,cursor

# Sign in on a remote machine
promptconduit login --no-browser

# Check what is installed and whether events are being sent
promptconduit status

login uses a browser device flow, saves the key into the active environment, and turns local-only mode off. status also warns when several promptconduit binaries are on your PATH and says which one your hooks call.

Capture: Install and Uninstall Hooks

promptconduit install [tool...]: Install hooks for one or more AI tools. Supported: claude-code, cursor, gemini-cli, codex, copilot, grok. Pass several names, or all. No argument opens a picker.
promptconduit uninstall <tool>: Remove PromptConduit hooks from one tool config. Takes exactly one tool name.

Flag	Description
`--local-only`	Save local-only mode: capture events, never send them
`--no-extension`	Don't sideload the bundled cost status-bar extension into Cursor
`--no-mcp`	Don't register the MCP server with Claude Code, Cursor, or Gemini CLI

bash
promptconduit install                      # interactive multi-select
promptconduit install cursor claude-code   # several at once
promptconduit install all                  # every supported tool
promptconduit install cursor --no-extension
promptconduit uninstall gemini-cli

Install writes hook entries into each tool's own config file and records the absolute path of the running binary. Re-running it replaces the previous PromptConduit entries, which is also how you repair hooks after moving the binary. gemini and grok-build are accepted as aliases. Restart the tool, or start a new session, so it loads the new hooks. Per-tool config paths and captured events are listed in Supported Tools. Installing for Cursor also installs the editor extension when the cursor shell command is available.

Cost and Insights

promptconduit cost: Current session cost by model, tokens, cache reads and writes, and tool calls. Computed locally.
promptconduit cost session: Same as running cost with no subcommand.
promptconduit cost history: Daily cost totals over recent days, read from ~/.promptconduit/events.jsonl.
promptconduit cost reprice: Fix Cursor events recorded before v0.21.0 that double-counted cached tokens.
promptconduit cost refresh-card: Download the PromptConduit model rate card. Also runs in the background once a day.
promptconduit cost refresh-pricing: Fetch the public LiteLLM price table to price models the built-in table lacks.
promptconduit graph: Live Session Graph in the browser, reading ~/.promptconduit/events.jsonl. 100% local.
promptconduit collect: Run a local OTLP/HTTP receiver, NDJSON store, and read-only trace dashboard.
promptconduit insights [tools|errors|sessions]: Usage analytics from the platform. Requires an API key.
promptconduit insights spend: Your synced spend across every machine: total, change, cache savings, and spend by model (the Overview page).
promptconduit insights trends: Your agent coaching trends and suggestions (the Trends page). Defaults to 30d.

Flag	Command	Description
`--cwd <dir>`	cost, cost session	Workspace to report on (default: current directory)
`--json`	cost, cost session, cost history	Machine-readable output
`--days N`	cost history	Number of days to include, today included (default 7)
`--dry-run`	cost reprice	Show what would change without writing
`--addr host:port`	graph	Address to serve on (default `127.0.0.1:4320`)
`--backfill N`	graph	Recent events to load before going live (default 10000)
`--no-open`	graph	Print the URL instead of opening a browser
`--otlp host:port`	collect	OTLP/HTTP receiver address (default `127.0.0.1:4318`)
`--dashboard host:port`	collect	Dashboard address (default `127.0.0.1:4319`)
`--dir <dir>`	collect	Span storage directory (default `~/.config/promptconduit/collect`)
`-p`, `--period`	insights	`24h`, `7d`, `30d`, or `90d` (default `7d`)
`-r`, `--repo`	insights	Filter by repository name
`-f`, `--format`	insights	`text` or `json`
`--json`	insights	Same as `--format json`
`-l`, `--limit`	insights sessions	Number of sessions to show (default 10)

bash
promptconduit cost                     # this workspace's current session
promptconduit cost history --days 30
promptconduit cost history --json
promptconduit graph --no-open          # e.g. over SSH
promptconduit insights tools -p 30d
promptconduit insights spend -p 30d --json

cost prices Claude Code sessions from their local transcripts and Cursor sessions from the token usage its hooks report. Models missing from the rate table show exact tokens and are marked unpriced rather than guessed. The Signals line reports cache-hit rate and the share of cost from cache misses; if cache hits are low, see improving cache hit rate. The Tools line counts tool calls by name, which pairs with batching tool calls. For live per-request cost in the editor status bar, use the editor extension.

Teams and Agents

promptconduit team [spend|savings|budgets|export|tag|create|invite|join]: Team spend, savings, budgets, client tags, and invites from the terminal. Every subcommand takes --json.
promptconduit team members [role <email> <role> | rm <email> --yes]: List members, change a role, or remove someone (owners and admins). Removing needs --yes.
promptconduit team billing [checkout --tier team|growth | portal] [--open]: Plan, seats, and status; print or open a Stripe checkout or billing portal link. Card details are only entered on Stripe.
promptconduit team alerts [slack <webhook-url|-> | slack --disconnect --yes]: Where budget alerts go; connect or disconnect Slack. Pass - to read the webhook from stdin.
promptconduit mcp: Run the MCP server over stdio. Agents start it themselves once it is registered.
promptconduit mcp install [tool...]: Register the MCP server with Claude Code, Cursor, or Gemini CLI.
promptconduit mcp uninstall [tool...]: Remove the registration. With no tool, also stops it being re-added after updates.
promptconduit mcp tools: List the tools agents see.

Flags, every MCP tool, and setup details are in AI Agents (MCP).

Sessions and Resume

promptconduit sessions: List recent AI sessions the CLI can reconstruct and reopen.
promptconduit sessions resolve --pid <pid>: Map a terminal shell PID to the Claude Code session inside it. Used by the editor extension.
promptconduit resume [session-id]: Reopen a captured session in its original working directory.

Flag	Command	Description
`--since <duration>`	sessions	Only sessions active within this window, e.g. `48h` (default `12h`)
`--all`	sessions	Include sessions that are still running
`--under <path>`	sessions	Only sessions whose directory is under this path
`--json`	sessions, sessions resolve	Machine-readable output
`--pid <pid>`	sessions resolve	Shell process ID of the terminal (required)
`--print`	resume	Print the `cd ... && claude --resume` command instead of running it

bash
promptconduit sessions                  # interrupted sessions, newest first
promptconduit sessions --since 48h --all
promptconduit resume                    # most recent session
promptconduit resume 9a40               # unambiguous id prefix
promptconduit resume 9a40 --print

Sessions are rebuilt from the local event log and record the exact directory each one ran in, including git worktrees, so resume reopens it in the right checkout. resume looks back 72 hours, needs the claude binary on PATH, and fails if the session's directory no longer exists. Running parallel agents in separate checkouts is covered in isolating work with worktrees.

Sync

promptconduit sync [tool]: Upload historical transcripts to the platform. Tools: claude-code, cursor. Requires an API key.

Flag	Description
`--dry-run`	Preview what would be uploaded without uploading
`--force`	Re-upload already synced transcripts
`--since YYYY-MM-DD`	Only sync transcripts modified after this date
`--limit N`	Sync at most N transcripts (0 means no limit)

bash
promptconduit sync --dry-run
promptconduit sync claude-code --since 2026-01-01
promptconduit sync --limit 10

Claude Code transcripts are read from ~/.claude/projects/ and Cursor transcripts from ~/.cursor/projects/*/agent-transcripts/. Upload state is tracked in ~/.config/promptconduit/sync_state.json, so unchanged transcripts are skipped. With an API key set and local-only off, hooks already sync the active transcript automatically after each response; run sync by hand to backfill history. A full sync also drains the replay queue.

Skills

promptconduit skills generate --local [flags]: Generate skills from local transcripts without a platform account.
promptconduit skills generate [flags]: Generate skills via platform (requires account).
promptconduit skills list: List skills detected on the platform.
promptconduit skills patterns: Show recurring prompt themes that drive skill generation.
promptconduit skills install [name|uuid]: Write a platform skill to .claude/skills/<name>/SKILL.md and track it in a manifest.
promptconduit skills uninstall [name]: Remove a skill installed by skills install. Refuses if the file was edited, unless --force.
promptconduit skills sync: Write all approved skills as command files in ~/.claude/commands/.
promptconduit skills approve <name|uuid>: Mark a skill approved on the platform.
promptconduit skills reject <name|uuid>: Mark a skill rejected on the platform.
promptconduit skills delete <name|uuid>: Soft-delete a skill on the platform so it no longer appears in listings.

Generate Flags

Flag	Description
`--local`	Run locally with your own AI subscription, no platform account
`--tool <name>`	Transcripts to read: `claude-code`, `codex`, `copilot`, or `all` (default)
`--repo owner/repo`	Scope generated skills to a specific repository (auto-detected inside a git repo)
`--force`	Re-analyze previously seen transcripts
`--dry-run`	Preview detected skills without writing files
`-f`, `--format`	`text` or `json`

Platform Skill Flags

Flag	Command	Description
`--approved true\|false\|pending`	list	Filter by approval state
`--filter`	list	`new`, `ready`, `removed`, or `all` (default)
`--type`	list	`workflow`, `command`, `template`, or `checklist`
`-l`, `--limit`	list	Maximum skills to show (default 50)
`--repo`	list, patterns	Filter to one project
`--scope project\|global`	install	Install into the current repo's `.claude/skills` or into `~/.claude/skills`
`--all`	install, uninstall	Every approved skill, or every PromptConduit-installed skill
`--force`	install, uninstall	Overwrite or remove files that were edited by hand
`--dir <dir>`	sync	Write command files somewhere other than `~/.claude/commands/`
`--yes`	delete	Skip the confirmation prompt (required without a terminal)

bash
# Local, no account
promptconduit skills generate --local --tool claude-code --dry-run

# Platform workflow
promptconduit skills generate
promptconduit skills list --filter new
promptconduit skills approve shipping-features
promptconduit skills install shipping-features --scope project

The local flow is described in detail in Local Skills. When a skill name matches more than one skill, install stops and lists each candidate's UUID so you can pick one. For when a skill or slash command is worth creating, see adopting skills and slash commands.

Config

promptconduit config set [flags]: Set configuration values in the config file.
promptconduit config show: Display the resolved configuration, including environment variable overrides.
promptconduit config path: Print the config file path.
promptconduit config env add <name>: Create or replace a named environment.
promptconduit config env use <name>: Switch to a named environment.
promptconduit config set-env <name>: Shortcut for config env use.
promptconduit config env list: List all configured environments. The active one is marked with an arrow.
promptconduit config env remove <name>: Delete a named environment.

Flag	Command	Description
`--api-key`	config set, env add	API key (required for env add)
`--api-url`	config set, env add	API URL (default `https://api.promptconduit.dev`)
`--debug`	config set, env add	Enable debug logging
`--local-only`	config set	Capture locally, never send
`--event-log-retention-days N`	config set	Days of local hook history to keep (default 30; `-1` keeps forever)
`--disable-event-log`	config set	Stop writing the local event log
`--disable-auto-update`	config set	Stop the background self-upgrade
`--disable-telemetry`	config set	Stop the anonymous daily usage ping

bash
promptconduit config set --api-key="sk_your_key_here"
promptconduit config set --local-only=true
promptconduit config set --event-log-retention-days=90
promptconduit config env add local --api-key=sk_local_key --api-url=http://localhost:8787
promptconduit config env use local

Boolean flags take an explicit value to turn a setting back off, for example --local-only=false. config set with no flags exits with an error listing the accepted flags.

Maintenance and Diagnostics

promptconduit upgrade: Download and apply the latest GitHub release. Also runs in the background once a day.
promptconduit prune: Trim local hook history past the configured retention window.
promptconduit events: Show captured events from the local event log, one summary line each.
promptconduit events flush: Replay events queued after failed sends, now.
promptconduit logs: Show the CLI log (errors, plus debug lines when debug is on).
promptconduit watch: Tail outbound HTTP to the platform in real time (hook sends, sync, skills).
promptconduit debug trace <session_id>: Print the stored trace ID and parent spans for a session.
promptconduit feedback [message]: Send a note to the team. No session data is included.

Flag	Command	Description
`--check`	upgrade	Only check for a newer release
`--force`	upgrade	Reinstall even when already on the latest version
`--dry-run`	prune, events flush	Report what would be removed or sent, change nothing
`-n`, `--lines`	events	Events to show from the end of the log (default 20)
`-f`, `--follow`	events, logs	Stream new lines as they are written
`--raw`	events	Print the full JSON envelope under each summary line
`--errors`	events	Show `errors.log` (failures and drops) instead
`--path`	events, logs	Print only the file path
`-n`, `--tail`	logs	Lines to show from the end of the log (default 50)
`--clear`	logs	Truncate the log file
`-v`, `--verbose`	watch	Include request and response bodies
`--lines N`	watch	Backfill the last N requests before going live
`--category`	feedback	Optional: `bug`, `idea`, `praise`, or `other`

bash
promptconduit events -n 5              # last five captured events
promptconduit events --errors          # why events failed or were dropped
promptconduit watch --verbose          # what is actually being sent
promptconduit events flush --dry-run   # how many events are queued for replay
promptconduit prune --dry-run
promptconduit upgrade --check
promptconduit feedback --category idea "filter the graph by repo"

When events captured locally do not show up on the dashboard, check them in this order: status for the mode and send counters, events --errors for the failure reason, watch for the HTTP response, then events flush once the cause is fixed. feedback also reads the message from stdin, is limited to 4000 characters, and is tied to your account only when an API key is set. The Configuration page lists every file these commands read.