CLI Reference

Overview

The primer CLI is installed automatically when you install the Primer Python package. It provides commands for managing the server, installing hooks, running diagnostics, and configuring your environment.

primer --help

All commands accept --help for detailed usage information. The CLI reads configuration from ~/.primer/config.toml and environment variables with the PRIMER_ prefix.

primer init

Initialize Primer on your machine. This is the first command you should run after installation.

primer init

This command:

1. Creates the ~/.primer/ configuration directory.
2. Generates a random admin API key and writes it to config.toml.
3. Runs database migrations to set up the schema.

✓ Created ~/.primer/
✓ Generated admin key: primer-admin-xxxxx
✓ Database migrations applied
Primer is ready. Run `primer server start` to launch the API.

primer setup

Register yourself as an engineer and save your API key.

primer setup [--name NAME] [--email EMAIL] [--server-url URL]

Flag	Default	Description
--name	git config user.name	Your display name in the dashboard
--email	git config user.email	Used for identification and GitHub matching
--server-url	http://localhost:8000	The Primer API server address

The command reads your name and email from git config automatically. If they aren’t found, it prompts interactively. You can skip the prompts entirely by passing both flags:

# Auto-detects name/email from git config
primer setup

# Explicit values (no prompts)
primer setup --name "Jane Doe" --email jane@example.com --server-url https://primer.internal

On completion, it creates your engineer account on the server and stores the API key in ~/.primer/config.toml.

primer server

Manage the Primer API server process.

primer server start

Start the API server as a managed background process.

primer server start [--host HOST] [--port PORT] [--fg]

Flag	Default	Description
--host	127.0.0.1	Bind address
--port	8000	Bind port
--fg	—	Run in foreground instead of daemonizing

The default host is 127.0.0.1 (localhost only). To accept external connections, pass --host 0.0.0.0. Use --fg to run in the foreground, which is useful for development, debugging, and Docker containers.

# Start on the default port
primer server start

# Start on a custom port, accessible externally
primer server start --host 0.0.0.0 --port 9000

# Run in the foreground with visible log output
primer server start --fg

primer server stop

Stop the managed server process.

primer server stop

Sends a graceful shutdown signal to the background server process. If the process does not exit within a few seconds, it is forcefully terminated.

primer server status

Show whether the server is running and verify API connectivity.

primer server status

Server: running (PID 12345)
Health: ok
URL:    http://localhost:8000

primer server logs

Tail the server log output.

primer server logs [-f] [-n N]

Flag	Default	Description
-f	—	Follow log output in real time
-n	50	Number of lines to display

# Show the last 100 lines
primer server logs -n 100

# Follow logs in real time
primer server logs -f

primer hook

Manage the Claude Code SessionEnd hook that automatically uploads session data to Primer.

primer hook install

Install the SessionEnd hook into Claude Code’s configuration.

primer hook install

This adds a SessionEnd entry to ~/.claude/settings.json that triggers the Primer ingest process when a Claude Code session ends. The hook uses your configured PRIMER_SERVER_URL and PRIMER_API_KEY.

primer hook uninstall

Remove the SessionEnd hook from Claude Code settings.

primer hook uninstall

After uninstalling, Claude Code sessions will no longer be uploaded to Primer. Previously uploaded sessions remain in the database.

primer hook status

Check whether the hook is installed and functional.

primer hook status

Hook:   installed
Server: reachable
Key:    valid (engineer: jane-doe)

This verifies three things:

1. The SessionEnd entry exists in ~/.claude/settings.json.
2. The configured Primer server is reachable.
3. The API key is valid and maps to a registered engineer.

primer sync

Re-upload sessions that failed to sync, for example due to the server being unreachable when a session ended.

primer sync

The hook stores failed uploads locally in ~/.primer/pending/. Running primer sync retries all pending uploads and removes them on success.

primer doctor

Run a comprehensive health check to verify your Primer installation.

primer doctor

✓ Data directory: ~/.primer
✓ Config file: ~/.primer/config.toml
✓ Database: ~/.primer/primer.db
✓ Admin API key: primer-admin-...
✓ API key: primer-eng-xxx...
✓ Server running (PID 12345, launchd)
✓ Server reachable: http://localhost:8000
✓ Claude Code hook installed
✓ MCP server registered

The doctor runs 9 checks:

1. Data directory — ~/.primer/ exists.
2. Config file — config.toml is present.
3. Database — The SQLite file (or external database) is accessible.
4. Admin API key — An admin key is configured.
5. Engineer API key — Your personal API key is set.
6. Server running — The background server process is active.
7. Server reachable — The health endpoint responds.
8. Hook installed — The SessionEnd hook is in Claude Code settings.
9. MCP registered — The MCP sidecar is registered in Claude Code.

If any check fails, the doctor provides actionable guidance on how to fix it.

primer configure

Read and write Primer configuration values.

primer configure get

Get a single configuration value:

primer configure get server.port
# server.port = 8000

primer configure get server.url
# server.url = http://localhost:8000

Sensitive values (API keys) are automatically masked in output.

primer configure set

Set a configuration value:

primer configure set server.port 9000
# ✓ server.port = 9000

primer configure set server.url https://primer.internal
# ✓ server.url = https://primer.internal

primer configure list

Show all configuration values:

primer configure list

[server]
  url            = http://localhost:8000
  port           = 8000
  host           = 127.0.0.1

[auth]
  admin_api_key  = primer-admin-...
  api_key        = primer-eng-xxx...

[database]
  url            = sqlite:///~/.primer/primer.db

See the Configuration page for a complete reference of all available settings.

Development Tools

These commands are not part of the primer CLI but are commonly used during Primer development.

API Server (hot reload)

Run the FastAPI server directly with auto-reload for development:

uvicorn primer.server.app:app --reload

This is an alternative to primer server start --fg that provides automatic code reloading when source files change.

Database Migrations

Apply all pending migrations:

alembic upgrade head

Generate a new migration after changing SQLAlchemy models:

alembic revision --autogenerate -m "description"

Tests

# Run the full test suite
pytest -v

# Run with coverage reporting
pytest -v --cov=primer --cov-report=term-missing

Linting and Formatting

# Check for lint errors
ruff check .

# Auto-fix lint errors
ruff check . --fix

# Format code
ruff format .

# Check formatting without changes
ruff format --check .

Security Scan

bandit -r src/ -c pyproject.toml

MCP Server

Run the MCP sidecar server directly for testing:

python -m primer.mcp.server

Frontend Commands

The React dashboard has its own set of commands, run from the frontend/ directory.

# Development server with hot reload
cd frontend && npm run dev

# Production build
cd frontend && npm run build

# ESLint
cd frontend && npm run lint

# TypeScript type checking
cd frontend && npx tsc -b --noEmit

See the Installation guide for initial setup instructions.