CLI Reference

The nomadflow binary provides several modes of operation.

Usage

nomadflow [OPTIONS] [COMMAND]

Commands

Default (no command)

nomadflow

Starts the HTTP server in the background, then launches the TUI wizard. When the TUI exits, the server is gracefully shut down (ttyd is cleanly stopped, no orphan processes). If the TUI returns a tmux session to attach to, tmux attach-session is executed automatically.

`serve`

nomadflow serve

Runs the HTTP server in the foreground with full tracing/logging enabled. Use this for headless deployments, Docker containers, or systemd services.

The server handles graceful shutdown: on Ctrl+C or SIGTERM, it stops accepting new connections, completes in-flight requests, then cleanly stops the ttyd subprocess.

`start`

nomadflow start

Starts the server as a background daemon. The process is detached, and its PID is written to ~/.nomadflowcode/nomadflow.pid. Logs are written to ~/.nomadflowcode/nomadflow.log.

If a daemon is already running (PID file exists and process is alive), the command prints a message and exits without spawning a duplicate.

`stop`

nomadflow stop

Stops the background daemon. Reads the PID file, sends SIGTERM to trigger graceful shutdown, and waits for the process to exit (up to 10 seconds). If the process does not exit in time, SIGKILL is sent. The PID file is removed after the process exits.

Options

`--status`

nomadflow --status

Displays the current daemon status (running/not running, PID) and the tmux session status (windows, features), then exits.

`--attach <feature>`

nomadflow --attach my-feature

Starts the server briefly, then attaches directly to the tmux session. The server is gracefully shut down before attaching. Useful for quickly jumping into a running session from the command line.

TUI wizard

When running in default mode, the TUI provides an interactive terminal interface with the following screens:

Server list — manage remote server connections
Add server — multi-step form: name, URL, token, confirmation
Repository browser — list and select repos
Feature browser — list, create, and switch feature branches

The TUI is built with ratatui and exits cleanly, handing off to tmux attach if a session was selected.

Daemon files

File	Description
`~/.nomadflowcode/nomadflow.pid`	PID of the running daemon process
`~/.nomadflowcode/nomadflow.log`	Stdout/stderr of the daemon process

Environment variables

Variable	Description
`RUST_LOG`	Controls log verbosity (e.g. `nomadflow_server=debug,tower_http=info`). Only effective in `serve` mode — TUI mode suppresses logs to avoid corrupting the terminal display.

Configuration

The CLI reads ~/.nomadflowcode/config.toml on startup. See Configuration for the full reference.

On this page