16 · CLI & Scripts Reference
This page is the exhaustive index of every command-line surface the pack exposes: the binary CLIs (cross-referenced), the npm scripts, every installer and validator in scripts/, the runtime hook scripts in shared/scripts/, and the scheduled jobs. If you are looking for "what command does X," it is here.
The binary CLIs
Documented in full on the Tools Reference page; summarized here for completeness.
| Binary | Role | Documented in |
|---|---|---|
prometheus | Skill management, canonical KBD control/audit, self-learning, GitOps validation, Cedar policy, sycophancy | 13 |
forge | Enrichment, reflection, drift, templates, MCP server | 13 |
pk / pk-cherry | Karpathy KB CLI / MCP bridge | 13 |
liter-llm | LLM proxy + MCP tool server | 13 |
surreal-memory-server | Graph memory + MCP + durable v2 receipt API | 13 |
prometheus-learning-worker | Queue, receipt, and snapshot reconciliation | 13 |
prometheus-rust-auditor | Staged Rust quality pipeline | 13 |
The npm script surface
package.json (ES module) is the most common entry point.
| Command | What it does |
|---|---|
npm run validate | Validate native skills (excludes submodules), 0 errors required |
npm run validate:strict | Strict validation — license, version, metadata.tags become errors; the gate for new skills |
npm run validate:skill <path> | Validate one skill (lenient; includes imported) |
npm run validate:signals | Lint that every process skill declares a ## Progress Signals section |
npm run doctor | Canonical local diagnosis parity with prometheus doctor |
npm run docs:check | Public safety, OpenAPI/examples, semantic drift, links/sidebars, production build |
npm run build | Build the marketplace distribution (the .claude-plugin/ symlinks) |
npm run install:user / install:project | Install skills to ~/.claude/skills/ or .claude/skills/ |
npm run install:platforms | Multi-platform installer (tsx) with full plugin support |
npm run install:opencode / install:skills | OpenCode install / immutable generation projection |
npm run generate:commands / register:commands / unregister:commands | Generate/register native slash commands |
npm run skill-matrix / skill-matrix:ci | Pairwise skill-similarity collision report |
npm run update / update:force | Pull and delta-install changed skills |
npm run format / check-format | Prettier |
scripts/ — installers, validators, generators
| Script | Purpose |
|---|---|
install-plugin-generation.js | Stage, hash, verify, activate, roll back, or uninstall an immutable generation (canonical ~/.agents/skills copies plus Claude/Qwen shims). [--verify] [--rollback] [--uninstall] |
install-prometheus-exec.sh | Build/select, version-check, stage, sign, atomically install, and hash-readback prometheus-exec at its approved artifact-manifest version. Requires the hash pinned for this machine's Rust host target in expectedBuildSha256ByTarget; --dry-run prints the hash and target it would require. [--dry-run] |
build-prometheus-exec.sh | Reproducible release build of prometheus-exec: staged workspace, pinned toolchain, remapped checkout, Cargo and rust-src paths. Copies the result to crates/prometheus-exec/target/release/ and prints that path, or its SHA-256 with --print-hash (the recertification command). [--print-hash] |
prometheus-exec-pin.sh | Sourced helper. prometheus_exec_host_target [crate-dir] prints the Rust host target; prometheus_exec_pin <manifest> <target> prints that target's certified hash, falling back to a legacy single expectedBuildSha256 |
cargo-release-dir.sh | Sourced helper. cargo_release_dir <workspace> prints where cargo writes that workspace's release binaries, asking cargo metadata so build.target-dir and CARGO_TARGET_DIR are honored. Used by both installers below instead of a hardcoded target/release |
install-prometheus-exec-service.sh | Render and optionally load the private macOS execution LaunchAgent (ai.prometheus.exec, socket daemon). Called automatically by install-mcp-services.sh. [--dry-run] [--no-load] |
install-platforms.ts | Multi-platform symlink installer for Claude Code, OpenCode, Cursor, Codex, etc. [--platform] [--scope] [--uninstall] [--list] |
install.js | Copy skills to user or project scope |
install-binaries.sh | Build and install every source-owned binary to ~/.local/bin/, from cargo's real target directory. A component that fails is reported at the end with a non-zero exit while the rest still install. --dry-run builds, downloads, installs and registers nothing. [--dry-run] |
install-mcp-services.sh | Render/reload allowed launchd or systemd user services, including ai.prometheus.exec via its delegated installer. Repeatable --exclude prevents rendering, restart, or rewrite of a service. [--unload] [--restart] [--user] [--dry-run] [--exclude] |
configure-mcp-all-tools.sh | Merge mcp-port-table.json into each tool's native MCP config (idempotent). [--dry-run] [--tool] |
prometheus-services.sh | Manage MCP services as macOS user LaunchAgents (install/load/status/doctor/…) |
register-slash-commands.sh | Register skills as OpenCode commands and Codex prompt files. [--uninstall] |
generate-commands.js | Generate Claude Code slash-command files from skill frontmatter. [--output] [--uninstall] |
check-prerequisites.sh | Check/install Node, Rust, npm deps; build tool binaries. [--install] [--build-tools] |
check-mcp-health.sh | Health table (service state + HTTP readiness) for non-excluded services. [--json] [--exclude] |
certify-memory-operations.sh | Mutating local proof of exact replay, conflict, response-loss reconciliation, terminal receipts, SSE resume, and optional long memory. |
smoke-test.sh | Confirm every tool binary is reachable and answers --version |
detect-command-conflicts.sh | Detect slash-command name collisions across installed command dirs |
skill-matrix.js | Pairwise Jaccard similarity of skill name+description; CI fails on un-allowlisted collisions |
validate-skills.js | The AgentSkills.io validator (Ajv schema). [--strict] [--exclude-submodules] |
validate-progress-signals.js | Merge gate for the ## Progress Signals section; ratchet baseline |
backfill-strict-fields.js | Backfill missing version/license/metadata.tags into SKILL.md. [--dry-run] |
build-marketplace.js | Build the .claude-plugin/ symlink distribution |
update-skill-pack.sh | Git-pull then delta-install changed skills across platforms (tracks last SHA). [--force] |
generate-harness-adapters.js | Generate Claude Code, Codex, OpenCode, and Kimi lifecycle adapters from one capability manifest |
check-harness-adapters.js | Reject drift between the manifest and generated adapters, and reject any supported capability field without its own evidence: a committed file, or a same-harness protocol-eval case with verdict PASS that declares that field. --capabilities <file> validates a copy instead of shared/harnesses/capabilities.json. [--capabilities] |
check-kbd-direct-writers.js | Reject new direct writers to canonical KBD compatibility projections |
validate-kbd-state.js | Validate KBD projection schemas and revision relationships |
test-kbd-control-plane.sh | Run runtime/journal/control-plane fixture tests |
generate-skill-eval-corpus.js / check-skill-evals.js | Maintain and validate the 30-prompt critical-skill activation corpus |
prometheus kbd
The canonical control CLI accepts a global project path before the subcommand:
prometheus kbd --path "/path/to/project" status --json
| Command | Purpose |
|---|---|
status [--json] | Lifecycle, revision, plan, checkpoint, active path, and completion |
projects [--json] [--prune-missing [--apply]] | List registered replicas or explicitly inventory/apply recoverable cleanup of missing checkout paths |
pause --reason <text> | Create the emergency valve and durable checkpoint |
revise --reason <text> [--exact-next-work <text>] | Append immutable plan revision N+1 |
resume [--plan-revision <n>] | Validate checkpoint and resume |
cancel --reason <text> | Terminal cancellation with audit history |
audit [--since <revision-or-event>] [--json] / watch | Inspect immutable events |
| `migrate --check | --apply` |
| `rollout status | observe |
phase, stage, change, task | Submit typed work-structure mutations |
completion, decision, blocker | Record independent completion, decisions, and blockers |
Full runbooks: KBD control plane, tokens, and operator controls.
Registry maintenance keeps the KBD-global --path option before the projects
subcommand and the maintenance flags after it:
prometheus kbd --path "/path/to/project" projects --prune-missing --json
prometheus kbd --path "/path/to/project" projects --prune-missing --apply --json
See Identity & Authentication for backup evidence and rollback behavior.
The MCP port table
scripts/mcp-port-table.json is the declared source of truth for MCP connectivity. The full table is on the MCP Substrate page; in brief: surreal-memory (23001, SSE), prometheus-knowledge (8942, SSE), forge-rs (8943, SSE), and the stdio servers sycophancy-correction, liter-llm, sequential-thinking, tavily, and firecrawl.
scripts/scheduled/
| File | Purpose |
|---|---|
periodic-nudge.sh | Runs every 4 hours (launchd ai.prometheus.prometheus-nudge); POSTs a heartbeat to surreal-memory REST after a /health check; no-ops when unreachable; logs to ~/.prometheus/logs/ |
shared/scripts/ — the runtime hooks
These are the scripts the hooks fire (the events are mapped on the Hooks & Lifecycle page). Grouped by function:
Context injection — immutable scoped snapshot readers, position-on-prompt.sh, detect-project-context.sh, pk-health.sh, memory-outbox-flush.sh.
Stop event — kbd-harness-adapter.sh stop <harness> queues bounded,
noncritical work and never blocks operator stop. Older summary/position
utilities remain implementation helpers but are no longer the installed
Claude Stop chain.
Position / waypoint — write-position-reminder.sh, plus lib/waypoint-render.sh.
Memory — enqueue-memory-operation.py, memory-outbox-flush.sh, and lib/memory-bridge.sh. Hooks publish locally; the worker owns remote receipt reconciliation.
Certification integrity — verify-protected-tests.mjs compares committed
Git states and validates SSH-signed approval manifests. It does not intercept
Bash, Python, Edit, or Write. scope-guard.sh,
pipeline-enforce.sh, cedar-skill-gate.sh, guard-direct-deploy.sh, and
check-child-scope.sh were unwired from PreToolUse — see
Hooks & Lifecycle. The
scripts remain on disk and can still be invoked directly during local work.
PostToolUse companions — scope-record.sh, validate-gitops-write.sh, sycophancy-check-artifact.sh.
SubagentStop gates — sycophancy-check-reflection.sh, evaluate-session.sh, propose-skill-update.sh, subagent-checkpoint-fallback.sh.
KBD lifecycle and journal authority — kbd-harness-adapter.sh,
kbd-phase-status.sh, kbd-next-phase.sh, and
lib/runtime-authority.sh.
Value-phase boundary (VLBV) — run by hand at the boundary, not by a hook:
| Script | Purpose |
|---|---|
kbd-contract-adopt.sh | Adopt or amend a phase contract; --lint-only runs the adoption lint alone |
kbd-phase-readiness-check.sh | Read-only readiness gate against canonical state. Prints READY, or a rejection listing what is missing or failed (contract, identity, adoption digest and the rest). --phase <id> |
kbd-boundary-authorize.mjs | Record the owner's authorization of B4 or B5 before the first attempt, as an append-only event in the phase's boundary-authorization.json. --phase <id> --authorizer <who> [--boundary B4|B5] [--reason] [--project]. Exit 2: phase not bound; exit 3: ordering violated |
kbd-phase-close-eval.sh | Evaluate boundary-results.json against the bound contract, record one canonical disposition, and write closure.json and closure-packet.md |
kbd-closure-packet.mjs | The derived closure view. Includes the passive scan that lists runner output, under the contract's boundaryPacket.runnerOutputGlobs, modified before the B4 authorization |
When to use each is covered in Boundary authorization and early-execution evidence.
Lint / health / verification — pk-lint.sh, pk-health.sh, verify-trace-state.sh.
Shared libraries (lib/) — hook-log.sh, path-scope.sh,
sycophancy.sh, memory-bridge.sh, runtime-authority.sh, and
waypoint-render.sh.
Scheduled (shared/scripts/scheduled/) — ai.prometheus.mem0-compress.plist, ai.prometheus.pk-lint.plist, mem0-compress.cron, pk-lint.cron. The mem0 compression runs weekly; the pk lint --fix sweep runs weekly.
evals/vlbv-protocol/ — per-harness method evidence
These scripts measure whether an agent on each harness follows VLBV. Each agent sample is a paid model session, so they run only at a phase boundary. Full procedure: Protocol evals and capability evidence.
| Script | Purpose |
|---|---|
machinery.mjs | The 6 harness-independent cases against the real runtime and close evaluator. [--negative --at ATnn] |
run.mjs | The 17 agent cases per harness, in isolated scratch homes; writes and validates evals/reports/<harness>.{json,md}. --harness <id[,id]|all> [--samples 3] [--report-dir] [--concurrency] [--timeout-min] |
validate-report.mjs | Re-derive every verdict from retained artifacts. --harness <id> [--negative] |
apply-capabilities.mjs | Promote capabilities.json fields to supported from PASS cases only, then regenerate the harness adapters. --reports <dir> [--negative] |
scan-fixture.mjs | Drive the pre-authorization artifact scan through the production entry points. --case mixed|all-after |
scan-secrets.mjs | Refuse credential-shaped text in reports and transcripts. <path>... |
prometheus-exec
init, daemon, mcp, run, status, doctor, verify, verify-bundle, and contracts are the complete CLI command surface. doctor, verify, and verify-bundle are non-mutating. The generated CLI flag, REST route, request/receipt field, MCP tool, component, target, and evidence tables live in the generated runtime reference.
How the surfaces relate
The mental model: npm run is the human entry point; it wraps the shell/JS/TS scripts in scripts/; those build the binaries and write the configs; the binaries run as background MCP services; and the hook scripts in shared/scripts/ call those binaries at lifecycle events. The next pages — Installation and Updating — put these commands in the order you actually run them.
Previous: ← 15 · Hooks & Lifecycle · Next: 17 · Platform Support →