Skip to main content

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.

BinaryRoleDocumented in
prometheusSkill management, canonical KBD control/audit, self-learning, GitOps validation, Cedar policy, sycophancy13
forgeEnrichment, reflection, drift, templates, MCP server13
pk / pk-cherryKarpathy KB CLI / MCP bridge13
liter-llmLLM proxy + MCP tool server13
surreal-memory-serverGraph memory + MCP + durable v2 receipt API13
prometheus-learning-workerQueue, receipt, and snapshot reconciliation13
prometheus-rust-auditorStaged Rust quality pipeline13

The npm script surface​

package.json (ES module) is the most common entry point.

CommandWhat it does
npm run validateValidate native skills (excludes submodules), 0 errors required
npm run validate:strictStrict 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:signalsLint that every process skill declares a ## Progress Signals section
npm run doctorCanonical local diagnosis parity with prometheus doctor
npm run docs:checkPublic safety, OpenAPI/examples, semantic drift, links/sidebars, production build
npm run buildBuild the marketplace distribution (the .claude-plugin/ symlinks)
npm run install:user / install:projectInstall skills to ~/.claude/skills/ or .claude/skills/
npm run install:platformsMulti-platform installer (tsx) with full plugin support
npm run install:opencode / install:skillsOpenCode install / immutable generation projection
npm run generate:commands / register:commands / unregister:commandsGenerate/register native slash commands
npm run skill-matrix / skill-matrix:ciPairwise skill-similarity collision report
npm run update / update:forcePull and delta-install changed skills
npm run format / check-formatPrettier

scripts/ — installers, validators, generators​

ScriptPurpose
install-plugin-generation.jsStage, hash, verify, activate, roll back, or uninstall an immutable generation (canonical ~/.agents/skills copies plus Claude/Qwen shims). [--verify] [--rollback] [--uninstall]
install-prometheus-exec.shBuild/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.shReproducible 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.shSourced 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.shSourced 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.shRender 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.tsMulti-platform symlink installer for Claude Code, OpenCode, Cursor, Codex, etc. [--platform] [--scope] [--uninstall] [--list]
install.jsCopy skills to user or project scope
install-binaries.shBuild 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.shRender/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.shMerge mcp-port-table.json into each tool's native MCP config (idempotent). [--dry-run] [--tool]
prometheus-services.shManage MCP services as macOS user LaunchAgents (install/load/status/doctor/…)
register-slash-commands.shRegister skills as OpenCode commands and Codex prompt files. [--uninstall]
generate-commands.jsGenerate Claude Code slash-command files from skill frontmatter. [--output] [--uninstall]
check-prerequisites.shCheck/install Node, Rust, npm deps; build tool binaries. [--install] [--build-tools]
check-mcp-health.shHealth table (service state + HTTP readiness) for non-excluded services. [--json] [--exclude]
certify-memory-operations.shMutating local proof of exact replay, conflict, response-loss reconciliation, terminal receipts, SSE resume, and optional long memory.
smoke-test.shConfirm every tool binary is reachable and answers --version
detect-command-conflicts.shDetect slash-command name collisions across installed command dirs
skill-matrix.jsPairwise Jaccard similarity of skill name+description; CI fails on un-allowlisted collisions
validate-skills.jsThe AgentSkills.io validator (Ajv schema). [--strict] [--exclude-submodules]
validate-progress-signals.jsMerge gate for the ## Progress Signals section; ratchet baseline
backfill-strict-fields.jsBackfill missing version/license/metadata.tags into SKILL.md. [--dry-run]
build-marketplace.jsBuild the .claude-plugin/ symlink distribution
update-skill-pack.shGit-pull then delta-install changed skills across platforms (tracks last SHA). [--force]
generate-harness-adapters.jsGenerate Claude Code, Codex, OpenCode, and Kimi lifecycle adapters from one capability manifest
check-harness-adapters.jsReject 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.jsReject new direct writers to canonical KBD compatibility projections
validate-kbd-state.jsValidate KBD projection schemas and revision relationships
test-kbd-control-plane.shRun runtime/journal/control-plane fixture tests
generate-skill-eval-corpus.js / check-skill-evals.jsMaintain 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
CommandPurpose
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] / watchInspect immutable events
`migrate --check--apply`
`rollout statusobserve
phase, stage, change, taskSubmit typed work-structure mutations
completion, decision, blockerRecord 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/​

FilePurpose
periodic-nudge.shRuns 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:

ScriptPurpose
kbd-contract-adopt.shAdopt or amend a phase contract; --lint-only runs the adoption lint alone
kbd-phase-readiness-check.shRead-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.mjsRecord 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.shEvaluate boundary-results.json against the bound contract, record one canonical disposition, and write closure.json and closure-packet.md
kbd-closure-packet.mjsThe 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.

ScriptPurpose
machinery.mjsThe 6 harness-independent cases against the real runtime and close evaluator. [--negative --at ATnn]
run.mjsThe 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.mjsRe-derive every verdict from retained artifacts. --harness <id> [--negative]
apply-capabilities.mjsPromote capabilities.json fields to supported from PASS cases only, then regenerate the harness adapters. --reports <dir> [--negative]
scan-fixture.mjsDrive the pre-authorization artifact scan through the production entry points. --case mixed|all-after
scan-secrets.mjsRefuse 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 →