Skip to content
Clasper Core

CLI Reference

CLI Reference

Section titled “CLI Reference”

The clasper-core CLI is the primary way to inspect governance decisions, list policies, and run operations locally. Use it via npx clasper-core or globally after clasper-core link.

Quick start

Section titled “Quick start”
Terminal window
# List recent decisions (requires --ops-api-key to mint adapter token)
npx clasper-core decisions latest --ops-api-key <key>


# Inspect a specific decision
npx clasper-core decisions show <decision_id> --ops-api-key <key>


# Install policy starter pack
npx clasper-core policy install safe-defaults

Authentication

Section titled “Authentication”

Several commands (decisions, policies) call adapter-facing APIs. You must provide either:

  • --ops-api-key <key> — Ops API key; the CLI mints a short-lived adapter token from /ops/api/adapter-probe-token
  • --adapter-token <token> — Direct adapter JWT (when you have one)

Set OPS_LOCAL_API_KEY in .env or pass --ops-api-key explicitly.

Commands

Section titled “Commands”

Server and setup

Section titled “Server and setup”
CommandDescription
devStart Clasper Core development server
serveStart the HTTP server (production build)
setupInteractive setup wizard with install profiles
init [dir]Create workspace from template (default: ./workspace)
linkRun npm link for global clasper-core command
statusShow health, port, and configuration summary

setup options

  • --profile <profile> — core | openclaw
  • --non-interactive — Run without prompts
  • --port <port> — Set CLASPER_PORT
  • --adapter-secret <secret> — Set ADAPTER_JWT_SECRET
  • --approval-mode <mode> — allow | block
  • --skip-openclaw — Skip OpenClaw integration
  • --upgrade-openclaw-plugin — Upgrade/sync OpenClaw plugin
  • --link — Run npm link without prompting

init options

  • -f, --force — Overwrite existing files

Decisions

Section titled “Decisions”

Inspect governance decisions (allow, deny, require_approval, pending).

Terminal window
npx clasper-core decisions [action] [id]
ActionDescription
latestShow recent decisions (default)
tailStream new decisions (polls API)
show <id>Detail + explain for one decision

Options

  • --base-url <url> — API base URL (default: http://localhost:8081)
  • --ops-api-key <key> — Ops API key (mints adapter token)
  • --adapter-token <token> — Adapter token directly
  • --tool <name> — Filter by tool name
  • --decision <value> — Filter: allow | deny | require_approval | pending
  • --since <value> — Time filter: 10m, 1h, or ISO timestamp
  • --limit <n> — Result limit (default: 20)
  • --interval-ms <n> — Tail poll interval (default: 2000)

Example output (latest)

TIME       TOOL             POLICY                     RESULT
19:02:14   http.request     deny-external-http          DENY
19:01:59   llm.ask          citation-required          ALLOW
19:01:40   payment.charge   approval-required          PENDING

Policies

Section titled “Policies”

List effective adapter policies.

Terminal window
npx clasper-core policies list

Options

  • --base-url <url> — API base URL
  • --ops-api-key <key> — Ops API key
  • --adapter-token <token> — Adapter token
  • --limit <n> — Result limit (default: 50)
  • --offset <n> — Pagination offset

Policy packs

Terminal window
npx clasper-core policy install [pack]
  • [pack] — Pack name (default: safe-defaults)
  • --out <dir> — Output base directory (default: policies)

Creates files under policies/<pack>/ (e.g. deny-external-http.yaml, require-citation.yaml). Does not overwrite existing directories or auto-activate policies.

Traces

Section titled “Traces”
Terminal window
npx clasper-core trace [action] [id]
ActionDescription
listList recent traces (default)
replayReplay trace (decision context)
simulateRe-run policy evaluation with current policies

Options

  • --base-url <url> — Ops API base URL
  • --ops-api-key <key> — Ops API key
  • --tenant-id <id> — Tenant ID (default: local)

Seed

Section titled “Seed”

Run seed scripts from any directory.

Terminal window
npx clasper-core seed <target>
  • openclaw — Seed OpenClaw policies
  • ops — Seed Ops data

Export

Section titled “Export”

Create a self-attested export bundle (trace + audit).

Terminal window
npx clasper-core export [options]

Options

  • --base-url <url> — Ops API base URL
  • --ops-api-key <key> — Ops API key
  • --tenant-id <id> — Tenant ID
  • --workspace-id <id> — Workspace ID
  • --trace-id <id> — Single trace export
  • --start-date <iso> — Start date
  • --end-date <iso> — End date
  • --out <path> — Output path (default: ./clasper-export-<timestamp>.tar.gz)

Dashboard

Section titled “Dashboard”

Open the Ops Console in your browser.

Terminal window
npx clasper-core dashboard
  • --port <port> — Override CLASPER_PORT from .env

Policy tests

Section titled “Policy tests”

Run policy tests from a YAML file (requires server + Ops API key).

Terminal window
npx clasper-core test [file]
  • [file] — Test file path (default: policy_tests.yaml)

Test file format

tests:
  - name: "deny rm"
    event:
      tenant_id: local
      action: exec
      context: { exec: { argv0: "rm" } }
    expected: { decision: deny }

Background scripts

Section titled “Background scripts”
CommandDescription
dispatcherRun notification dispatcher loop
heartbeatRun heartbeat (set USER_ID, AGENT_ROLE)
standupRun daily standup

Verification

Section titled “Verification”

To verify governance posture and runtime behavior:

Terminal window
npm run prove:governance

With Clasper running and OPS_LOCAL_API_KEY set, this seeds OpenClaw policies, fetches posture from /api/adapter/posture, and runs a synthetic decision probe using __clasper_probe__.

Section titled “Related”