CLI Reference

okto-pulse is the single entry point for installing, starting, and maintaining a Pulse instance. All commands run locally — nothing is sent to a remote server.

Installing the CLI

pip install okto-pulse

Requires Python 3.11+. See Install for Docker and source options. Verify the install:

okto-pulse --version

okto-pulse 0.2.0
okto-pulse-core 0.2.0

Global flags

These flags are accepted by every command.

boolean

Print usage and exit. Works on the root command and on any subcommand: okto-pulse init --help.

boolean

Print the versions of both okto-pulse and okto-pulse-core and exit. Source: cli.py:164.

To increase log verbosity, set the DEBUG environment variable:

DEBUG=true okto-pulse serve --accept-terms

`okto-pulse init`

Source: cli.py:314–440 Initialize ~/.okto-pulse/, seed the database, bootstrap the knowledge graph schema for the first board, and optionally write .mcp.json for your agent.

okto-pulse init [--agents [NAME ...]]

string[]

Generate .mcp.json in the current directory. Pass with no argument to include all registered agents. Pass one or more agent names to include only that subset. Omit the flag entirely to skip .mcp.json generation.

okto-pulse init --agents          # all agents
okto-pulse init --agents claude   # named agent only
okto-pulse init                   # no .mcp.json

What init creates:

~/.okto-pulse/
  data/pulse.db                   SQLite database (WAL mode, FK ON)
  uploads/                        file attachment storage
  boards/{board_id}/graph.lbug    per-board knowledge graph

.mcp.json is written in the current working directory (not ~/.okto-pulse/). Run init from your project root so your agent picks it up.

.mcp.json contains a per-agent API key. Add it to .gitignore before your first commit.

Exit codes: 0 on success. Non-zero if the data directory cannot be created or the database cannot be seeded.

cd ~/my-project
okto-pulse init --agents

✓ Data directory: ~/.okto-pulse/data/
✓ Database initialized
✓ Default board created
✓ Knowledge graph bootstrapped
✓ .mcp.json written (1 agent)

`okto-pulse serve`

Source: cli.py:500–563 Start the API server, web board, and MCP server as a single Python process with two uvicorn listeners.

okto-pulse serve [--api-port PORT] [--mcp-port PORT] [--accept-terms]

number

default:"8100"

Port for the web board and REST API. Sets OKTO_PULSE_PORT before the app module is imported. Source: cli.py:20.

number

default:"8101"

Port for the MCP server (216 tools). Sets OKTO_PULSE_MCP_PORT before the app module is imported. Source: cli.py:21.

boolean

Pre-accept the Terms of Use and skip the interactive prompt. Equivalent to setting OKTO_PULSE_TERMS_ACCEPTED=1. Required in CI and containerized environments. Source: cli.py:537.

Both port environment variables are set before the app module is imported, because okto_pulse.community.main reads them at import time to generate /config.js. If you use a non-default MCP port, update the generated .mcp.json URL so it matches the port passed to okto-pulse serve --mcp-port.

okto-pulse serve --accept-terms

Board:  http://127.0.0.1:8100
MCP:    http://127.0.0.1:8101/mcp

okto-pulse serve --api-port 9000 --mcp-port 9001 --accept-terms

Exit codes: 0 on clean shutdown (Ctrl+C). Non-zero if either port is already in use.

`okto-pulse status`

Source: cli.py:567–614 Show service status and board metrics without starting the server.

okto-pulse status [--api-port PORT] [--mcp-port PORT]

number

default:"8100"

Port to probe for the API server. Must match the port used in serve.

number

default:"8101"

Port to probe for the MCP server.

okto-pulse status

Data dir:   ~/.okto-pulse/data/
Database:   ~/.okto-pulse/data/pulse.db (1,204 KB)

  boards      1
  cards       47
  specs       8
  agents      2

API server  :8100   running
MCP server  :8101   running

Exit codes: 0 always. Port connectivity failures are reported in the output, not via exit code.

`okto-pulse api-key`

Source: cli.py:620–680 Print the bootstrap API key directly from the SQLite database. Use this in CI/CD pipelines to extract the seeded key without parsing log output.

okto-pulse api-key

No flags. Output: The API key value on a single line to stdout. The startup banner goes to stderr so the key can be captured cleanly:

KEY=$(okto-pulse api-key 2>/dev/null)

Exit codes: 0 if the key is found and printed. 1 if the database is missing or no key exists (run okto-pulse init first).

okto-pulse api-key

dash_a3f8c21e4b7d9f0e2a1c5b8d

`okto-pulse verify-pipeline`

Source: cli.py:683–744, kg/health.py Run five KG pipeline health checks against a board and report results.

okto-pulse verify-pipeline <board_id> [--json]

string

required

The board UUID to inspect. Find it in the web board URL or via okto-pulse status.

boolean

Emit a structured JSON object instead of a human-readable table. Useful for scripted health monitoring.

Checks run:

Check	What it verifies
`check_queue`	SQLite consolidation queue depth
`check_kuzu`	LadybugDB graph file presence and node count
`check_kuzu_node_refs`	Cross-check between LadybugDB total and SQLite node ref mirror
`check_outbox`	Global update outbox staleness
`check_global`	Global discovery graph file presence

Exit codes: 0 if all five checks pass. 1 if any check fails. Use exit code in CI to gate deployments.

okto-pulse verify-pipeline <board_id>

check_queue          ✓ pass   depth=0
check_kuzu           ✓ pass   nodes=312
check_kuzu_node_refs ✓ pass   delta=0
check_outbox         ✓ pass   staleness=0s
check_global         ✓ pass

okto-pulse verify-pipeline <board_id> --json

{
  "check_queue": {"status": "pass", "depth": 0},
  "check_kuzu": {"status": "pass", "nodes": 312},
  "check_kuzu_node_refs": {"status": "pass", "delta": 0},
  "check_outbox": {"status": "pass", "staleness_seconds": 0},
  "check_global": {"status": "pass"}
}

`okto-pulse kg backfill`

Source: cli.py:747–902 Run the Layer 1 deterministic KG worker against a board to (re-)populate the knowledge graph from existing artifacts. Dry-run by default — pass --apply to write.

okto-pulse kg backfill <board_id> [--apply] [--artifact-type TYPE] [--json]

string

required

The board UUID to backfill.

boolean

Enqueue all artifacts and drain the consolidation queue, writing to LadybugDB. Without this flag the command reports what would be emitted without making any changes.

string

Restrict backfill to one artifact type. Accepts: spec, sprint, or card. Omit to backfill all types.

boolean

Emit structured JSON output. Useful for scripting and log parsing.

Run kg backfill after a schema migration, after importing data from another instance, or when the KG health check reports a check_kuzu_node_refs delta greater than zero. For ongoing consolidation, the background worker handles new artifacts automatically. See KG backfill operations for guidance on expected runtime.

okto-pulse kg backfill <board_id>

Dry run — no writes. Pass --apply to commit.

  spec artifacts   8    →  would emit  43 nodes,  61 edges
  sprint artifacts 12   →  would emit  28 nodes,  34 edges
  card artifacts   47   →  would emit  94 nodes, 118 edges

Total: 165 nodes, 213 edges pending

okto-pulse kg backfill <board_id> --apply

Enqueueing artifacts...
Processing queue...

  spec artifacts   8    → committed  43 nodes,  61 edges
  sprint artifacts 12   → committed  28 nodes,  34 edges
  card artifacts   47   → committed  94 nodes, 118 edges

Backfill complete. Queue empty.

Exit codes: 0 on success. 1 if the board is not found or the graph file cannot be opened.

`okto-pulse kg dedup-entities`

Source: cli.py:908–936 Consolidate duplicate LadybugDB nodes that share the same (node_type, source_artifact_ref). Writes by default — pass --dry-run to preview.

okto-pulse kg dedup-entities <board_id> [--dry-run] [--json]

string

required

The board UUID to deduplicate.

boolean

Report duplicates without merging them. Always run this first to review what will be merged before committing.

boolean

Emit structured JSON output.

kg dedup-entities writes to the LadybugDB graph by default (without --dry-run). Merging nodes is not automatically reversible. Run the dry-run first, then verify-pipeline after applying to confirm the graph is consistent.

okto-pulse kg dedup-entities <board_id> --dry-run

Dry run — no writes.

  Decision  "Use SQLite for queue"   2 duplicates → would merge
  Entity    "Claude Code"            3 duplicates → would merge

2 merge operations pending. Run without --dry-run to apply.

okto-pulse kg dedup-entities <board_id>

  Decision  "Use SQLite for queue"   merged (2 → 1)
  Entity    "Claude Code"            merged (3 → 1)

Deduplication complete. 2 nodes merged.

Exit codes: 0 on success (including zero duplicates found). 1 if the board or graph file is not found.

`okto-pulse reset`

Source: cli.py:939–960 Delete all local Pulse data and re-seed from scratch. Equivalent to uninstalling and reinstalling the data directory.

okto-pulse reset [-y]

boolean

Skip the confirmation prompt. Required for non-interactive environments (CI, scripts). Without this flag, the command prints a warning and asks for confirmation before proceeding.

reset permanently deletes pulse.db, all WAL files, and everything in the uploads directory. All boards, specs, cards, knowledge graph data, and file attachments are lost. There is no undo.If you need to start over on a single board without losing others, use archive_tree via the MCP API instead.

What reset does:

Deletes ~/.okto-pulse/data/pulse.db* (database and WAL files)
Clears ~/.okto-pulse/uploads/
Runs okto-pulse init to re-seed defaults

Exit codes: 0 on success. 1 if the user declines the confirmation prompt.

okto-pulse reset

⚠ This will delete all boards, specs, cards, and knowledge graph data.
  Data dir: ~/.okto-pulse/

Type "yes" to confirm: yes

✓ Database deleted
✓ Uploads cleared
✓ Re-initialized

okto-pulse reset -y

Environment variables

Key variables that affect CLI behavior. Set in your shell or in a .env file in the working directory.

Variable	Default	Description
`OKTO_PULSE_PORT`	`8100`	API + frontend port
`OKTO_PULSE_MCP_PORT`	`8101`	MCP server port
`OKTO_PULSE_TERMS_ACCEPTED`	—	Set to `1` to skip the ToU prompt (same as `--accept-terms`)
`OKTO_PULSE_DATA_DIR`	`~/.okto-pulse`	Override the data directory location
`OKTO_PULSE_NO_BANNER`	—	Set to `1` to suppress the ASCII banner
`DEBUG`	`false`	Enable verbose debug logging
`KG_KUZU_BUFFER_POOL_MB`	`256`	LadybugDB buffer pool in MB (legacy env-var name, 16–512)
`KG_KUZU_MAX_DB_SIZE_GB`	`1`	LadybugDB max database size in GB (legacy env-var name, 1–64)

Full environment variable reference: Local operations.

Quick reference

Command	What it does
`okto-pulse init --agents`	Bootstrap data dir + write `.mcp.json`
`okto-pulse serve --accept-terms`	Start board (`:8100`) and MCP (`:8101`)
`okto-pulse status`	Check running ports and board metrics
`okto-pulse api-key`	Print bootstrap API key (CI use)
`okto-pulse verify-pipeline <id>`	Run 5 KG health checks
`okto-pulse kg backfill <id> --apply`	Rebuild KG from existing artifacts
`okto-pulse kg dedup-entities <id> --dry-run`	Preview duplicate node merges
`okto-pulse reset -y`	Delete all data and re-seed

Get started

Concepts

Configuration

Reference

Permissions & Agents

Guides

KG Operations

Operations

Help

CLI Reference

CLI Reference

Installing the CLI

Global flags

`okto-pulse init`

`okto-pulse serve`

`okto-pulse status`

`okto-pulse api-key`

`okto-pulse verify-pipeline`

`okto-pulse kg backfill`

`okto-pulse kg dedup-entities`

`okto-pulse reset`

Environment variables

Quick reference

​CLI Reference

​Installing the CLI

​Global flags

​okto-pulse init

​okto-pulse serve

​okto-pulse status

​okto-pulse api-key

​okto-pulse verify-pipeline

​okto-pulse kg backfill

​okto-pulse kg dedup-entities

​okto-pulse reset

​Environment variables

​Quick reference

CLI Reference

Installing the CLI

Global flags

`okto-pulse init`

`okto-pulse serve`

`okto-pulse status`

`okto-pulse api-key`

`okto-pulse verify-pipeline`

`okto-pulse kg backfill`

`okto-pulse kg dedup-entities`

`okto-pulse reset`

Environment variables

Quick reference