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.1.14
okto-pulse-core 0.1.14

Global flags

These flags are accepted by every command.

--help

boolean

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

--version

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 ...]] [--mcp-port PORT]

--agents

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

--mcp-port

number

default:"8101"

MCP server port to embed in the generated .mcp.json URLs. Must match the port you pass to okto-pulse serve --mcp-port. Source: cli.py:334.

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

`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]

--api-port

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.

--mcp-port

number

default:"8101"

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

--accept-terms

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 change ports after init, re-run okto-pulse init --agents --mcp-port <new-port> to update .mcp.json.

okto-pulse serve --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]

--api-port

number

default:"8100"

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

--mcp-port

number

default:"8101"

Port to probe for the MCP server.

okto-pulse status

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

`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]

board_id

string

required

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

--json

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`	Kùzu graph file presence and node count
`check_kuzu_node_refs`	Cross-check between Kùzu 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>

`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]

board_id

string

required

The board UUID to backfill.

--apply

boolean

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

--artifact-type

string

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

--json

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>

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 Kùzu 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]

board_id

string

required

The board UUID to deduplicate.

--dry-run

boolean

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

--json

boolean

Emit structured JSON output.

kg dedup-entities writes to the Kùzu 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

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]

-y, --yes

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

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`	Kùzu buffer pool in MB (16–512)
`KG_KUZU_MAX_DB_SIZE_GB`	`1`	Kùzu max database size in GB (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

Get started

Concepts

Configuration

Reference

Permissions & Agents

Guides

KG Operations

Operations

Help

Documentation Index

​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