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 services by killing processes in service directories
`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`	Run without the interactive TUI (log-only mode)
`--profile`	Filter by profile (used with `logs` command)
`--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

# Stop services for 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 --profile core api    # Filter by profile
fuku l api db                   # Short alias

# 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
`/`	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 (later files take precedence):

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

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