Skip to main content

​
Infrastructure Commands

Commands for setting up Genie, launching the TUI and desktop app, managing services, diagnosing issues, updating, database management, and configuring terminal shortcuts.

​
genie tui

Launch the interactive terminal UI (OpenTUI nav + tmux Claude Code). 
genie tui [options]
FlagDescription
--devDevelopment mode with auto-reload on file changes
# Launch TUI
genie tui

# Launch in dev mode (auto-reloads on source changes)
genie tui --dev

​
genie serve

Start, stop, and check status of all genie infrastructure services (pgserve, tmux, scheduler). 
genie serve [command]

​
Subcommands

CommandDescription
startStart genie serve (pgserve, tmux, scheduler)
stopStop genie serve and all services
statusShow service health
# Start all services
genie serve start

# Check service health
genie serve status

# Stop all services
genie serve stop

​
genie app

Launch the Genie desktop app (backend sidecar + views). 
genie app [options]
FlagDescription
--backend-onlyStart only the backend sidecar (IPC on stdin/stdout)
--tuiFall back to terminal UI mode
--devDevelopment mode
# Launch the desktop app
genie app

# Start only the backend sidecar
genie app --backend-only

# Fall back to TUI mode
genie app --tui

​
genie setup

Interactive wizard for configuring Genie settings. 
genie setup [options]
Terminal
$ genie setup
╔════════════════════════════════════════════════════════════════╗
║                  ✨ Genie Setup Wizard ✨                     ║
╠════════════════════════════════════════════════════════════════╣
║  Terminal: tmux                                               ║
║  Session:  auto                                               ║
║  Codex:    not configured                                     ║
╚════════════════════════════════════════════════════════════════╝

? Configure terminal shortcuts? (Y/n)
? Set up Codex integration? (Y/n)
? Configure session naming? (auto/manual)

​
Options

FlagDescription
--quickSkip interactive prompts, use defaults
--shortcutsOnly configure terminal shortcuts
--codexOnly configure Codex integration
--terminalOnly configure terminal settings
--sessionOnly configure session naming
--resetReset all settings to defaults
--showShow current configuration
Terminal
$ genie setup --show
Genie Configuration:
  Config: ~/.genie/config.json
  Terminal: tmux
  Session naming: auto
  Shortcuts: installed
  Codex: configured (OTel relay on port 4318)

​
genie doctor

Diagnose the Genie installation and environment. 
genie doctor [options]
FlagDescription
--fixAuto-fix: kill zombie postgres, clean shared memory, restart daemon
Terminal
$ genie doctor
Genie Doctor — Checking your environment...

  genie CLI       ✅ v4.260324.8
  bun runtime     ✅ v1.2.x
  tmux            ✅ v3.4
  git             ✅ v2.43.0
  claude code     ✅ installed
  PostgreSQL      ✅ connected (pgserve)
  NATS            ⚠️  not running (optional)
  .genie/         ✅ scaffolded
  AGENTS.md       ✅ found
  CLAUDE.md       ✅ found

Summary: 9/10 checks passed. 1 warning.

​
genie update

Update Genie to the latest version. 
genie update [options]
FlagDescription
--nextSwitch to dev builds (npm @next tag)
--stableSwitch to stable releases (npm @latest tag)
Terminal
$ genie update
Checking for updates...
  Current: v4.260324.7
  Latest:  v4.260324.8
Updating...
  ✅ Updated to v4.260324.8

​
genie uninstall

Remove Genie from the system. Cleans up global state, configuration, and the CLI binary. 
genie uninstall
Terminal
$ genie uninstall
Uninstalling Genie...
  Removed ~/.genie/
  Removed CLI binary
  ✅ Genie uninstalled.

​
genie db

Database management commands for the embedded PostgreSQL instance.

​
genie db status

Show pgserve health, port, data directory, and table counts. 
genie db status
Terminal
$ genie db status
PostgreSQL (pgserve):
  Status:     running
  Port:       19642
  Data dir:   ~/.genie/data/pgserve/
  Tables:     18
  Migrations: 10/10 applied

Table Counts:
  tasks           42
  agents          5
  boards          3
  audit_events    1,234
  sessions        8

​
genie db migrate

Run pending database migrations. 
genie db migrate
Terminal
$ genie db migrate
Running migrations...
  ✅ 008_boards.sql (applied)
  ✅ 009_app_store.sql (applied)
2 migrations applied.

​
genie db query

Execute arbitrary SQL and print results. 
genie db query <sql>
Terminal
$ genie db query "SELECT count(*) FROM tasks WHERE stage = 'build'"
 count
-------
     3
(1 row)

​
genie shortcuts

Configure Warp-like keyboard shortcuts for tmux. 
genie shortcuts [command]

​
Subcommands

CommandDescription
showShow available shortcuts and installation status
installInstall shortcuts to config files (~/.tmux.conf, shell rc)
uninstallRemove shortcuts from config files
# Show current shortcut status
genie shortcuts show

# Install shortcuts
genie shortcuts install

# Remove shortcuts
genie shortcuts uninstall
Generates and installs:
PlatformConfigShortcuts
tmux~/.tmux.confCtrl+T (new tab), Ctrl+S (vertical split), Ctrl+Shift+S (horizontal split)
Termux~/.termux/termux.propertiesF1 (new tab), F2 (vsplit), F3 (hsplit)
Shell~/.bashrc / ~/.zshrcHelper functions + disable Ctrl+S flow control
Terminal
$ genie shortcuts
Installing keyboard shortcuts...
  tmux config:    ✅ written to ~/.tmux.conf
  shell config:   ✅ appended to ~/.zshrc
  termux config:  ⬜ skipped (not on Termux)

Shortcuts installed! Restart tmux to apply:
  tmux source ~/.tmux.conf