CLI / TUI

The CLI/TUI is the primary interface for developers. A single binary (watchfire) operates in two modes: CLI commands for scripting and automation, and TUI mode for interactive work. It's project-scoped — run from within a project directory.

Looking for a single-page reference? The Keyboard Shortcuts cheat sheet lists every TUI binding in printable form.

CLI Commands

Global

Command	Alias	Description
watchfire		Start TUI
watchfire version	--version, -v	Show version (all components)
watchfire help	-h	Show help
watchfire update		Update all components
watchfire init		Initialize project in current directory

Project Lifecycle

Command	Alias	Description
watchfire define	def	Edit project definition in $EDITOR
watchfire configure	config	Configure project settings (interactive)

Task Management

Command	Alias	Description
watchfire task list	task ls	List tasks (excludes deleted)
watchfire task list --deleted		List soft-deleted tasks
watchfire task add		Add new task (interactive)
watchfire task <taskid>		Edit task (interactive)
watchfire task delete <taskid>	task rm <taskid>	Soft delete task
watchfire task restore <taskid>		Restore soft-deleted task

Execution

Command	Alias	Description
watchfire run		Start chat mode
watchfire run <taskid>		Run specific task
watchfire run all		Run all ready tasks sequentially
watchfire plan		Generate tasks from project definition
watchfire generate	gen	Generate project definition
watchfire wildfire	fire	Autonomous three-phase loop

Daemon

Command	Alias	Description
watchfire daemon start		Start the daemon
watchfire daemon status		Show daemon info
watchfire daemon stop		Stop the daemon

watchfire init Flow

1. Check for git → if missing, initialize git repo
2. Create .watchfire/ directory structure
3. Create initial project.yaml
4. Append .watchfire/ to .gitignore
5. Commit .gitignore change
6. Prompt for the coding agent (Claude Code, Codex, opencode, Gemini, Copilot, Cursor)
   — seeded into project.default_agent
7. Prompt for project definition (optional)
8. Prompt for project settings
9. Save project.yaml
10. Register project in ~/.watchfire/projects.yaml

The agent prompt only appears when the global default is set to "Ask per project" (or unset). If a global default is configured, init skips the prompt and uses it. See the Supported Agents doc for backend-specific setup.

TUI Mode

Launch by running watchfire with no arguments. The TUI provides a split-view interface:

┌──────────────────────────────────────────────────────────────────────┐
│ ● project-name  Tasks | Definition | Settings    Chat | Logs  ● Idle│
├────────────────────────────────┬─────────────────────────────────────┤
│  Task List                     │  Agent Terminal / Logs              │
│                                │                                     │
│  Draft (2)                     │  > Starting session...              │
│    #0001 Setup structure       │                                     │
│    #0004 Add authentication    │  > Working on task...               │
│      [codex]                   │                                     │
│                                │                                     │
│  Ready (1)                     │                                     │
│  ● #0002 Implement login [▶]  │                                     │
│                                │                                     │
│  Done (2)                      │                                     │
│    #0003 Create schema   ✓    │                                     │
│    #0005 Add tests       ✓    │                                     │
├────────────────────────────────┴─────────────────────────────────────┤
│ Ctrl+q quit  Ctrl+h help  Tab switch panel           a add  s start │
└──────────────────────────────────────────────────────────────────────┘

A compact agent badge (e.g. [codex]) appears next to a task title when its agent field is set and differs from the project default. Tasks that defer to the project default show no badge, keeping the list visually quiet for the common case.

Navigation

Input	Action
Tab	Switch between left/right panels
j/k or ↓/↑	Move up/down in lists
h/l or ←/→	Switch tabs
1/2/3	Switch left panel tabs
Enter	Select/edit item
Esc	Close overlay / cancel
Ctrl+q	Quit
Ctrl+h	Help overlay
Ctrl+f	Fleet (cross-project) Insights overlay
Ctrl+e	Export report (CSV or Markdown)
Ctrl+i	Integrations overlay (Outbound / Inbound tabs)

Ctrl+f opens the fleet rollup — KPI strip, stacked-bar tasks-per-day, agent donut, duration histogram, and a 7d / 30d / 90d / All window switcher — backed by the same data the GUI Dashboard rollup card renders.

Ctrl+e triggers InsightsService.ExportReport with the same scope precedence as the GUI: the active project if one is selected, otherwise the dashboard (global). Single-task export is reachable from the task action menu.

Integrations Overlay (Ctrl+I)

Ctrl+I opens the Integrations overlay — the TUI mirror of the GUI Integrations panel. The overlay is split into two tabs:

Tab	Content
Outbound	One row per configured adapter (webhook, Slack, Discord, GitHub auto-PR) with a status pill (OK / Disabled / Breaker open / Misconfigured) and a t shortcut to fire a synthetic test event.
Inbound	Listening pill (polled every 5 s), editable ListenAddr (defaults to 127.0.0.1:8765) and PublicURL, four write-only secret inputs (Discord, GitHub, Slack, generic webhook), and per-provider last-delivery timestamps.

Both tabs talk to the daemon through IntegrationsService gRPC: List / Save / Delete / Test, with secret fields write-only on the wire. See the Integrations concept page for the underlying model and the watchfire integrations command for the scriptable equivalent.

Task Actions

When the task list is focused:

Key	Action
a	Add new task
e / Enter	Edit selected task
s	Start task (set to Ready + start agent)
r	Move task to Ready
t	Move task to Draft
d	Open inline diff overlay
i	Open project Insights overlay
x	Delete (soft)

The diff overlay renders the same FileDiffSet as the GUI Inspect tab.

The Insights overlay (i) is the TUI mirror of the GUI Insights tab — KPI strip, stacked-bar tasks-per-day, agent donut, duration histogram, and a 7d / 30d / 90d / All window switcher. See the Insights concept page for the underlying metrics and how the windows aggregate.

Left Panel Tabs

Tab	Content
Tasks	Task list grouped by status. Tasks with a per-task agent override show an agent badge next to the title.
Definition	Project definition (press e to edit in $EDITOR)
Settings	Git config, automation toggles, and a coding agent selector that cycles through the registered backends (project default).

Right Panel Tabs

Tab	Content
Chat	Live agent terminal output
Logs	Past session logs per task. Formatted transcripts render for all supported backends (Claude Code, Codex, opencode, Gemini, Copilot, Cursor), falling back to PTY scrollback when no transcript is available.

Task Form

The Add / Edit Task overlay includes an agent field — a cycling selector below the existing fields. The first option, Project default (<name>), maps to the empty string and keeps the task on whatever the project is configured for. The remaining options are the registered backends. Saving the form writes the chosen value to the task's agent field.

TUI Features

• Mouse support (click, scroll, drag divider)
• Vim-like + arrow key navigation
• Resizable panels (40/60 default split)
• Real-time streaming from daemon
• Context-sensitive keyboard shortcuts
• Agent issue banners (auth errors, rate limits)
• Auto-reconnect on daemon disconnection

Global Settings (globalsettings)

The TUI exposes app-wide preferences through a globalsettings overlay — the keyboard mirror of the GUI Global Settings panel. It reads and writes the same ~/.watchfire/settings.yaml file, so a value changed in either client takes effect everywhere on the next event.

The overlay is split into eight category sub-pages (Appearance, Defaults, Agent Paths, Notifications, Integrations, Inbound, Updates, About). Press / from the overlay to open a search overlay that filters categories and surfaces individual matching controls; selecting a result jumps to the category and pulses the matching field briefly.

Phoenix adds a parallel per-project Settings sidebar inside the project view (open with the Settings tab) that mirrors this UX with seven sections — General, Automation, Notifications, Integrations, Metadata, Secrets, Danger zone — for the per-project knobs (project-scoped notification overrides, Slack channel + Discord guild bindings, archive / regenerate ID / reset task numbering / prune merged branches / unregister).

Notification Preferences

The Notifications section of globalsettings configures notification behaviour. Every control below is gated through models.ShouldNotify on the daemon and persisted to defaults.notifications in ~/.watchfire/settings.yaml.

Control	Default	Notes
Master toggle	On	Top-level kill switch — turning it off silences every event kind without losing per-event preferences.
Per-event toggles	TASK_FAILED on, RUN_COMPLETE on, WEEKLY_DIGEST off	One row per event kind. The weekly digest is the only event that defaults off — opt in to start receiving the rendered Markdown report at ~/.watchfire/digests/<YYYY-MM-DD>.md.
Sounds	On	Master sounds toggle. When on, a foregrounded GUI plays assets/sounds/task-{done,failed}.wav and the OS toast is sent silent so each event makes one cue.
Volume slider	100%	Linear 0–100 applied to renderer-side audio when the GUI plays the cue.
Quiet hours	Off	Optional time window (start/end, local time, DST-stable). While enabled and inside the window, notifications are suppressed.
Per-project mute	None	Project list to skip regardless of other toggles. Useful for noisy long-running projects.

The TUI itself does not raise OS toasts — these settings drive the daemon's tray and any connected GUI. Clicking the tray Notifications submenu still routes back through DaemonService.SubscribeFocusEvents.