# NeuroBrix CLI Reference

Complete reference for all `neurobrix` commands, flags, and mechanisms.

**Version:** 0.1.0 | **Date:** February 2026

---

## Quick Start

```bash
# Development mode (no pip install needed)
PYTHONPATH=src python -m neurobrix <command> [options]

# After pip install
neurobrix <command> [options]
```

---

## Commands Overview

| Command | Description |
|---------|-------------|
| [`run`](#run) | Run model inference (image generation, text generation) |
| [`hub`](#hub) | Browse models available on the NeuroBrix registry |
| [`import`](#import) | Download a model from the registry |
| [`list`](#list) | Show installed models and store contents |
| [`remove`](#remove) | Remove a model from cache, store, or both |
| [`clean`](#clean) | Wipe all models from store and/or cache |
| [`info`](#info) | Display system information (GPU, models, hardware profiles) |
| [`inspect`](#inspect) | Inspect a .nbx container (metadata, components, weights) |
| [`validate`](#validate) | Validate .nbx file integrity |

---

## Storage Architecture

NeuroBrix uses two local directories under `~/.neurobrix/`:

```
~/.neurobrix/
├── store/          ← Downloaded .nbx archives (transport format)
│   └── 1600m-1024.nbx    (9.1 GB — original download)
└── cache/          ← Extracted models (runtime reads from here)
    └── 1600m-1024/
        ├── manifest.json
        ├── topology.json
        ├── runtime/
        ├── components/
        └── modules/
```

| Directory | Purpose | Lifecycle |
|-----------|---------|-----------|
| **store/** | .nbx archives — backup for re-extraction without re-download | Kept after import (delete with `--no-keep` or `neurobrix clean --store`) |
| **cache/** | Extracted models — all runtime reads happen here | Created by `import`, used by `run` |

**Flow:** `hub` (browse) → `import` (download + extract) → `run` (execute) → `remove`/`clean` (cleanup)

---

## `run`

Run model inference. Supports image generation (diffusion, VQ autoregressive) and text generation (LLM).

```bash
neurobrix run --model <name> --hardware <profile> --prompt <text> [options]
```

### Required Flags

| Flag | Description |
|------|-------------|
| `--model NAME` | Model name as it appears in cache (e.g., `1600m-1024`, `Flex.1-alpha`) |
| `--hardware PROFILE` | Hardware profile ID from `config/hardware/` (e.g., `v100-32g`, `c4140-4xv100-custom-nvlink`) |
| `--prompt TEXT` | Text prompt for generation |

### Generation Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--steps N` | int | from model config | Number of inference steps (diffusion models) |
| `--cfg SCALE` | float | from model config | Classifier-free guidance scale |
| `--height PX` | int | from model config | Output height in pixels |
| `--width PX` | int | from model config | Output width in pixels |
| `--seed N` | int | random | Random seed for reproducibility |
| `--output PATH` | str | `output_<model>.png` | Output file path |

**Default cascade:** CLI flag > `runtime/defaults.json` (per model) > family config (`config/families/`)

### LLM-Specific Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--temperature T` | float | from model config | Sampling temperature. `0` = greedy (argmax), `1.0` = standard sampling |
| `--repetition-penalty P` | float | from model config | Penalizes repeated tokens. `1.0` = disabled, `1.1`-`1.5` recommended |
| `--chat` | flag | auto-detect | Force chat template formatting (applies model's chat template) |
| `--no-chat` | flag | auto-detect | Force raw text completion (no chat template) |

`--chat` and `--no-chat` are mutually exclusive. If neither is set, the model's default behavior from `defaults.json` is used.

### Execution Engine Flags

| Flag | Engine | Description |
|------|--------|-------------|
| *(none)* | **Compiled** (default) | CompiledSequenceV2 — pre-compiled ops with integer slot addressing, zero Python overhead. Fastest. |
| `--seq_aten` | **Native** | Sequential PyTorch ATen dispatch — dict-based, op-by-op execution. For debugging. |
| `--triton` | **Triton** | Python loop with custom Triton kernels from `kernels/ops/`. Experimental R&D. |

#### Engine Internals

| Engine | Python Overhead | GPU Utilization | Use Case |
|--------|----------------|-----------------|----------|
| Compiled | ~0% (pre-compiled) | 80-95% | Production (default) |
| Native (`--seq_aten`) | ~15-30% (dict lookups) | 60-80% | Debugging, compatibility |
| Triton (`--triton`) | ~5% (kernel dispatch) | 70-90% | R&D, custom kernels |

**Compiled mode** uses `DtypeEngine` for AMP (Automatic Mixed Precision) — critical for numerical stability. FP32 ops (pow, rsqrt, softmax) are upcast automatically; FP16 ops (matmul, conv) stay in compute dtype. See `core/dtype/engine.py`.

### Advanced: `--set` Flag

Inject arbitrary runtime variables. Useful for overriding any `global.*` variable.

```bash
# Override guidance scale and custom variable
neurobrix run --model 1600m-1024 --hardware v100-32g \
  --prompt "test" --set global.cfg=7.5 --set global.negative_prompt="ugly"
```

Values are auto-typed: `true`/`false` → bool, digits → int, decimal → float, otherwise string.

### Examples

```bash
# Image generation (diffusion)
neurobrix run --model 1600m-1024 --hardware v100-32g \
  --prompt "A cyberpunk city at sunset" --steps 20 --cfg 4.5 --seed 42

# LLM text generation
neurobrix run --model deepseek-moe-16b-chat --hardware c4140-4xv100-custom-nvlink \
  --prompt "Explain quantum computing" --temperature 0.7

# LLM with chat mode forced off (raw completion)
neurobrix run --model deepseek-moe-16b-chat --hardware v100-32g \
  --prompt "Once upon a time" --no-chat --temperature 0.9

# Save LLM output as JSON (OpenAI-compatible format)
neurobrix run --model deepseek-moe-16b-chat --hardware v100-32g \
  --prompt "Hello" --output response.json

# Debug mode (sequential ATen, verbose)
NBX_DEBUG=1 neurobrix run --model 1600m-1024 --hardware v100-32g \
  --prompt "test" --seq_aten
```

### Mechanism: Run Flow

```
1. find_model()          — Locate model in ~/.neurobrix/cache/
2. NBXContainer.load()   — Load manifest, topology, components
3. PrismSolver.solve()   — Hardware allocation (strategy, dtype, device mapping)
4. NBXRuntimeLoader()    — Load RuntimePackage from cache
5. Build inputs dict     — Map CLI args to global.* variables
6. RuntimeExecutor()     — Execute pipeline (iterative_process / autoregressive / forward_pass)
7. Output processing     — Family-driven: image → PNG, LLM → text/JSON
```

**Prism** determines the execution strategy based on model size vs available VRAM:

| Strategy | Description | When Used |
|----------|-------------|-----------|
| `single_gpu` | All components on one GPU | Model fits in one GPU |
| `single_gpu_lifecycle` | Persistent + transient components | Autoregressive with VQ pipeline |
| `pp_nvlink` | Pipeline parallel across NVLink GPUs | Multi-GPU with NVLink |
| `fgp_nvlink` | Fine-grained pipeline parallel | Large models, NVLink |
| `zero3` | ZeRO Stage 3 sharding | Very large models |

---

## `hub`

Browse models available on the NeuroBrix registry (neurobrix.es). No authentication required.

```bash
neurobrix hub [options]
```

### Flags

| Flag | Description |
|------|-------------|
| `--category`, `-c` | Filter by category: `IMAGE`, `VIDEO`, `AUDIO`, `SPEECH`, `LLM`, `UPSCALER` |
| `--search`, `-s` | Search by model name, tag, or description |
| `--registry URL` | Override registry URL (default: `https://neurobrix.es`) |

### Output Columns

| Column | Description |
|--------|-------------|
| MODEL | `org/name` slug |
| CATEGORY | Model category |
| SIZE | .nbx file size |
| DOWNLOADS | Total download count |
| STATUS | `installed` if model exists in local cache |

### Examples

```bash
neurobrix hub                          # All models
neurobrix hub --category IMAGE         # Image models only
neurobrix hub -c LLM -s deepseek      # LLM models matching "deepseek"
neurobrix hub --search "text-to-image" # Search tags
```

### Mechanism

Calls `GET https://neurobrix.es/api/models` with optional `category` and `q` query parameters. Public endpoint, no authentication. Cross-references results with local `~/.neurobrix/cache/` to show installation status.

---

## `import`

Download a model from the NeuroBrix registry and extract to local cache.

```bash
neurobrix import <org>/<model> [options]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `model_ref` | Model reference in `org/name` format (e.g., `sana/1600m-1024`) |

### Flags

| Flag | Description |
|------|-------------|
| `--force` | Re-download even if model is already in cache |
| `--no-keep` | Delete .nbx from store after extraction (saves disk space) |
| `--registry URL` | Override registry URL |

### Examples

```bash
neurobrix import sana/1600m-1024              # Download and keep .nbx
neurobrix import deepseek/janus-pro-7b        # Download LLM
neurobrix import sana/1600m-1024 --no-keep    # Delete .nbx after extraction
neurobrix import sana/1600m-1024 --force      # Re-download
```

### Mechanism

```
1. GET /api/models/{org}/{name}           — Fetch model metadata (size, category)
2. GET /api/models/{org}/{name}/download  — Get signed download URL (1h expiry)
3. Download .nbx to ~/.neurobrix/store/   — Streamed with progress bar
4. Extract .nbx to ~/.neurobrix/cache/    — ZIP extraction
5. (if --no-keep) Delete .nbx from store  — Free disk space
```

The download URL is a time-limited signed S3 URL served via `hub.neurobrix.es` (Cloudflare → HAProxy → MinIO). No authentication required for downloads.

---

## `list`

Show installed models and store contents.

```bash
neurobrix list [options]
```

### Flags

| Flag | Description |
|------|-------------|
| `--store` | Show store contents only (.nbx archives in `~/.neurobrix/store/`) |

### Default Output (no flags)

Shows installed models from cache with store indicator:

```
MODEL                               FAMILY         SIZE    STORE
------------------------------------------------------------------
1600m-1024                          image         9.1 GB     .nbx
janus-pro-7b                        image         7.2 GB        -

Installed: 2 model(s)

Store usage: 9.1 GB (1 file(s))
```

| Column | Description |
|--------|-------------|
| MODEL | Model name (directory name in cache/) |
| FAMILY | From manifest.json: `image`, `llm`, `audio`, `video` |
| SIZE | Total extracted size in cache |
| STORE | `.nbx` if backup exists in store, `-` otherwise |

Also shows **store-only** entries (downloaded but not extracted).

### `--store` Output

Shows raw store directory contents:

```
FILE                                          SIZE
---------------------------------------------------------
1600m-1024.nbx                              9.1 GB

Total: 1 file(s), 9.1 GB
Path:  /home/mlops/.neurobrix/store
```

### Examples

```bash
neurobrix list               # Installed models + store indicator
neurobrix list --store       # Store contents only
```

---

## `remove`

Remove a model from cache, store, or both.

```bash
neurobrix remove <model_name> [options]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `model_name` | Model name to remove (e.g., `1600m-1024`) |

### Flags

| Flag | Target | Effect |
|------|--------|--------|
| *(none)* | **Cache only** | Remove extracted model, keep .nbx in store |
| `--store` | **Store only** | Remove .nbx archive, keep extracted model in cache |
| `--all` | **Both** | Remove from both cache and store |

### Examples

```bash
# Remove from cache only (keep .nbx backup in store)
neurobrix remove 1600m-1024

# Remove .nbx from store only (keep extracted model in cache for runtime)
neurobrix remove 1600m-1024 --store

# Complete removal — cache + store
neurobrix remove 1600m-1024 --all
```

### Behavior

- If model is not in the requested target, shows helpful message indicating where it was found
- Searches store by matching `model_name` in .nbx filenames (fuzzy: `model_name in stem`)

---

## `clean`

Wipe ALL models from store and/or cache. Bulk operation with confirmation prompt.

```bash
neurobrix clean <--store|--cache|--all> [options]
```

### Flags (at least one required)

| Flag | Description |
|------|-------------|
| `--store` | Delete all .nbx files from `~/.neurobrix/store/` |
| `--cache` | Delete all extracted models from `~/.neurobrix/cache/` |
| `--all` | Delete both store and cache |
| `-y`, `--yes` | Skip confirmation prompt |

### Examples

```bash
neurobrix clean --store          # Free store space (keep extracted models)
neurobrix clean --cache          # Free cache space (keep .nbx backups)
neurobrix clean --all            # Complete wipe
neurobrix clean --all -y         # No confirmation (scripting)
```

### Mechanism

1. Scans target directories and calculates total size
2. Shows summary: file count, model count, total GB
3. Asks for confirmation (unless `-y`)
4. Deletes all matching files/directories

---

## `info`

Display system information: installed models, hardware profiles, GPU status.

```bash
neurobrix info [options]
```

### Flags

| Flag | Description |
|------|-------------|
| `--models` | Show installed models only |
| `--hardware` | Show available hardware profiles only |
| `--system` | Show system configuration only |

If no flag is set, all sections are shown.

### Output Sections

**Models:** Lists all models in cache with sizes.

**Hardware Profiles:** Lists all `.yml` files in `config/hardware/`. Each profile defines GPU capabilities (VRAM, supported dtypes, interconnect).

**System:** Package path, cache/store paths, Python version, PyTorch version, CUDA availability, GPU details (name, VRAM per device).

### Examples

```bash
neurobrix info                # Full system info
neurobrix info --hardware     # Available hardware profiles
neurobrix info --system       # Python, PyTorch, GPU details
```

---

## `inspect`

Inspect a .nbx container file — metadata, components, topology, weights.

```bash
neurobrix inspect <path> [options]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `nbx_path` | Path to .nbx file |

### Flags

| Flag | Description |
|------|-------------|
| `--topology` | Show graph topology details (node count, first few ops per component) |
| `--weights` | Show weight shard information (count, filenames) |

### Examples

```bash
neurobrix inspect ~/.neurobrix/cache/1600m-1024/model.nbx
neurobrix inspect model.nbx --topology --weights
```

### Output

Shows: file path, model name, NBX version, family, component list (neural vs config), and optionally topology/weight details.

---

## `validate`

Validate .nbx file integrity at various depth levels.

```bash
neurobrix validate <file(s)> [options]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `nbx_files` | One or more paths to .nbx files (glob supported) |

### Flags

| Flag | Description |
|------|-------------|
| `--level`, `-l` | Validation depth (see below). Default: `coherence` |
| `--strict` | Exit on first validation failure |
| `--json` | Output results as JSON |
| `--verbose`, `-v` | Show detailed validation info |

### Validation Levels

| Level | Checks |
|-------|--------|
| `structure` | Files exist in ZIP archive |
| `schema` | JSON parsing + required fields validation |
| `coherence` | Cross-reference weights_index with actual shards (default) |
| `deep` | Read safetensors headers, verify checksums |

### Examples

```bash
neurobrix validate model.nbx
neurobrix validate model.nbx --level deep --verbose
neurobrix validate model.nbx --strict --json
neurobrix validate models/*/model.nbx          # Multiple files
```

---

## Environment Variables

### Debug Variables

| Variable | Effect |
|----------|--------|
| `NBX_DEBUG=1` | Enable verbose logging. Forces GPU sync on every op (2x slower, 40-60% GPU utilization). |
| `NBX_TRACE_ZEROS=1` | Find the first op that produces all-zero output from non-zero input. Stops at first detection. |
| `NBX_TRACE_NAN=1` | Trace NaN/Inf values in the first few ops. |
| `NBX_NAN_GUARD=1` | Replace NaN with 0 in every op output. Expensive (2.5x slower). For diagnosis only. |

### Performance Impact

| Mode | GPU Utilization | Relative Speed |
|------|----------------|----------------|
| Default | 80-95% | 1.0x |
| `NBX_DEBUG=1` | 40-60% | 0.5x |
| `NBX_NAN_GUARD=1` | 30-50% | 0.4x |

### Examples

```bash
# Trace where zeros appear
NBX_TRACE_ZEROS=1 PYTHONPATH=src python -m neurobrix run \
  --model 1600m-1024 --hardware v100-32g --prompt "test"

# Debug with native engine (maximum visibility)
NBX_DEBUG=1 PYTHONPATH=src python -m neurobrix run \
  --model 1600m-1024 --hardware v100-32g --prompt "test" --seq_aten
```

---

## Hardware Profiles

Hardware profiles are YAML files in `src/neurobrix/config/hardware/`. They define:
- GPU count, VRAM per device
- Supported dtypes (`float32`, `float16`, `bfloat16`)
- Interconnect type (NVLink, PCIe)

| Profile | GPUs | VRAM | Description |
|---------|------|------|-------------|
| `v100-32g` | 1 | 32 GB | Single V100 32GB |
| `v100-16g` | 1 | 16 GB | Single V100 16GB |
| `c4140-4xv100-custom-nvlink` | 4 | 96 GB | 2xV100-16GB + 2xV100-32GB, NVLink |
| `v100-32g-x2-nvlink` | 2 | 64 GB | 2xV100-32GB, NVLink |

List available profiles: `neurobrix info --hardware`

---

## Model Families

Models are categorized by family (stored in `manifest.json`). The family determines the execution flow:

| Family | Flow Type | Output | Examples |
|--------|-----------|--------|----------|
| `image` (diffusion) | `iterative_process` | PNG image | PixArt-Sigma, Sana, SDXL, FLUX |
| `image` (VQ autoregressive) | `autoregressive_generation` | PNG image | Janus-Pro-7B, LlamaGen |
| `llm` | `autoregressive_generation` | Text / JSON | DeepSeek-MoE, Llama, Mistral |
| `audio` | `forward_pass` | Audio file | Whisper |
| `video` | `iterative_process` | Video frames | CogVideoX |

The `--family` flag does NOT exist at runtime — the family is read from `manifest.json` (set at build/import time). This is the ZERO HARDCODE principle.

---

## Dtype Flow

Dtype is NEVER hardcoded. It flows from hardware profile through the entire system:

```
Hardware YAML (supports_dtypes: ["float32", "float16"])
    → Prism._resolve_dtype()
    → allocation.dtype = torch.float16
    → ExecutorFactory
    → GraphExecutor(dtype=torch.float16)
    → WeightLoader converts weights to dtype
    → DtypeEngine applies AMP rules per-op
```

**AMP Rules (Compiled mode):**
- FP32 ops: `pow`, `rsqrt`, `softmax`, `layer_norm`, `sum`, `mean` — upcast to fp32 for numerical stability
- FP16 ops: `mm`, `bmm`, `conv2d`, `linear` — run in compute dtype (fp16) for speed
- Promote ops: inputs promoted to highest precision among them

**Critical:** Without AMP, RMSNorm's `pow → mean → rsqrt` chain overflows in fp16 (rsqrt(Inf) = 0 → all zeros). AMP prevents this automatically.

---

## Typical Workflows

### First Time Setup

```bash
# 1. Browse available models
neurobrix hub

# 2. Download a model
neurobrix import sana/1600m-1024

# 3. Check hardware
neurobrix info --hardware

# 4. Run inference
neurobrix run --model 1600m-1024 --hardware v100-32g \
  --prompt "A beautiful sunset over the ocean" --steps 20
```

### Save Disk Space

```bash
# Import without keeping .nbx backup
neurobrix import sana/1600m-1024 --no-keep

# Or clean store after the fact
neurobrix clean --store

# Remove a single model's .nbx
neurobrix remove 1600m-1024 --store
```

### Debugging a Model

```bash
# Step 1: Try native engine
neurobrix run --model 1600m-1024 --hardware v100-32g \
  --prompt "test" --seq_aten

# Step 2: Enable zero tracing
NBX_TRACE_ZEROS=1 neurobrix run --model 1600m-1024 --hardware v100-32g \
  --prompt "test"

# Step 3: Full debug
NBX_DEBUG=1 neurobrix run --model 1600m-1024 --hardware v100-32g \
  --prompt "test" --seq_aten
```

### Complete Cleanup

```bash
# See what's installed
neurobrix list

# See store usage
neurobrix list --store

# Wipe everything
neurobrix clean --all
```
