CLI & Headless Mode

Craft Easy Agentic has three runtime modes in addition to the default web dashboard.

Mode selection

Flag	Mode	Use case
(none)	Web — browser dashboard + HTTP/WS server	Primary use; multi-project
--headless	TUI — ratatui ANSI terminal UI	SSH sessions, Termux, no browser
--headless --once	Snapshot — JSON/pretty output then exit	CI, scripting, monitoring
--serve [host:port]	Web on explicit address	Explicit binding (default: 127.0.0.1:4242)

Auto-detection: if stdout is not a TTY (piped, redirected), the binary automatically switches to --once --output json.

---

Web mode

# Default: bind to loopback only
craft-easy-agentic

# Bind to all interfaces (required for LAN / mobile)
craft-easy-agentic --serve 0.0.0.0:4242

# Suppress browser auto-open
craft-easy-agentic --serve 0.0.0.0:4242 --no-browser

# Single-project (backward-compat)
craft-easy-agentic --repo-root ~/esi/petanque-life --serve 0.0.0.0:4242

The bearer token is printed on startup. Pass it as: - Query string: ?token=<TOKEN> (used in the initial browser URL) - Header: Authorization: Bearer <TOKEN> (used by the frontend for all API calls)

Security notes

• The token protects the dashboard from unauthenticated access on the LAN.
• HTTPS is not built in — use a reverse proxy (nginx, Caddy) if the server is exposed beyond your LAN.
• For cross-internet access, Tailscale (or similar VPN) is the recommended approach. No port forwarding needed.

---

Headless TUI mode

craft-easy-agentic --headless --repo-root ~/esi/petanque-life

A full-screen ratatui ANSI UI in the terminal. All dashboard information is available without a browser.

Keyboard shortcuts

Key	Action
s	Start runner
S	Stop runner (graceful)
q / Q	Stop runner (graceful)
K	Force-stop runner
↑ / ↓	Navigate active task list
Enter	Open task log for selected task
Ctrl+R	Force refresh
?	Toggle help overlay
Esc	Close modal / go back
Ctrl+C	Exit Agentic (runner keeps going)

The TUI uses the same state backend as the web UI — file watchers and state reconciliation work identically.

---

Snapshot mode

# Pretty-print to stdout
craft-easy-agentic --headless --once --repo-root ~/esi/petanque-life

# JSON output (pipe-friendly)
craft-easy-agentic --headless --once --output json --repo-root ~/esi/petanque-life

# Auto-mode (non-TTY stdout automatically uses JSON)
craft-easy-agentic --repo-root ~/esi/petanque-life | jq .kpis

The snapshot reads the current disk state without starting a file watcher. It exits immediately after printing. Use in CI scripts, Grafana plugins, or monitoring checks.

Snapshot JSON schema

{
  "runner_active": false,
  "runner_pid": null,
  "stop_requested": false,
  "paused": false,
  "pause_reason": null,
  "resume_at_unix": null,
  "kpis": {
    "completed": 711,
    "running": 0,
    "queued": 7,
    "remaining": 7,
    "current_wave": 1
  },
  "active_tasks": [],
  "queued_task_ids": ["PL-T302", "PL-T303", ...],
  "completed_task_ids": [...],
  "recent_events": [...],
  "session_cost_usd": 42.17,
  "backlog_total": 718,
  "last_backlog_load": 1746000000,
  "recent_completions_unix": [...]
}

---

Mobile via Tailscale

For persistent access from your phone or a remote machine:

1. Install Tailscale on the server and the device.
2. Start Agentic bound to all interfaces: --serve 0.0.0.0:4242.
3. Access via the Tailscale IP: http://100.x.x.x:4242/?token=<TOKEN>.

No router port-forwarding or firewall changes needed. The Tailscale network is encrypted end-to-end.

---

Common invocations

# Start in web mode, log to file, background process
nohup craft-easy-agentic --serve 0.0.0.0:4242 --no-browser >> ~/agentic.log 2>&1 &

# Snapshot and extract queue length for monitoring
craft-easy-agentic --headless --once --output json \
  --repo-root ~/esi/petanque-life | jq '.kpis.queued'

# Start with specific parallel count and skip infrastructure checks
craft-easy-agentic --serve 0.0.0.0:4242 \
  # (then use Start button with parallel=8 from the UI)