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. On first run, the TUI begins with the setup wizard to create ~/.nomadflowcode/config.toml. When the TUI exits, the server is gracefully shut down.

`serve`

nomadflow serve [--public] [--host <address>] [--port <port>]

Runs the HTTP server in the foreground with full tracing/logging enabled. Use this for headless deployments, Docker containers, or systemd services. If no config exists, the setup wizard runs first.

Option	Description
`--public`	Expose the server publicly via tunnel. See Public Tunnel.
`--host <address>`	Override the displayed address (IP or domain name) for QR code and URL.
`--port <port>`	Override the API server port (default: from `config.toml`, fallback `8080`).

The server handles graceful shutdown: on Ctrl+C or SIGTERM, it stops accepting new connections, completes in-flight requests, and cleanly shuts down all managed PTY processes.

`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.

`web`

nomadflow web [--port <port>]

Starts a lightweight HTTP server that serves the web dashboard (static files), then opens it in your default browser. This is a standalone server — no auth required.

Option	Description
`--port <port>`	Override the dashboard port (default: from `config.toml`, fallback `3000`).

`link`

nomadflow link <path> [--name <name>]

Links an existing git repository to NomadFlow. The repository will appear in the repo list without cloning.

Option	Description
`<path>`	Path to the git repository.
`--name <name>`	Custom name for the link (defaults to the directory name).

`unlink`

nomadflow unlink [<name>]

Removes a previously linked repository from NomadFlow. If no name is given, shows a picker.

`attach`

nomadflow attach [--pane <id>]

Attaches to a server-managed PTY pane via a Unix socket. This provides a native terminal experience directly in your CLI.

Option	Description
`--pane <id>`	(Optional) The numeric ID of the pane to attach to. If omitted, shows an interactive picker.

Options

`--status`

nomadflow --status

Displays the current daemon status (running/not running, PID) and the active PTY panes (repo, worktree, agent type), then exits.

TUI wizard

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

Setup wizard — first-run configuration: choose password, enable tunnel, set subdomain
Resume — quick recall of the last active session
Session picker — list and resume active PTY sessions
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.

Daemon files

File	Description
`~/.nomadflowcode/nomadflow.pid`	PID of the running daemon process
`~/.nomadflowcode/nomadflow.log`	Stdout/stderr of the daemon process
`~/.nomadflowcode/nomadflow.sock`	Unix socket for local CLI `attach`

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