CLI Commands

Command reference, flags, TUI controls, and environment file loading.

Reference

Commands

Command	Alias	Description
`fuku run [profile]`	`r`	Run services for a profile (default if omitted)
`fuku stop [profile]`	`s`	Stop the running fuku of the project gracefully, then kill what is left in the service directories. When the running fuku cannot be reached, it exits 1 and stops nothing
`fuku logs [services...]`	`l`	Stream logs from a running fuku instance
`fuku doctor [profile]`	—	Diagnose configuration, environment, topology, and runtime issues
`fuku init`	`i`	Generate a `fuku.yaml` template
`fuku version`	`-v`, `--version`	Show version
`fuku help`	`-h`, `--help`	Show help

Options

Flags

Flag	Description
`--config`, `-c`	Path to config file (default: `fuku.yaml`, falls back to `fuku.yml`). Disables automatic override file merging. Supported with `run`, `stop`, `logs`, and `doctor` commands
`--no-ui`	With `run`, run without the interactive TUI (log-only mode). With `logs`, hide the logs panel and the footer and keep the log lines
`--detached`, `-d`	Run in the background and return once every service is running. Exits 1 when a service fails and stops what started, 130 on `Ctrl-C`. Supported with `run` only
`--profile`	Profile the running instance must serve; `logs` exits with 1 on a mismatch
`--tail`	Replay at most the newest n buffered messages, in total across the named services. Must be greater than zero. Supported with `logs` only
`--no-follow`	Exit once the buffered replay is written instead of following new lines. Supported with `logs` only
`--summary`	Print a compact one-line-per-check report (used with `doctor` command)
`--json`	Print the report as machine-readable JSON (used with `doctor` command)

Flags can be placed in any position:

terminal

fuku run core --no-ui
fuku --no-ui run core        # Same result

Examples

Usage examples

terminal

# Run with TUI (default profile)
fuku

# Run a specific profile without TUI
fuku run core --no-ui

# Use short aliases
fuku r core

# Run in the background and return once every service is running
fuku run core -d

# Stop the running fuku, then the services of a profile
fuku stop                       # Default profile
fuku stop core                  # Specific profile

# Stream logs from running instance (separate terminal)
fuku logs                       # All services
fuku logs api auth              # Specific services
fuku logs api --profile core    # Filter by profile
fuku l api db                   # Short alias

# Bounded log read for scripts and agents
fuku logs api --tail 100        # At most the newest 100 buffered messages, then follow
fuku logs api --no-follow       # Replay the buffered messages and exit
fuku logs api --no-ui --tail 100 --no-follow  # No panel, at most 100 messages, then exit

# Use a custom config file
fuku --config path/to/fuku.yaml run core
fuku -c custom.yaml run core

# Diagnose configuration, environment, and runtime issues
fuku doctor                     # Default profile
fuku doctor core                # Specific profile
fuku doctor --summary           # Compact one-line-per-check report
fuku doctor --json              # Machine-readable report

# Generate config template
fuku init

# Show help / version
fuku help
fuku version

Diagnostics

fuku doctor

fuku doctor runs a read-only health check and prints a sectioned report — Environment, Configuration, Services,Topology, and Runtime. It diagnoses a broken setup without starting any services, so it works even when the config fails to load. See Troubleshooting for what each section checks.

Each check carries a status glyph:

Glyph	Meaning
`✓`	ok
`○`	idle (inactive but expected)
`↑`	note (informational)
`⚠`	warning (non-fatal)
`✗`	failure

The exit code makes doctor usable in scripts and CI:

Exit code	Meaning
`0`	No failures (warnings and notes are allowed)
`2`	At least one check failed
`3`	doctor itself errored (e.g. failed to write the JSON report)

Keyboard

TUI controls

When running with the interactive TUI (default), use these keyboard shortcuts:

Key	Action
`↑` / `↓` or `k` / `j`	Navigate services (or scroll the focused panel)
`PgUp` / `PgDn`	Scroll the focused panel
`Home` / `End`	Jump to start / end of the focused panel
`Enter`	Open the service info aside (toggles closed when already open)
`Tab` / `Shift+Tab`	Cycle aside tabs forward / backward
`\`	Toggle focus between the services list and the aside
`s`	Stop or start the selected service
`r`	Restart the selected service
`ctrl+r`	Restart all failed services
`t`	Show or hide the rotating tips
`/`	Filter services by name
`Esc`	Close the service info aside, or clear filter when it is already closed
`q`	Quit and stop all services

Environment

Environment file loading

On startup, fuku loads its own environment files using godotenv, in this order (the first file to set a variable wins):

.env.<GO_ENV>.local
.env.<GO_ENV>
.env

GO_ENV must be set before fuku starts. Fuku reads it before any file, so a GO_ENV in .env does not select .env.<GO_ENV>.

These files configure the fuku process itself. Each service inherits fuku's environment but does not receive any per-service variables injected by fuku — child processes run in their service dir and are responsible for loading their own .env files.

Per-service .env files are still read by fuku, but only for display in the TUI's info aside (the env tab). By default fuku reads .env, .env.local, .env.development, and .env.development.local from each service's dir; override the list with the per-service env.files field (see Configuration).