CLI Commands

All examples use pnpm dev:cli -- to invoke the CLI from the repo root. Replace with your preferred invocation (e.g. a global nous binary) if configured.

send

Send a message to Nous.

pnpm dev:cli -- send <message> [--project <id>]

Arguments:

• message — The message to send

Options:

• -p, --project <id> — Project ID for context (inherited from global --project if set)

Example:

pnpm dev:cli -- send "What is the capital of France?"
pnpm dev:cli -- -p abc-123 send "Summarize our last conversation"

Output: Full response text. With --json, returns structured response including traceId.

projects

Manage projects.

projects list

List all projects.

pnpm dev:cli -- projects list
pnpm dev:cli -- projects

projects create

Create a new project.

pnpm dev:cli -- projects create --name <name>

Options:

• --name <name> — Project name (required)

projects switch

Switch the active project for subsequent commands.

pnpm dev:cli -- projects switch -p <id>

Options:

• -p, --project <id> — Project ID to switch to (required)

config

View and modify configuration.

config get

Get current configuration.

pnpm dev:cli -- config get

With --json, returns full config as JSON.

config set

Modify configuration.

pnpm dev:cli -- config set --Cortex-tier <0-5>

Options:

• --Cortex-tier <0-5> — Set Cortex tier

Example:

pnpm dev:cli -- config set --Cortex-tier 4

Model role assignments can be modified via the web UI Configuration panel.

pkg

Inspect advisory marketplace suggestions and install governed packages through the canonical install pipeline.

pkg install

Install or update a package for a project through the canonical package install pipeline.

pnpm dev:cli -- pkg install <package-id> --project <id>
pnpm dev:cli -- pkg install <package-id> --project <id> --version ^2.0.0
pnpm dev:cli -- pkg install <package-id> --project <id> --release rel_123
pnpm dev:cli -- --api-url http://localhost:4317 pkg install <package-id> --project <id>

Arguments:

• package-id — Registry package ID to install

Options:

• -p, --project <id> — Project ID that owns the install (required)
• --version <range> — Install the newest release satisfying this semver range
• --release <id> — Install one specific registry release ID
• --api-url <url> — Override the API base URL for the current invocation

Output:

• Default output prints Installed <package-id> followed by the canonical install order when the install succeeds
• Failure output prints the install status (blocked or rolled_back) plus the canonical reason code, and exits non-zero
• With --json, returns the full PackageInstallResult

Important behavior:

• pkg install routes through the same canonical resolver, planner, lifecycle gates, and materialization pipeline used by first-party surfaces.
• --release and --version are mutually exclusive.
• Installs fail closed when dependency ranges conflict, trust/lifecycle gates block the request, or a write must be rolled back.

pkg discover

Fetch the canonical marketplace discovery feed for the current project or an explicitly selected project.

pnpm dev:cli -- pkg discover
pnpm dev:cli -- pkg discover --project <id> --limit 10
pnpm dev:cli -- pkg discover --project <id> --dismiss <candidate-id>
pnpm dev:cli -- pkg discover --project <id> --snooze <candidate-id>
pnpm dev:cli -- pkg discover --project <id> --mute-category <candidate-id>
pnpm dev:cli -- pkg discover --project <id> --mute-project <candidate-id>
pnpm dev:cli -- pkg discover --mute-global <candidate-id>

Options:

• -p, --project <id> — Project ID for trust-eligibility and project-scoped suppression (optional unless using --mute-project)
• --limit <n> — Maximum number of suggestion cards to return (default: 5)
• --signal <ref> — Append an evidence or signal reference used to contextualize the feed request (repeatable)
• --dismiss <candidate-id> — Apply dismiss_once suppression to one candidate in the current feed
• --snooze <candidate-id> — Apply a 30-minute snooze to one candidate in the current feed
• --mute-category <candidate-id> — Mute the candidate's source category across enabled surfaces
• --mute-project <candidate-id> — Mute nudges for the selected project across enabled surfaces; requires --project
• --mute-global <candidate-id> — Mute nudges globally across enabled surfaces

Output:

• Default output prints one line per candidate: candidate_id, source_ref, origin trust tier, and the current distribution_status/compatibility_state trust-eligibility posture
• Follow-up lines include "why this" reasoning and the available suppression actions for that card
• With --json, returns { feed, suppression }

Important behavior:

• pkg discover is advisory only. It does not install, enable, or execute packages.
• The CLI consumes the same canonical marketplace discovery feed used by the web marketplace surface.
• Feedback for opened cards and any applied suppression action is written back through the canonical marketplace runtime.
• Use pkg install after review when you want to install a governed package for a project.

opctl

Operator control commands.

opctl request-proof

Request a runtime-issued confirmation proof for T1+ control actions. Use the proof with submitCommand when submitting pause, cancel, hard_stop, or other tiered actions.

pnpm dev:cli -- opctl request-proof --action <action> --tier <T1|T2|T3> [--project <id>]

Options:

• --action <action> — Control action (e.g. pause, cancel, hard_stop) (required)
• --tier <tier> — Confirmation tier: T1, T2, or T3 (required)
• --project <id> — Project ID for scope (optional)
• --scope-kind <kind> — Scope kind: single_agent, agent_set, project_run (default: project_run)
• --scope-class <class> — Scope class (default: project_run_scope)
• --reason <text> — Reason for confirmation (optional, for T2/T3)

Output: Proof ID, action, and expiry. With --json, returns full proof JSON for use with submitCommand via tRPC or web UI.

witness

Run witness verification and inspect verification artifacts.

witness verify

Generate a witness VerificationReport.

pnpm dev:cli -- witness verify
pnpm dev:cli -- witness verify --from 1 --to 200

Options:

• --from <sequence> — Start event sequence (optional)
• --to <sequence> — End event sequence (optional)

With --json, prints full report JSON including receipt and invariants.

witness list

List recent witness verification reports.

pnpm dev:cli -- witness list
pnpm dev:cli -- witness list --limit 25
pnpm dev:cli -- witness

Options:

• --limit <n> — Max reports to return (optional)

witness get

Retrieve a verification report by ID.

pnpm dev:cli -- witness get --id <report-id>

Options:

• --id <report-id> — Verification report ID (required)