> ## Documentation Index
> Fetch the complete documentation index at: https://noesis-32c1d602-cursor-technical-documentation-improvements.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Command reference for the shipped Noēsis CLI entrypoint.

The `noesis` CLI entrypoint is implemented in `noesis/cli/__main__.py`.

<Note>
  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.
</Note>

## Install

Install from source:

```bash theme={null}
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

```bash theme={null}
noesis run "Draft release notes"
```

Run with verification inputs:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
noesis events ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C --phase governance
```

### Process-oriented inspection

```bash theme={null}
# Process liveness and metadata
noesis processes --limit 20

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

### Diagnostics and integrity

```bash theme={null}
# 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

```bash theme={null}
# 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`.