Commands Reference¶

The Compose Farm CLI is available as both compose-farm and the shorter alias cf.

Command Overview¶

Category	Command	Description
Lifecycle	`apply`	Make reality match config
	`up`	Start stacks
	`down`	Stop stacks
	`restart`	Restart stacks (down + up)
	`update`	Update stacks (pull + build + down + up)
	`pull`	Pull latest images
Monitoring	`ps`	Show stack status
	`logs`	Show stack logs
	`stats`	Show overview statistics
Configuration	`check`	Validate config and mounts
	`refresh`	Sync state from reality
	`init-network`	Create Docker network
	`traefik-file`	Generate Traefik config
	`config`	Manage config files
	`ssh`	Manage SSH keys
Server	`web`	Start web UI

Global Options¶

cf --version, -v    # Show version
cf --help, -h       # Show help

Lifecycle Commands¶

cf apply¶

Make reality match your configuration. The primary reconciliation command.

cf apply [OPTIONS]

Options:

Option	Description
`--dry-run, -n`	Preview changes without executing
`--no-orphans`	Skip stopping orphaned stacks
`--full, -f`	Also refresh running stacks
`--config, -c PATH`	Path to config file

What it does:

Stops orphaned stacks (in state but removed from config)
Migrates stacks on wrong host
Starts missing stacks (in config but not running)

Examples:

# Preview what would change
cf apply --dry-run

# Apply all changes
cf apply

# Only start/migrate, don't stop orphans
cf apply --no-orphans

# Also refresh all running stacks
cf apply --full

cf up¶

Start stacks. Auto-migrates if host assignment changed.

cf up [OPTIONS] [STACKS]...

Options:

Option	Description
`--all, -a`	Start all stacks
`--host, -H TEXT`	Filter to stacks on this host
`--config, -c PATH`	Path to config file

Examples:

# Start specific stacks
cf up plex sonarr

# Start all stacks
cf up --all

# Start all stacks on a specific host
cf up --all --host nuc

Auto-migration:

If you change a stack's host in config and run cf up:

Verifies mounts/networks exist on new host
Runs down on old host
Runs up -d on new host
Updates state

cf down¶

Stop stacks.

cf down [OPTIONS] [STACKS]...

Options:

Option	Description
`--all, -a`	Stop all stacks
`--orphaned`	Stop orphaned stacks only
`--host, -H TEXT`	Filter to stacks on this host
`--config, -c PATH`	Path to config file

Examples:

# Stop specific stacks
cf down plex

# Stop all stacks
cf down --all

# Stop stacks removed from config
cf down --orphaned

# Stop all stacks on a host
cf down --all --host nuc

cf restart¶

Restart stacks (down + up).

cf restart [OPTIONS] [STACKS]...

Options:

Option	Description
`--all, -a`	Restart all stacks
`--config, -c PATH`	Path to config file

Examples:

cf restart plex
cf restart --all

cf update¶

Update stacks (pull + build + down + up).

cf update [OPTIONS] [STACKS]...

Options:

Option	Description
`--all, -a`	Update all stacks
`--config, -c PATH`	Path to config file

Examples:

# Update specific stack
cf update plex

# Update all stacks
cf update --all

cf pull¶

Pull latest images.

cf pull [OPTIONS] [STACKS]...

Options:

Option	Description
`--all, -a`	Pull for all stacks
`--config, -c PATH`	Path to config file

Examples:

cf pull plex
cf pull --all

Monitoring Commands¶

cf ps¶

Show status of stacks.

cf ps [OPTIONS] [STACKS]...

Options:

Option	Description
`--all, -a`	Show all stacks (default)
`--host, -H TEXT`	Filter to stacks on this host
`--config, -c PATH`	Path to config file

Examples:

# Show all stacks
cf ps

# Show specific stacks
cf ps plex sonarr

# Filter by host
cf ps --host nuc

cf logs¶

Show stack logs.

cf logs [OPTIONS] [STACKS]...

Options:

Option	Description
`--all, -a`	Show logs for all stacks
`--host, -H TEXT`	Filter to stacks on this host
`--follow, -f`	Follow logs (live stream)
`--tail, -n INTEGER`	Number of lines (default: 20 for --all, 100 otherwise)
`--config, -c PATH`	Path to config file

Examples:

# Show last 100 lines
cf logs plex

# Follow logs
cf logs -f plex

# Show last 50 lines of multiple stacks
cf logs -n 50 plex sonarr

# Show last 20 lines of all stacks
cf logs --all

cf stats¶

Show overview statistics.

cf stats [OPTIONS]

Options:

Option	Description
`--live, -l`	Query Docker for live container counts
`--config, -c PATH`	Path to config file

Examples:

# Config/state overview
cf stats

# Include live container counts
cf stats --live

Configuration Commands¶

cf check¶

Validate configuration, mounts, and networks.

cf check [OPTIONS] [STACKS]...

Options:

Option	Description
`--local`	Skip SSH-based checks (faster)
`--config, -c PATH`	Path to config file

Examples:

# Full validation with SSH
cf check

# Fast local-only validation
cf check --local

# Check specific stack and show host compatibility
cf check jellyfin

cf refresh¶

Update local state from running stacks.

cf refresh [OPTIONS]

Options:

Option	Description
`--dry-run, -n`	Show what would change
`--log-path, -l PATH`	Path to Dockerfarm TOML log
`--config, -c PATH`	Path to config file

Examples:

# Sync state with reality
cf refresh

# Preview changes
cf refresh --dry-run

cf init-network¶

Create Docker network on hosts with consistent settings.

cf init-network [OPTIONS] [HOSTS]...

Options:

Option	Description
`--network, -n TEXT`	Network name (default: mynetwork)
`--subnet, -s TEXT`	Network subnet (default: 172.20.0.0/16)
`--gateway, -g TEXT`	Network gateway (default: 172.20.0.1)
`--config, -c PATH`	Path to config file

Examples:

# Create on all hosts
cf init-network

# Create on specific hosts
cf init-network nuc hp

# Custom network settings
cf init-network -n production -s 10.0.0.0/16 -g 10.0.0.1

cf traefik-file¶

Generate Traefik file-provider config from compose labels.

cf traefik-file [OPTIONS] [STACKS]...

Options:

Option	Description
`--all, -a`	Generate for all stacks
`--output, -o PATH`	Output file (stdout if omitted)
`--config, -c PATH`	Path to config file

Examples:

# Preview to stdout
cf traefik-file --all

# Write to file
cf traefik-file --all -o /opt/traefik/dynamic.d/cf.yml

# Specific stacks
cf traefik-file plex jellyfin -o /opt/traefik/cf.yml

cf config¶

Manage configuration files.

cf config COMMAND

Subcommands:

Command	Description
`init`	Create new config with examples
`show`	Display config with highlighting
`path`	Print config file path
`validate`	Validate syntax and schema
`edit`	Open in $EDITOR
`symlink`	Create symlink from default location

Options by subcommand:

Subcommand	Options
`init`	`--path/-p PATH`, `--force/-f`
`show`	`--path/-p PATH`, `--raw/-r`
`edit`	`--path/-p PATH`
`path`	`--path/-p PATH`
`validate`	`--path/-p PATH`
`symlink`	`--force/-f`

Examples:

# Create config at default location
cf config init

# Create config at custom path
cf config init --path /opt/compose-farm/config.yaml

# Show config with syntax highlighting
cf config show

# Show raw config (for copy-paste)
cf config show --raw

# Validate config
cf config validate

# Edit config in $EDITOR
cf config edit

# Print config path
cf config path

# Create symlink to local config
cf config symlink

# Create symlink to specific file
cf config symlink /opt/compose-farm/config.yaml

cf ssh¶

Manage SSH keys for passwordless authentication.

cf ssh COMMAND

Subcommands:

Command	Description
`setup`	Generate key and copy to all hosts
`status`	Show SSH key status and host connectivity
`keygen`	Generate key without distributing

Options for cf ssh setup and cf ssh keygen:

Option	Description
`--force, -f`	Regenerate key even if it exists

Examples:

# Set up SSH keys (generates and distributes)
cf ssh setup

# Check status and connectivity
cf ssh status

# Generate key only (don't distribute)
cf ssh keygen

Server Commands¶

cf web¶

Start the web UI server.

cf web [OPTIONS]

Options:

Option	Description
`--host, -H TEXT`	Host to bind to (default: 0.0.0.0)
`--port, -p INTEGER`	Port to listen on (default: 8000)
`--reload, -r`	Enable auto-reload for development

Note: Requires web dependencies: pip install compose-farm[web]

Examples:

# Start on default port
cf web

# Start on custom port
cf web --port 3000

# Development mode with auto-reload
cf web --reload

Common Patterns¶

Daily Operations¶

# Morning: check status
cf ps
cf stats --live

# Update a specific stack
cf update plex

# View logs
cf logs -f plex

Maintenance¶

# Update all stacks
cf update --all

# Refresh state after manual changes
cf refresh

Migration¶

# Preview what would change
cf apply --dry-run

# Move a stack: edit config, then
cf up plex  # auto-migrates

# Or reconcile everything
cf apply

Troubleshooting¶

# Validate config
cf check --local
cf check

# Check specific stack
cf check jellyfin

# Sync state
cf refresh --dry-run
cf refresh