# FABRIC CLI Reference Complete reference for all `fabric` commands and options. ## Installation ```bash npm install -g @needle/fabric # or pnpm add -g @needle/fabric ``` The binary installs as `fabric` (or `fabric-node` if there's a naming conflict). ## Commands Overview | Command | Description | |---------|-------------| | `fabric tui` | Launch terminal UI dashboard | | `fabric web` | Launch web dashboard | | `fabric tail` / `fabric logs` | Tail log file and display events | | `fabric replay` | Replay worker session history | | `fabric prune` | Prune old log files | | `fabric digest` | Generate session digest from log file | | `fabric config` | Manage FABRIC configuration | --- ## Global Options ```bash fabric --help # Show help fabric --version # Show version ``` --- ## `fabric tui` Launch the terminal UI dashboard with real-time worker activity. ### Usage ```bash fabric tui [options] ``` ### Options | Option | Alias | Default | Description | |--------|-------|---------|-------------| | `-f, --file ` | — | — | Log file to tail (single-file mode) | | `--source ` | — | `~/.needle/logs/` | Log source (file or directory) | | `-w, --worker ` | — | — | Filter to specific worker ID | | `-l, --level ` | — | — | Filter by log level (`debug`, `info`, `warn`, `error`) | | `--otlp-grpc ` | — | — | Enable OTLP/gRPC receiver (e.g. `:4317` or `0.0.0.0:4317`) | | `--otlp-http ` | — | — | Enable OTLP/HTTP receiver (e.g. `:4318` or `0.0.0.0:4318`) | ### Examples ```bash # Basic TUI watching default log directory fabric tui # Watch a specific directory fabric tui --source /var/log/needle/ # Filter to one worker fabric tui --worker w-alpha # Filter by log level fabric tui --level error # With OTLP live telemetry fabric tui --otlp-grpc :4317 # Combine log file tailing with OTLP fabric tui --source ~/.needle/logs/ --otlp-grpc 0.0.0.0:4317 ``` ### Keyboard Shortcuts | Key | Action | |-----|--------| | `q` | Quit | | `Tab` | Switch panels | | `j` / `k` | Scroll down/up | | `/` | Search | | `f` | Filter | | `Ctrl+P` | Command palette | --- ## `fabric web` Launch the web dashboard with real-time updates via WebSocket. ### Usage ```bash fabric web [options] ``` ### Options | Option | Alias | Default | Description | |--------|-------|---------|-------------| | `-p, --port ` | — | `3000` | Port to listen on | | `-f, --file ` | — | — | Log file to tail (single-file mode) | | `--source ` | — | `~/.needle/logs/` | Log source (file or directory) | | `-w, --worker ` | — | — | Filter to specific worker ID | | `-l, --level ` | — | — | Filter by log level | | `-a, --auth-token ` | — | `$FABRIC_AUTH_TOKEN` | Auth token for POST endpoints | | `--otlp-grpc ` | — | — | Enable OTLP/gRPC receiver | | `--otlp-http ` | — | — | Enable OTLP/HTTP receiver | | `--max-events ` | — | — | Max events in store before liveness guard exits | | `--heap-snapshots` | — | `true` in production | Enable automatic heap snapshot capture | | `--snapshot-interval ` | — | `30` | Interval between heap snapshots | ### Examples ```bash # Basic web server on default port fabric web # Custom port fabric web --port 8080 # With auth token FABRIC_AUTH_TOKEN=secret fabric web fabric web --auth-token secret # With OTLP/HTTP receiver fabric web --otlp-http :4318 # With memory-bomb guard fabric web --max-events 1000000 ``` ### Access - Local: `http://localhost:3000` - Remote (via Tailscale): `https://hetzner-ex44.tail1b1987.ts.net/` ### Authentication POST endpoints (`/api/events`, `/api/events/batch`) require `Authorization: Bearer ` when an auth token is configured. --- ## `fabric tail` / `fabric logs` Tail log file and display events. `logs` is an alias for `tail`. ### Usage ```bash fabric tail [options] fabric logs [options] ``` ### Options | Option | Alias | Default | Description | |--------|-------|---------|-------------| | `-f, --file ` | — | — | Log file to tail (single-file mode) | | `--source ` | — | `~/.needle/logs/` | Log source (file or directory) | | `-w, --worker ` | — | — | Filter by worker ID | | `-t, --event-type ` | — | — | Filter by event type (glob, e.g. `bead.*`, `worker.started`) | | `-l, --level ` | — | — | Filter by log level (deprecated: use `--event-type`) | | `-n, --lines ` | — | `0` | Number of existing lines to show | | `--no-follow` | — | — | Exit after reading existing lines | | `--json` | — | — | Output raw JSON instead of formatted | | `--otlp-grpc ` | — | — | Enable OTLP/gRPC receiver | | `--otlp-http ` | — | — | Enable OTLP/HTTP receiver | ### Examples ```bash # Stream events from default directory fabric tail # Show last 100 lines and follow fabric tail -n 100 # Filter by worker fabric tail --worker w-alpha # Filter by event type fabric tail --event-type "bead.*" # Raw JSON output fabric tail --json # Exit after reading (no follow) fabric tail --no-follow -n 50 # With OTLP fabric tail --otlp-grpc :4317 ``` --- ## `fabric replay` Replay worker session history chronologically with timeline scrubbing. ### Usage ```bash fabric replay [options] ``` ### Options | Option | Alias | Default | Description | |--------|-------|---------|-------------| | `-f, --file ` | — | `~/.needle/logs/workers.log` | Log file to replay | | `-w, --worker ` | — | — | Filter by worker ID | | `-t, --event-type ` | — | — | Filter by event type (glob) | | `-l, --level ` | — | — | Filter by log level (deprecated) | | `-s, --speed ` | — | `1` | Playback speed (`0.5`, `1`, `2`, `5`, `10`) | | `--auto` | — | — | Start playback automatically | ### Playback Speeds - `0.5` - Half speed - `1` - Normal speed (default) - `2` - 2x speed - `5` - 5x speed - `10` - 10x speed ### Keyboard Controls | Key | Action | |-----|--------| | `q` / `C-c` | Quit | | `Escape` | Quit | | `Space` | Play/Pause | | `←` / `→` | Seek backward/forward | | `Home` / `End` | Jump to start/end | ### Examples ```bash # Replay default log file fabric replay # Replay specific file fabric replay --file /path/to/session.jsonl # Filter by worker fabric replay --worker w-alpha # 2x speed, auto-start fabric replay --speed 2 --auto ``` --- ## `fabric prune` Prune old log files (archive + delete). ### Usage ```bash fabric prune [options] ``` ### Options | Option | Default | Description | |--------|---------|-------------| | `--source ` | `~/.needle/logs/` | Log directory to prune | | `--archive-after ` | `3` | Archive files older than N days | | `--archive-retain ` | `30` | Delete archives older than N days | | `--max-age ` | `7` | Delete files older than N days regardless | | `--dry-run` | — | Report what would happen without making changes | ### Archive Structure Archives are created as `~/.needle/logs/archive/YYYY-MM-DD.tar.gz`. ### Examples ```bash # Dry run to see what would happen fabric prune --dry-run # Run with defaults fabric prune # Custom retention fabric prune --archive-after 5 --max-age 14 --archive-retain 60 # Prune different directory fabric prune --source /var/log/needle/ ``` ### Cron Setup ```bash # Daily at 03:17 17 3 * * * ~/.local/bin/fabric prune ``` --- ## `fabric digest` Generate session digest from log file. ### Usage ```bash fabric digest [options] ``` ### Options | Option | Alias | Default | Description | |--------|-------|---------|-------------| | `-f, --file ` | — | `~/.needle/logs/workers.log` | Log file to analyze | | `-o, --output ` | — | — | Output file (default: stdout) | | `-w, --worker ` | — | — | Filter by worker IDs (comma-separated) | | `--since ` | — | — | Start time (Unix timestamp in ms) | | `--until ` | — | — | End time (Unix timestamp in ms) | | `--max-files ` | — | `50` | Maximum files to list | | `--max-errors ` | — | `20` | Maximum errors to list | | `--no-cost` | — | — | Exclude cost information | | `--no-errors` | — | — | Exclude error information | ### Examples ```bash # Generate digest to stdout fabric digest # Save to file fabric digest --output session-summary.md # Filter by workers fabric digest --worker w-alpha,w-bravo # Time range fabric digest --since 1709337600000 --until 1709424000000 # Exclude cost and errors fabric digest --no-cost --no-errors ``` --- ## `fabric config` Manage FABRIC configuration (theme, presets, recent commands, filters). ### Usage ```bash # Show all config fabric config # Subcommands fabric config theme [dark|light] fabric config presets list fabric config presets delete fabric config clear [options] ``` ### `fabric config` Show current configuration. ```bash fabric config ``` Output includes: - Theme setting - Focus presets - Recent commands - Filter state ### `fabric config theme` Show or set color theme. ```bash # Show current theme fabric config theme # Set theme fabric config theme dark fabric config theme light ``` ### `fabric config presets` Manage focus presets. ```bash # List all presets fabric config presets list fabric config presets ls # Delete a preset fabric config presets delete my-preset fabric config presets rm my-preset ``` ### `fabric config clear` Clear configuration state. ```bash # Clear all config fabric config clear --all # Clear specific categories fabric config clear --theme fabric config clear --presets fabric config clear --commands fabric config clear --filters ``` ### Config File Locations | Config | Path | |--------|------| | Theme | `~/.fabric/theme.json` | | Presets | `~/.fabric/focus-presets.json` | | Recent commands | `~/.fabric/recent-commands.json` | | Filter state | `~/.fabric-filter-state.json` | --- ## OTLP Receivers FABRIC can receive telemetry via OpenTelemetry Protocol (OTLP) from NEEDLE workers. ### `--otlp-grpc` Enable OTLP/gRPC receiver. ```bash fabric tui --otlp-grpc :4317 fabric web --otlp-grpc 0.0.0.0:4317 fabric tail --otlp-grpc :4317 ``` | Format | Binds to | |--------|----------| | `:4317` | `0.0.0.0:4317` | | `127.0.0.1:4317` | `127.0.0.1:4317` | | `0.0.0.0:4317` | `0.0.0.0:4317` | ### `--otlp-http` Enable OTLP/HTTP receiver. ```bash fabric tui --otlp-http :4318 fabric web --otlp-http 0.0.0.0:4318 fabric tail --otlp-http :4318 ``` ### NEEDLE Configuration Set environment variables before launching NEEDLE workers: ```bash export OTEL_EXPORTER_OTLP_ENDPOINT=http://fabric-host:4317 export OTEL_EXPORTER_OTLP_PROTOCOL=grpc needle run ... ``` --- ## Common Patterns ### Multiple Sources Combine log file tailing with OTLP live telemetry: ```bash fabric tui --source ~/.needle/logs/ --otlp-grpc :4317 ``` Events from both sources are merged and deduplicated. ### Filtering Most commands support worker and level filtering: ```bash fabric tui --worker w-alpha --level error fabric tail --worker w-alpha --event-type "bead.*" fabric replay --worker w-bravo ``` ### Production Service Run as a systemd service with OTLP/HTTP: ```bash systemctl --user start fabric-web.service ``` Service file at `scripts/fabric-web.service` runs: ```bash fabric web --port 3000 --source ~/.needle/logs/ --otlp-http :4318 ``` --- ## Exit Codes | Code | Meaning | |------|---------| | `0` | Success | | `1` | Error (invalid options, file not found, runtime error) | --- ## Environment Variables | Variable | Purpose | |----------|---------| | `FABRIC_AUTH_TOKEN` | Auth token for POST endpoints (overrides `--auth-token`) | | `NODE_ENV` | When `production`, enables heap snapshots by default | | `WATCHDOG_USEC` | systemd watchdog timeout (enables watchdog ping) | | `NOTIFY_SOCKET` | systemd notification socket (for watchdog) | --- ## See Also - [Plan](plan.md) - Implementation roadmap - [Schema](schema.md) - NeedleEvent wire format - [Metrics](metrics.md) - Prometheus metrics export - [README](../README.md) - Project overview