How Commands Work

Yeet runs on your workstation. Catch runs on remote hosts. Most yeet commands send requests to the selected catch host.

The command model has three recurring questions: which host, which service, and which arguments belong to yeet versus the payload. When a command behaves unexpectedly, check those boundaries first.

Setup uses an SSH machine host:

yeet init root@<machine-host>

Normal commands use the catch host:

CATCH_HOST=<catch-host> yeet status
yeet --host=<catch-host> status
yeet status@<catch-host>

The default catch host is catch. For a second host, pick a distinct catch hostname during setup:

yeet --host=morpheus-catch init root@<machine-host>

Run new-service deploy commands from a Service Workspace so the generated yeet.toml lands in the directory you intend to use for that service set.

Target a specific host when deploying:

yeet run <svc>@<catch-host> ./compose.yml

If yeet.toml contains a host list, yeet status with no service queries those hosts.

Save a default host:

yeet config --host=<catch-host>

Most service commands accept a service name:

yeet status <svc>
yeet status <svc-a> <svc-b>
yeet info
yeet info <svc>
yeet logs -f <svc>

New service names must use lowercase letters, numbers, and dashes, start with a letter, and end with a letter or number.

Use --service=<svc> only when a command needs an explicit override:

yeet --service=<svc> logs -f

Some commands are host-level and do not target a service, such as config, list-hosts, mount, and umount.

Use -- when arguments belong to the service payload instead of yeet:

yeet run <svc> ./bin/<svc> -- --flag value
yeet cron <svc> ./job.sh "0 9 * * *" -- --job-arg foo

This keeps yeet flags and application flags separate. Without the separator, every parser in the chain has to guess where its job ends.

Use standard help for people and structured help for AI tools or scripts:

yeet --help
yeet run --help
yeet run --help-agent

Use yeet Commands for a grouped command index.

Interactive commands such as yeet edit, yeet env edit, and some prompts need a TTY. Run them from an interactive shell. For scripts, prefer explicit flags such as --yes, --progress=plain, or --progress=quiet where the command supports them.