# Product Requirements Document: axiom CLI

> **Implementation Status: 🟡 Partial** — Core CLI, extension discovery, and 17 builtin extensions shipped. Agents (Neut, EVE, M-O, PR-T, D-FIB) operational. Future domain commands (`log`, `sim`, `model`, `twin`, `data`, `infra`) planned.

**Module:** axiom Command-Line Interface
**Status:** Active Development (v0.4.0)
**Last Updated:** 2026-03-17
**Parent:** [Executive PRD](prd-executive.md)
**Tech Spec:** [axiom CLI Specification](../tech-specs/spec-axi-cli.md)

---

## Executive Summary

`axi` is the unified command-line interface for Axiom. It provides operators, researchers, and developers a single entry point for interacting with the platform — from querying ops logs to managing surrogate models to orchestrating simulations.

The CLI embodies the platform philosophy: **power tools for experts, sensible defaults for everyone else**.

Every capability in Axiom ships as an **extension**, discovered via `axiom-extension.toml` manifests. The CLI is the primary interface for both humans and agents — the same commands a user types are the same commands agents invoke programmatically.

---

## Problem Statement

Nuclear facilities currently interact with data and simulations through:
- **Fragmented interfaces**: Web dashboards, ad-hoc scripts, manual file transfers
- **No automation path**: Can't script operational queries or model deployments
- **Platform lock-in**: GUI-only tools prevent integration with CI/CD pipelines
- **Tribal knowledge**: "How to run X" lives in people's heads, not in reproducible commands

---

## User Personas

| Persona | Primary Use Cases | Technical Level |
|---------|-------------------|-----------------|
| **System Operator** | Query ops log, check status, export compliance reports | Basic CLI |
| **Research Engineer** | Run simulations, manage experiments, analyze data | Intermediate |
| **Data Engineer** | Orchestrate pipelines, manage schemas, debug transforms | Advanced |
| **ML Engineer** | Train/deploy surrogates, manage WASM extensions | Advanced |
| **DevOps** | Infrastructure management, CI/CD integration | Expert |

---

## The Agent Team

Axiom agents are named after robots from Pixar's WALL-E — a film about a world made uninhabitable by environmental neglect. The irony is intentional: Axiom helps build the cleanest large-scale energy source available.

| Agent | Character | CLI | Role | REPL Role |
|-------|-----------|-----|------|-----------|
| **WALL-E** | WALL-E | `axiom chat` | Orchestrator — routes commands, delegates to other agents, maintains context. Branded as "Neut" in NeutronOS | **Loop** |
| **EVE** | Probe droid | `axiom signal` | Event Evaluator — signal detection and intelligence extraction | **Read** |
| **CURI-O** | — | `axiom research` | Research agent — autonomous RAG optimization and knowledge synthesis | **Eval** |
| **M-O** | Cleaning robot | `axiom mo` | Micro-Obliterator — resource stewardship and system hygiene | Infrastructure |
| **PR-T** | Beauty bot | `axiom pub` | Purty — document lifecycle, .md → polished .docx → publish. Also owns content gating (formerly Mirror) | **Print** |
| **D-FIB** | Medical bot | `axiom doctor` | Defib — diagnostics, health, configuration audit. Also owns security checks (formerly SECUR-T) | Health |
| **BURN-E** | Welder bot | `axiom release` | Release agent — build, tag, ship | Ship |
| ~~Mirror~~ | — | ~~`axiom mirror`~~ | Deprecated — agent retired, content gate absorbed by PR-T | — |
| ~~SECUR-T~~ | — | — | Retired — security ownership transferred to D-FIB | — |

Agents follow a **REPL model** (Read-Eval-Print-Loop): EVE reads signals in, CURI-O evaluates and synthesizes knowledge, PR-T prints publishable output, and WALL-E is the interactive loop that orchestrates the cycle.

---

## Shipped Commands

### Core Platform

| Command | Extension | Kind | Description |
|---------|-----------|------|-------------|
| `axiom config` | core | utility | Interactive onboarding wizard |
| `axiom status` | status | utility | System health dashboard |
| `axiom doctor` | dfib (D-FIB) | agent | Diagnose environment issues |
| `axiom ext` | core | utility | Manage extensions (builtin + user) |
| `axiom update` | update | utility | Dependency and migration updates |
| `axiom settings` | settings | utility | View and edit axiom settings |
| `axiom test` | test | utility | Test orchestration |

### Agents

| Command | Extension | Description |
|---------|-----------|-------------|
| `axiom chat` | axi_agent (Axi) | Interactive agent with tool calling. Alias: `axiom code` |
| `axiom signal` | eve_agent (EVE) | Agentic signal ingestion pipeline |
| `axiom pub` | prt_agent (PR-T) | Document publishing lifecycle. Alias: `axiom doc` |
| `axiom mo` | mo_agent (M-O) | Resource steward — scratch, vitals, cleanup |
| ~~`axiom mirror`~~ | ~~mirror_agent~~ | Deprecated — content gate absorbed by PR-T |

### Tools & Services

| Command | Extension | Description |
|---------|-----------|-------------|
| `axiom db` | db | PostgreSQL + pgvector infrastructure |
| `axiom rag` | rag | RAG index management — index, search, sync the three-tier corpus |
| `axiom demo` | demo | Guided demonstrations and walkthroughs |
| `axiom note` | note | Quick personal notes — captured to RAG-indexed daily log |
| `axiom serve` | web_api | Start the axiom HTTP API server |

---

## Neut: The Orchestrator (`axiom chat`)

Neut is the interactive agent — think Claude Code, but for operations facilities. Neut orchestrates all other agents and tools on behalf of the user.

### Interaction Modes

Neut operates in three modes that represent **levels of autonomy**, not different personalities. The default is Ask — the safest mode — and Neut escalates only with the user's consent.

| Mode | Autonomy | What Neut Does | Side Effects |
|------|----------|----------------|-------------|
| **Ask** (default) | None | Answers questions, explains, searches. Read-only. | Zero |
| **Plan** | Propose | Explores the problem, designs an approach, presents structured options. | Zero until approved |
| **Agent** | Execute | Runs multi-step tasks autonomously within scoped permissions. | Bounded writes |

### Escalation Model

Neut always starts in **Ask** mode. When a prompt implies action, Neut proposes escalation rather than assuming permission:

```
Operator: "Set up experiment UT-facility-043 with the standard NAA config"

Neut (Ask): I can help set that up. This will create a new experiment
            record, reserve beam port 3, and generate the ROC
            authorization request.

            → Switch to Plan mode to walk through the steps? [y/N]
```

Power users can skip escalation with `axiom chat --mode plan` or mid-conversation with `/plan`, `/ask`, `/agent`.

### Session & UX Flags

| Flag | Description |
|------|-------------|
| `--resume` | Continue the most recent session |
| `--session <id>` | Continue a specific session by ID |
| `--list` | List recent sessions (ID, title, messages, cost, last active) |
| `--sync` | Sync local JSON sessions to PostgreSQL |
| `--simple` | Read-only tools only (no writes) |
| `--tools <list>` | Restrict to named tools (comma-separated) |
| `--budget <tokens>` | Set per-session token budget |
| `--json` | Structured JSON output (no streaming, no rich rendering) |
| `--mode <ask\|plan\|agent>` | Start in a specific interaction mode |

Sessions are stored in PostgreSQL when available, with automatic fallback to local JSON files. See [spec-session-store.md](../tech-specs/spec-session-store.md) for the backend and [spec-axi-cli.md §Chat Mode](../tech-specs/spec-axi-cli.md) for detailed UX.

### Slash Commands

Slash commands are the composable action layer inside `axiom chat`. Each command is registered by an extension, follows a standard four-step flow (collect context → present choices → confirm intent → dispatch + report), and always shows the underlying `axi` CLI invocation it dispatched.

This design teaches users the machine API through the conversational interface.

Full slash command design in [CLI Specification §Slash Commands](../tech-specs/spec-axi-cli.md).

### Mode Guardrails

| Guardrail | Behavior |
|-----------|----------|
| **Writes always confirm** | Even in Agent mode, Neut pauses before creating records, publishing, or sending notifications |
| **Agent scope is per-session** | Agent permissions don't persist across sessions |
| **Escalation is reversible** | `/ask` returns to read-only at any time |
| **Structured decisions** | Bounded option spaces use interactive forms, not freetext |
| **Audit trail** | All mode transitions and approved actions are logged |

---

## Planned Commands

These commands are designed but not yet implemented. Each will ship as an extension. CLI examples are drawn from their constituent PRDs — see each for the full command set.

### Model Registry (`axiom model`)

Physics model registry (Model Corral) with version control, validation, and lineage tracking.

```bash
axiom model search "facility transient SimTool"
axiom model list --system=triga --facility=netl
axiom model init ./my-model --system=triga --code=mcnp
axiom model validate ./my-model
axiom model add ./my-model --message="Initial thermal model"
axiom model diff triga-netl-mcnp-v3 triga-netl-mcnp-v2
axiom model lineage triga-netl-rom2-v3
axiom model audit --since=2026-01-01
```

See [Model Corral PRD](prd-model-corral.md).

### Digital Twin Hosting (`axiom twin`)

ROM execution, shadow runs, drift detection, and prediction validation.

```bash
axiom twin run --model=triga-netl-vera-shadow-v4 --type=shadow
axiom twin shadow --facility=netl --date=2026-03-16
axiom twin infer --model=triga-netl-rom2 --input=state.json
axiom twin rom-train --source=triga-netl-vera-shadow-v4 --tier=ROM-2
axiom twin rom-deploy --model=triga-netl-rom2-v3 --target=wasm
axiom twin rom-validate --model=triga-netl-rom2-v3 --dataset=benchmark-2026
axiom twin compare --run=run-2026-03-17-001 --against=measured
axiom twin drift --model=triga-netl-rom2 --since=2026-01-01
axiom twin report --facility=netl --month=2026-03
```

See [Digital Twin Hosting PRD](prd-digital-twin-hosting.md).

### System Operations (`axiom log`)

Console checks, shift handoffs, compliance exports.

```bash
axiom log query --last 1h
axiom log query --type console_check --since 2026-01-20
axiom log entry create --type general_note --content "Shift turnover complete"
axiom log export --format nrc --range 2026-01-01:2026-01-31 -o january.pdf
```

See [System Ops Log PRD](prd-system-ops-log.md).

### Data Platform (`axiom data`)

Lakehouse queries, pipeline orchestration, backfills.

```bash
axiom data query "SELECT * FROM gold.system_hourly_metrics LIMIT 10"
axiom data pipeline status
axiom data backfill bronze.system_timeseries_raw --start 2026-01-01
```

See [Data Platform PRD](prd-data-platform.md).

### Connections (`axiom connect`)

Unified credential and endpoint management for external integrations.

```bash
axiom connect teams --method browser
axiom connect --check
axiom connect --json
```

See [Connections PRD](prd-connections.md).

### Agent Lifecycle (`axiom agents`)

Register, start, stop, and monitor background agent processes.

```bash
axiom agents register-launchd          # macOS
axiom agents start eve
axiom agents stop mo
axiom agents status
axiom agents logs eve --since 1h
```

See [Agents PRD](prd-agents.md).

### State Management (`axiom state`)

Inventory, backup, restore, and retention across all state locations.

```bash
axiom state inventory --verbose
axiom state backup --encrypt --output backup.tar.gz
axiom state restore backup.tar.gz
axiom state retention --status
axiom state cleanup --dry-run
```

See [Agent State Management PRD](prd-agent-state-management.md).

### Media Library (`axiom media`)

Cross-cutting media management — recordings, photos, documents.

```bash
axiom media ingest photo.jpg --tag pool-clarity --link ops:2026-02-26-shift-A
axiom media search "beam port schedule" --type audio
axiom media tag <id> pool-clarity system-bay
axiom media link <id> experiment:UT-facility-043
```

See [Media Library PRD](prd-media-library.md).

### Infrastructure (`axiom infra`)

Service health, logs, deployment orchestration.

```bash
axiom infra health
axiom infra logs axiom-gateway --since 1h
axiom infra deploy --env staging
```

---

## Non-Functional Requirements

| Requirement | Target |
|-------------|--------|
| **Startup time** | <100ms (no network) |
| **Authentication** | OAuth2/OIDC, API keys, certificate |
| **Output formats** | Table, JSON, YAML, CSV |
| **Shell completion** | bash, zsh, fish, PowerShell |
| **Offline mode** | Graceful degradation for local operations |
| **Cross-platform** | macOS, Linux, Windows |

---

## User Experience Principles

### Progressive Disclosure

```bash
# Simple (sensible defaults)
axiom log query

# Detailed (when needed)
axiom log query --type console_check --facility netl-triga --since 2026-01-20T08:00:00Z --format json
```

### Helpful Errors

```bash
$ axiom model deploy broken.wasm
Error: Model validation failed

  × Missing required export: predict
  │
  │ The model must implement the axiom:surrogate/model interface.
  │ Required exports: predict, validate, get-metadata
  │
  help: Run `axiom model validate broken.wasm --verbose` for details
```

### Confirmation for Destructive Operations

```bash
$ axiom data backfill bronze.system_timeseries_raw --start 2020-01-01
⚠️  This will process 2.3 TB of data (~4 hours)

Continue? [y/N]
```

---

## Dependencies

| Dependency | Purpose |
|------------|---------|
| LLM gateway | Agent intelligence (Neut, EVE, M-O, PR-T, D-FIB) |
| Authentication service | OAuth2/OIDC integration |
| PostgreSQL + pgvector | State management, RAG embeddings |
| Pandoc | Document generation (PR-T) |
| Playwright | Browser-based OneDrive/Teams integration |
| WASM runtime | Local model validation |

---

## Open Questions

1. **Distribution**: Homebrew? apt? Standalone binary?
2. **Agent mode permissions**: Per-noun granularity (e.g., "agent can write to ops log but not compliance")? Or simpler role-based scoping via OpenFGA?
3. **Escalation UX in non-interactive contexts**: How do scripts/CI handle mode transitions? Likely: `--mode agent --yes` for pre-approved pipelines with explicit scope flags.
4. **Session persistence**: Should Plan mode drafts survive across sessions? Or are they ephemeral?

---

*For the complete command hierarchy, configuration schema, and implementation details, see the [CLI Technical Specification](../tech-specs/spec-axi-cli.md).*
