compose-farm/docs/commands.md

icon

icon
lucide/terminal

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 services
	down	Stop services
	restart	Restart services (down + up)
	update	Update services (pull + down + up)
	pull	Pull latest images
Monitoring	ps	Show service status
	logs	Show service 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 services
--full, -f	Also refresh running services
--config, -c PATH	Path to config file

What it does:

1. Stops orphaned services (in state but removed from config)
2. Migrates services on wrong host
3. Starts missing services (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 services
cf apply --full

---

cf up

Start services. Auto-migrates if host assignment changed.

cf up [OPTIONS] [SERVICES]...

Options:

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

Examples:

# Start specific services
cf up plex sonarr

# Start all services
cf up --all

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

Auto-migration:

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

1. Verifies mounts/networks exist on new host
2. Runs down on old host
3. Runs up -d on new host
4. Updates state

---

cf down

Stop services.

cf down [OPTIONS] [SERVICES]...

Options:

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

Examples:

# Stop specific services
cf down plex

# Stop all services
cf down --all

# Stop services removed from config
cf down --orphaned

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

---

cf restart

Restart services (down + up).

cf restart [OPTIONS] [SERVICES]...

Options:

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

Examples:

cf restart plex
cf restart --all

---

cf update

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

cf update [OPTIONS] [SERVICES]...

Options:

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

Examples:

# Update specific service
cf update plex

# Update all services
cf update --all

---

cf pull

Pull latest images.

cf pull [OPTIONS] [SERVICES]...

Options:

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

Examples:

cf pull plex
cf pull --all

---

Monitoring Commands

cf ps

Show status of services.

cf ps [OPTIONS] [SERVICES]...

Options:

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

Examples:

# Show all services
cf ps

# Show specific services
cf ps plex sonarr

# Filter by host
cf ps --host nuc

---

cf logs

Show service logs.

cf logs [OPTIONS] [SERVICES]...

Options:

Option	Description
--all, -a	Show logs for all services
--host, -H TEXT	Filter to services 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 services
cf logs -n 50 plex sonarr

# Show last 20 lines of all services
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] [SERVICES]...

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 service and show host compatibility
cf check jellyfin

---

cf refresh

Update local state from running services.

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] [SERVICES]...

Options:

Option	Description
--all, -a	Generate for all services
--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 services
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 PATH	Symlink from default location

Examples:

cf config init
cf config show
cf config validate
cf config edit
cf config path
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

Examples:

# Set up SSH keys
cf ssh setup

# Check status
cf ssh status

---

Server Commands

cf web

Start the web UI server.

cf web [OPTIONS]

See cf web --help for available options.

---

Common Patterns

Daily Operations

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

# Update a specific service
cf update plex

# View logs
cf logs -f plex

Maintenance

# Update all services
cf update --all

# Refresh state after manual changes
cf refresh

Migration

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

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

# Or reconcile everything
cf apply

Troubleshooting

# Validate config
cf check --local
cf check

# Check specific service
cf check jellyfin

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