CLI reference

The Noēsis CLI is installed with the package. Run via noesis or uv run noesis.

The CLI surface is intentionally small in this release. A more robust CLI is in active development, with better scripting ergonomics, richer subcommands, and stronger JSON-first workflows. When in doubt, treat noesis <command> --help as the source of truth.

Installation

Install from source while the PyPI name is pending:

git clone https://github.com/saraeloop/noesis.git
cd noesis
uv tool install .
# or: pipx install .

When the PyPI release is live, you can also use uv add noesis or pip install noesis.

Commands

Available for now: run, solve, list, show, view, events, insight, artifacts, diagnostics, version, validate-ports, migrate, new.

noesis run

Run a baseline episode (no adapter).

noesis run "task description" [options]
# or read from stdin
echo "Summarize the README" | noesis run --stdin

Arguments:

Argument	Description
`task`	Task prompt (optional if `--stdin` or `-` is used)

Options:

Option	Description	Default
`-s, --seed INT`	Seed for reproducibility	`0`
`-P, --policy SPEC`	Policy alias or `module:Class` (`on`/`off` accepted)	`on`
`--no-intuition`	Disable intuition entirely	`False`
`--tags JSON`	JSON object of tags to attach	None
`--dir-min FLOAT`	Override `direction_min_confidence`	None
`--stdin`	Read task prompt from STDIN (or pass `-` as task)	`False`
`-y, --yes`	Assume yes for interactive prompts	`False`
`-j, --json`	Emit JSON `{episode_id}`	`False`
`-q, --quiet`	Print only the episode id	`False`

Examples:

# Simple run
noesis run "Draft release notes"

# Policy alias or module:Class
noesis run "Check database" --policy mymodule:SafetyPolicy

# JSON tags object
noesis run "Deploy to staging" --tags '{"env":"staging","team":"platform"}'

# Quiet / JSON forms
noesis run "Test task" -q
noesis run "Test task" -j | jq -r '.episode_id'

noesis solve

Run an episode through a specific adapter/flow.

noesis solve ADAPTER "task description" [options]

Arguments:

Argument	Description
`adapter`	Adapter name or import path (required)
`task`	Task prompt (optional if `--stdin` or `-` is used)

Options:

Option	Description	Default
`-s, --seed INT`	Seed for reproducibility	`0`
`-P, --policy SPEC`	Policy alias or `module:Class` (`on`/`off` accepted)	`on`
`--no-intuition`	Disable intuition entirely	`False`
`--tags JSON`	JSON object of tags to attach	None
`--dir-min FLOAT`	Override `direction_min_confidence`	None
`--stdin`	Read task prompt from STDIN (or pass `-` as task)	`False`
`-j, --json`	Emit JSON `{episode_id}`	`False`
`-q, --quiet`	Print only the episode id	`False`

Examples:

# With registered adapter
noesis solve my-adapter "Process data"

# With module path
noesis solve mymodule:analyzer "Analyze logs"

# Policy + tags
noesis solve deploy-adapter "Deploy" --policy SafetyPolicy --tags '{"env":"prod"}'

noesis list

List recent episodes.

noesis list [options]

Options:

Option	Description	Default
`--limit INT`	Maximum episodes to show	20
`--strict-manifest`	Re-hash manifests and warn on drift	False
`-j, --json`	Output as JSON	False
`-q, --quiet`	Print episode ids only	False

Examples:

# Table output
noesis list --limit 10

# JSON output for scripting
noesis list -j | jq '.[0].episode_id'

Output columns:

Column	Description
Started	Start timestamp
ID	Episode identifier
Task	Truncated task description
Manifest	Status note (only when `--strict-manifest` is used)

noesis show

Display episode summary.

noesis show EPISODE_ID [options]

Arguments:

Argument	Description
`episode_id`	Episode ID to display (required)

Options:

Option	Description	Default
`-j, --json`	Output raw JSON	False
`-q, --quiet`	Print episode id only	False

Examples:

# Friendly output
noesis show ep_2024_abc123_s0

# Raw JSON
noesis show ep_2024_abc123_s0 -j

noesis view

Inspect an episode timeline, metrics, and governance decisions in one view.

noesis view TARGET [options]

Arguments:

Argument	Description
`target`	Episode ID or run directory

Options:

Option	Description	Default
`--pretty`	Render formatted tables	True
`-j, --json`	Emit JSON view	False
`--events`	Stream raw `events.jsonl`	False
`--grep SUBSTR`	Filter timeline rows by substring	None
`--schema VERSION`	Validate against specific summary schema	`latest` (auto)
`--fail-on-invalid`	Exit 1 if validation errors are detected	False
`--open`	Print artifact paths	False

Examples:

# Pretty viewer
noesis view ep_2024_abc123_s0

# JSON
noesis view ep_2024_abc123_s0 -j | jq '.summary.metrics.success'

noesis events

Print events for an episode.

noesis events EPISODE_ID [options]

Arguments:

Argument	Description
`episode_id`	Episode ID to read (required)

Options:

Option	Description	Default
`--phase PHASE`	Filter by phase	None
`-j, --json`	Output events as JSONL	False
`-q, --quiet`	Suppress banner	False

Examples:

# All events
noesis events ep_2024_abc123_s0

# Filter by phase
noesis events ep_2024_abc123_s0 --phase act

# JSON for piping
noesis events ep_2024_abc123_s0 -j | jq '.phase'

# Latest episode
noesis events $(noesis list -j | jq -r '.[0].episode_id')

noesis list returns episodes newest first, so index 0 is the latest run. Phase values:

Phase	Description
`start`	Episode start
`observe`	Input capture
`interpret`	Signal extraction
`plan`	Action planning
`direction`	Policy directives
`intuition`	Policy intuition
`insight`	Insight metrics
`reason`	Reasoning traces
`governance`	Audit decisions
`act`	Tool execution
`reflect`	Outcome evaluation
`learn`	Learning signals
`terminate`	End state
`error`	Error events

noesis insight

Show computed insight events (alias for events --phase insight).

noesis insight EPISODE_ID [options]

Arguments:

Argument	Description
`episode_id`	Episode ID to analyze (required)

Options:

Option	Description	Default
`-j, --json`	Output events as JSONL	False
`-q, --quiet`	Suppress banner	False

Examples:

# Get metrics
noesis insight ep_2024_abc123_s0

# Parse with jq
noesis insight ep_2024_abc123_s0 -j | jq '.metrics.success'

noesis artifacts

Verify artifact manifests.

noesis artifacts verify TARGET [options]

Arguments:

Argument	Description
`target`	Episode ID, run directory, or manifest path

Options:

Option	Description	Default
`--strict`	Fail when unexpected files are present	False
`-j, --json`	Emit JSON report	False
`-q, --quiet`	Suppress human-readable output	False

Exit codes:

Code	Meaning
0	Verified (including warnings)
2	Verification error
3	Missing manifest/files
4	Signature error

Example:

noesis artifacts verify ep_2024_abc123_s0 --strict

noesis diagnostics

Run stability diagnostics (default) or compare two runs for drift.

# Default checks
noesis diagnostics [options]

# Replay comparison
noesis diagnostics replay RUN_A RUN_B [options]

Options (default mode):

Option	Description	Default
`--checks a,b,c`	Comma-separated subset of checks	all
`--strict`	Exit non-zero on warnings	False
`-j, --json`	Emit JSON payload	False
`-q, --quiet`	Suppress human-readable output	False

Checks include runs_dir health, learn_home, confidence bounds, learn thresholds, registered ports, config snapshot drift, latest summary schema, and latest manifest verification. Replay mode options:

Option	Description	Default
`run_a run_b`	Episode directories to compare (required)	—
`-j, --json`	Emit JSON payload	False
`-q, --quiet`	Suppress human-readable output	False

Examples:

# Default diagnostics
noesis diagnostics --strict

# Drift compare two runs
noesis diagnostics replay runs/ep_a runs/ep_b

Replay exits 1 on drift, 0 otherwise. Default mode exits 1 on errors (or warnings when --strict).

noesis version

Show CLI/core version and available adapters.

noesis version [-j]

Options:

Option	Description	Default
`-j, --json`	Emit JSON payload	False

noesis validate-ports

List registered runtime ports from the active session.

noesis validate-ports [-j|-q]

Options:

Option	Description	Default
`-j, --json`	Emit JSON payload	False
`-q, --quiet`	Suppress human output	False

noesis migrate

Codemod deprecated Noēsis shims to the modern API.

noesis migrate [paths...] [--dry-run] [-j]

Options:

Option	Description	Default
`paths...`	Files or directories (defaults to `.`)	`.`
`--dry-run`	Preview changes without modifying files	False
`-j, --json`	Emit JSON report	False

Exit codes:

Code	Meaning
0	No issues
1	Errors encountered
2	TODOs or skipped items remain

noesis new

Experimental scaffolder placeholder.

noesis new [flow|policy] NAME [-j|-q]

Returns a TODO message today.

Global options

These options work with all commands:

Option	Description
`--compact`	Compact output (summary only)
`--verbose`	Verbose output (detailed reasoning)
`--debug`	Debug mode (implies verbose)
`--port NAME=SPEC`	Register a runtime port (repeatable)
`--help`	Show help message

Environment variables

Variable	Description
`NOESIS_RUNS_DIR`	Default runs directory
`NOESIS_PLANNER`	Default planner mode (`meta`/`minimal`)
`NOESIS_DIRECTION_MIN_CONFIDENCE`	Default `direction_min_confidence`
`NOESIS_INTUITION_MODE`	Default intuition mode
`NOESIS_TIMEOUT_SEC`	Default timeout
`NOESIS_LEARN_HOME`	Default learn directory
`NOESIS_LEARN_MODE`	Default learn mode
`NOESIS_LEARN_AUTO_APPLY_MIN_SUCCESSES`	Minimum successes before auto-apply
`NOESIS_LEARN_AUTO_APPLY_MIN_CONFIDENCE`	Confidence threshold for auto-apply
`NOESIS_PROMPT_PROVENANCE_ENABLED`	Enable prompt provenance (`true`/`false`)
`NOESIS_PROMPT_PROVENANCE_MODE`	Provenance mode
`NOESIS_AGENTS`	Agent registry path override
`NOESIS_TASKS`	Tasks registry path override

Example:

# Set planner mode via environment
NOESIS_PLANNER=minimal noesis run "Quick test"

# Set runs directory
NOESIS_RUNS_DIR=./my-runs noesis list

Scripting patterns

Get latest episode ID

LATEST=$(noesis list -j | jq -r '.[0].episode_id')
noesis show $LATEST

Check success rate

noesis list -j --limit 100 | jq '[.[] | select(.success != null) | .success] | (add / length)'

Export metrics to CSV

noesis list -j | jq -r '.[] | [.episode_id, .success, .started_at] | @csv' > episodes.csv

Filter by manifest drift

noesis list -j --strict-manifest | jq '[.[] | select(.manifest_status != null and .manifest_status != "ok")]'

Tail direction events

noesis events $(noesis list -j | jq -r '.[0].episode_id') --phase direction

Batch process episodes

for ep in $(noesis list -j | jq -r '.[].episode_id'); do
  echo "Processing $ep"
  noesis insight $ep > "insights/$ep.json"
done

Exit codes

Core CLI exit codes (noesis/cli/errors.py):

Code	Meaning
0	Success
1	General error (`EXIT_ERROR`)
2	Invalid usage / argument errors (`EXIT_USAGE`)
3	Episode vetoed by governance (`EXIT_VETO`)

Some subcommands add their own codes. For example, noesis artifacts verify uses dedicated codes for verification results (missing files, signature failures, etc.). Check noesis <command> --help if you need exact codes in CI.

API reference

Schema reference

Configuration

Installation

Commands

noesis run

noesis solve

noesis list

noesis show

noesis view

noesis events

noesis insight

noesis artifacts

noesis diagnostics

noesis version

noesis validate-ports

noesis migrate

noesis new

Global options

Environment variables

Scripting patterns

Get latest episode ID

Check success rate

Export metrics to CSV

Filter by manifest drift

Tail direction events

Batch process episodes

Exit codes

Next steps

Python API

Quickstart

API reference

Schema reference

Configuration

​Installation

​Commands

​noesis run

​noesis solve

​noesis list

​noesis show

​noesis view

​noesis events

​noesis insight

​noesis artifacts

​noesis diagnostics

​noesis version

​noesis validate-ports

​noesis migrate

​noesis new

​Global options

​Environment variables

​Scripting patterns

​Get latest episode ID

​Check success rate

​Export metrics to CSV

​Filter by manifest drift

​Tail direction events

​Batch process episodes

​Exit codes

​Next steps

Python API

Quickstart

Installation

Commands

noesis run

noesis solve

noesis list

noesis show

noesis view

noesis events

noesis insight

noesis artifacts

noesis diagnostics

noesis version

noesis validate-ports

noesis migrate

noesis new

Global options

Environment variables

Scripting patterns

Get latest episode ID

Check success rate

Export metrics to CSV

Filter by manifest drift

Tail direction events

Batch process episodes

Exit codes

Next steps