CLI reference

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:

Option	Description
`--quiet`, `-q`	Minimal output
`--json`, `-j`	JSON output (shape depends on command)
`--force-rich`	Force Rich renderer in non-TTY environments
`--port NAME=SPEC`	Register a runtime port for this invocation

Command map

Command	Purpose
`noesis run`	Start a baseline episode
`noesis view`	Inspect an episode by ID or path
`noesis ps`	List recent episodes
`noesis processes`	List process registry entries
`noesis runs`	List runs for one process
`noesis events`	Stream or envelope episode events
`noesis insight`	Show insight events
`noesis explain`	Explain governance/veto decisions
`noesis diagnostics`	Run health checks or replay compare
`noesis validate-ports`	Validate active runtime ports
`noesis browse`	Open interactive TUI browser
`noesis migrate-layout`	Migrate legacy on-disk layout
`noesis help`	Show 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.

API reference

Schema reference

Configuration

Install

Global options

Command map

Core workflows

Run an episode

Inspect and filter episodes

Inspect one episode

Read events

Process-oriented inspection

Diagnostics and integrity

Other utility commands

Command constraints

Verification flags on `run`

JSON output shape by command

Troubleshooting

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

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

`episode not found: <id>`

`error: corrupted events.jsonl at ...`

`Textual not available: ...` on `noesis browse`

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

​Install

​Global options

​Command map

​Core workflows

​Run an episode

​Inspect and filter episodes

​Inspect one episode

​Read events

​Process-oriented inspection

​Diagnostics and integrity

​Other utility commands

​Command constraints

​Verification flags on run

​JSON output shape by command

​Troubleshooting

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

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

​episode not found: <id>

​error: corrupted events.jsonl at ...

​Textual not available: ... on noesis browse

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

Install

Global options

Command map

Core workflows

Run an episode

Inspect and filter episodes

Inspect one episode

Read events

Process-oriented inspection

Diagnostics and integrity

Other utility commands

Command constraints

Verification flags on `run`

JSON output shape by command

Troubleshooting

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

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

`episode not found: <id>`

`error: corrupted events.jsonl at ...`

`Textual not available: ...` on `noesis browse`

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