Skip to main content
The noesis CLI entrypoint is implemented in noesis/cli/__main__.py.
If you see docs or examples mentioning noesis list, noesis show, or noesis solve, those refer to an older CLI surface. The current shipped commands are documented on this page.

​
Install

Install from source: 
git clone https://github.com/saraeloop/noesis.git
cd noesis
pipx install .
# or: pip install -e .

​
Global options

Most commands accept:
OptionDescription
--quiet, -qMinimal output
--json, -jJSON output (shape depends on command)
--force-richForce Rich renderer in non-TTY environments
--port NAME=SPECRegister a runtime port for this invocation

​
Command map

CommandPurpose
noesis runStart a baseline episode
noesis viewInspect an episode by ID or path
noesis psList recent episodes
noesis processesList process registry entries
noesis runsList runs for one process
noesis eventsStream or envelope episode events
noesis insightShow insight events
noesis explainExplain governance/veto decisions
noesis diagnosticsRun health checks or replay compare
noesis validate-portsValidate active runtime ports
noesis browseOpen interactive TUI browser
noesis migrate-layoutMigrate legacy on-disk layout
noesis helpShow help (or help for one command)

​
Core workflows

​
Run an episode

noesis run "Draft release notes"
Run with verification inputs: 
noesis run "Update config" \
  --workspace . \
  --verify-file-exists config.yaml \
  --verify-file-contains config.yaml --text "enabled: true" \
  --verify-only-modified config.yaml
Emit JSON envelope: 
noesis run "Draft release notes" --json | jq .
--json output includes episode_id, episode_dir, artifacts, outcome, adapter_result, and verification summary fields.

​
Inspect and filter episodes

# Recent episodes
noesis ps --limit 10

# Filter by process id or name
noesis ps --process alpha

# JSON envelope
noesis ps --json | jq '.episodes[0]'

​
Inspect one episode

# Human-readable dashboard
noesis view ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C

# JSON dashboard envelope
noesis view ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C --json | jq .
view accepts either an episode ID or an episode directory path.

​
Read events

# Human-readable events
noesis events ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C

# JSONL mode (one event object per line)
noesis events ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C --json

# Single JSON envelope (ADR-012 style)
noesis events ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C --envelope
Filter by phase: 
noesis events ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C --phase governance

​
Process-oriented inspection

# Process liveness and metadata
noesis processes --limit 20

# Runs for a specific process
noesis runs --process alpha --limit 20

​
Diagnostics and integrity

# Default checks
noesis diagnostics

# Strict mode
noesis diagnostics --strict

# Replay compare
noesis diagnostics replay .noesis/episodes/ep_a .noesis/episodes/ep_b

# Runtime ports
noesis validate-ports
Trace integrity is fail-closed. Commands that read events.jsonl (for example noesis events and noesis view) return a non-zero exit code when the event log is corrupted, rather than skipping bad lines.

​
Other utility commands

# Governance explanation
noesis explain ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C

# Interactive terminal UI
noesis browse

# Migrate old storage layout
noesis migrate-layout

# Help
noesis help
noesis help events

​
Command constraints

​
Verification flags on run

The verification parser enforces:
  • --verify-no-modifications cannot be combined with --verify-only-modified
  • --text requires --verify-file-contains
  • each --verify-file-contains entry must have a matching --text
  • --verify-file must point to an existing JSON file containing a list

​
JSON output shape by command

  • run --json emits a run-result envelope (episode_id, episode_dir, artifacts, outcome, verification, capabilities)
  • ps --json emits {"episodes":[...], ...}
  • processes --json emits {"processes":[...], ...}
  • events --json emits JSONL (one event per line)
  • events --envelope emits one JSON object containing all selected events

​
Troubleshooting

​
usage error: each --verify-file-contains must have a matching --text

Cause: mismatch between repeated --verify-file-contains and --text flags. Fix: provide both flags in matching order and count.

​
usage error: --verify-no-modifications cannot be combined with --verify-only-modified

Cause: mutually exclusive verification constraints. Fix: keep only one of the two flags.

​
episode not found: <id>

Cause: the ID is unknown in the configured runs directory. Fix:
  • check NOESIS_RUNS_DIR / runtime config
  • pass a direct episode directory path to noesis view
  • inspect available episodes with noesis ps

​
error: corrupted events.jsonl at ...

Cause: the episode trace failed integrity checks (for example malformed JSON, invalid UTF-8, or a truncated record). Fix:
  • inspect events.jsonl near the reported line number
  • restore the run artifacts from a known-good copy if available
  • re-run the episode if recovery is not possible

​
Textual not available: ... on noesis browse

Cause: textual is not installed in the current environment. Fix: install UI dependencies, then re-run noesis browse.

​
invalid cli version (expected cli/MAJOR.MINOR) on run --json

Cause: unsupported --cli-version value. Fix: use cli/1.0 or omit --cli-version.