yeet Commands

For agent-readable CLI context, run the command with --help-agent.

yeet --help-agent
yeet run --help-agent
yeet vm images --help-agent

For recipes, start with Workflows. Use this page as a command reference once you know the workflow you need.

These flags work across commands:

• --host=<catch-host>: target a catch host. Also set by CATCH_HOST.
• --service=<svc>: force a service name when a command can infer one.
• --tty: force TTY mode for remote commands.
• --no-tty: disable TTY mode for remote commands.
• --progress=auto|tty|plain|quiet: choose progress output.

Host shortcuts:

yeet status@<catch-host>

See How Commands Work for service selection and argument routing.

If catch denies a command with missing yeet permission, update the matching Tailscale grant. See Tailscale Access Grants.

Install or update a service from a payload:

Run new-service deploy commands from a Service Workspace. A successful deploy writes or updates yeet.toml in the active workspace.

yeet run --web
yeet run <svc> ./compose.yml
yeet run -p 8080:80 <svc> nginx:alpine
yeet run <svc> ./Dockerfile
yeet run <svc> ./bin/<svc> -- --app-flag value
yeet run <vm> vm://ubuntu/26.04

Target a specific host with <svc>@<catch-host> when needed:

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

<svc> must use lowercase letters, numbers, and dashes, start with a letter, and end with a letter or number.

Common flags:

• --web: open the local guided deploy form.
• --pull: pull fresh images for Compose and image payloads.
• --force: redeploy even when yeet detects no payload or config change.
• -p HOST:CONTAINER: publish host ports for image, Dockerfile, Python, and TypeScript payloads.
• --publish-reset: replace or clear the saved published-port list.
• --net=<mode[,mode...]>: choose service network modes such as svc, svc,ts, lan, or lan,ts. VMs support svc, lan, and svc,lan. VM lan networking prompts to prepare a host bridge when one is not ready.
• --service-root=<path-or-dataset>: choose the initial service root.
• --zfs: treat --service-root as a ZFS dataset.
• --snapshots=on|off|inherit: override service snapshot policy.
• --env-file=<path>: upload an environment file before deploy.
• --vcpus, --memory, --disk: set initial VM resources.
• --image-policy=prompt|update|cached: choose stale VM image behavior.

Related guides:

• Payloads
• Workflows
• Networking for reachability, DNS, and internet egress paths
• ZFS

Upload a payload without applying it. This adds a review point between "bytes arrived" and "service changed":

yeet stage <svc> ./bin/<svc>
yeet stage <svc> show
yeet stage <svc> commit
yeet stage <svc> clear

Install or update a scheduled job:

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

Use Cron Jobs for timer behavior.

Show host or service status:

yeet status
yeet status <svc>
yeet status <svc-a> <svc-b>
yeet status <svc>@<catch-host>

Show host storage and inventory, or detailed service information when a service is supplied:

yeet info
yeet info --host=<catch-host>
yeet info <svc>
yeet info <svc> --format=json

Show service logs:

yeet logs <svc>
yeet logs -f <svc>

Control a service:

yeet start <svc>
yeet stop <svc>
yeet restart <svc>

Enable or disable autostart for systemd-backed services:

yeet enable <svc>
yeet disable <svc>

Show catch events:

yeet events
yeet events@<catch-host>

Remove a service:

yeet rm <svc>

Remove service data and the local config entry too:

yeet rm --clean <svc>

Useful flags:

• --clean: delete service data and the local yeet.toml entry.
• --yes: skip prompts. This does not imply --clean or --clean-data.
• --clean-config: delete the local yeet.toml entry.
• --clean-data: delete service data, including VM guest disks.

Read confirmation prompts carefully before deleting data. --yes answers the prompt; it does not decide that data should be deleted.

Open the current service config in $EDITOR:

yeet edit <svc>

Inspect and manage a service env file:

yeet env show <svc>
yeet env edit <svc>
yeet env copy <svc> ./app.env
yeet env set <svc> PORT=8080 LOG_LEVEL=debug
yeet env set <svc> LOG_LEVEL=

Copy files between local paths and service data or VM guests:

yeet copy ./config.yml <svc>:config/config.yml
yeet copy ./configs/ <svc>:config/
yeet copy ./configs/*.yml <vm>:~/configs/
yeet copy <vm>:"/var/log/*.log" ./logs/
yeet copy --force-proxy ./configs/ <vm>:~/configs/

Regular service endpoints are relative to the service data directory. VM endpoints target the guest filesystem.

Show or update local yeet client config:

yeet config
yeet config --host=<catch-host>
yeet config --workspace ~/yeet-services
yeet config --add-workspace ~/lab-services
yeet config --remove-workspace ~/lab-services
yeet config --clear-workspaces

--workspace replaces the registered workspace list with an existing directory. --add-workspace adds another existing directory.

Show generation state:

yeet service generations <svc>

Generations track deployed definitions and install artifacts. They are not storage snapshots. Rollback changes what was deployed; snapshots recover data.

Roll a non-VM service back to the previous deployed generation:

yeet service rollback <svc>

For VM disk recovery, use snapshots.

Change settings that require an explicit service update:

yeet service set <svc> -p 80:80 -p 443:443
yeet service set <svc> --publish-reset -p 443:443
yeet service set <svc> --service-root=/srv/apps/<svc> --copy
yeet service set <svc> --service-root=tank/apps/<svc> --zfs --copy
yeet service set <svc> --snapshots=off
yeet service set <svc> --snapshots=inherit

Stop the service before moving a service root. Use --copy to copy the old root or --empty to create a fresh root.

Sync live service settings back into an existing yeet.toml entry:

yeet service sync <svc>
yeet service sync --all
yeet service sync <svc> --config ./yeet.toml

Check Compose services for upstream image updates without changing containers:

yeet docker outdated
yeet docker outdated <svc>
yeet docker outdated --format=json

Prefetch images for a Compose service without restarting:

yeet docker pull <svc>

Pull images and recreate Compose containers:

yeet docker update <svc>
yeet docker update <svc-a> <svc-b>@<catch-host>
yeet docker update --outdated

Push a local image to the catch host:

yeet docker push <svc> <local-image>:<tag> --run

Show catalog and cache state, update image bundles, import local images, or prune old cache entries:

yeet vm images catalog
yeet vm images
yeet vm images update
yeet vm images update vm://nixos/26.05
yeet vm images import lab/ubuntu ./dist/my-vm
yeet vm images rm lab/ubuntu --yes
yeet vm images prune --dry-run

Official catalog images are published from yeetrun/yeet-vm-images. Use VMs for the full VM image workflow.

Stop the VM before changing VM resources or networking:

yeet stop <vm>
yeet vm set <vm> --vcpus=6 --memory=6g --disk=128g
yeet vm set <vm> --net=svc,lan
yeet start <vm>

Stream a VM serial console:

yeet vm console <vm>

Detach by pressing Enter, then typing ~..

Snapshots are yeet recovery points for ZFS-backed service roots and VM disks. They are for storage state.

yeet snapshots list <svc>
yeet snapshots inspect <svc> <snapshot>
yeet snapshots create <svc> --comment "before upgrade"
yeet snapshots clone <svc> <snapshot> <svc>-recover
yeet snapshots restore <svc> <snapshot> --stop --yes

yeet snapshots defaults show
yeet snapshots defaults set --enabled=true --keep-last=5 --max-age=7d
yeet snapshots protect <svc> <snapshot>
yeet snapshots unprotect <svc> <snapshot>
yeet snapshots rm <svc> <snapshot>

For VM full checkpoints:

yeet snapshots create <vm> --full --comment "checkpoint before risky change"
yeet snapshots restore <vm> <snapshot> --mode=full --stop --yes

A full restore completes only after the restored VM runner remains stable and the guest agent confirms SSH readiness.

Use ZFS for snapshot defaults, retention, clone-first recovery, and VM restore behavior.

Open a catch host shell, a service shell, or a VM guest shell:

yeet ssh
yeet ssh <svc>
yeet ssh --force-proxy <vm>
yeet ssh -- uname -a
yeet ssh <svc> -- ls -la

After yeet init, host and regular service shells use catch over Tailscale and do not require host SSH keys or a host password. yeet ssh <svc> starts in the service data directory. VM services still connect to the guest operating system with SSH, because the guest is a real machine and gets its own authentication boundary.

Show connectable service or VM IP endpoints:

yeet ip <svc>

Set up Tailscale OAuth for the catch host or run Tailscale commands for a service identity:

yeet tailscale --setup
yeet tailscale <svc> -- status
yeet ts <svc> serve --bg 3000
yeet ts <svc> update

Use Tailscale for tag and OAuth setup. Use Networking before choosing plain --net=ts; most Tailscale-exposed services should use svc,ts unless they are intentionally tailnet-only or use an exit node.

Install or update catch on a machine host over SSH:

yeet init root@<machine-host>
yeet --host=morpheus-catch init root@<machine-host>
yeet init --workspace ~/yeet-services root@<machine-host>
yeet init --no-workspace root@<machine-host>
yeet init --data-dir=/srv/yeet-data root@<machine-host>
yeet init --zfs --data-dir=flash/yeet/data --services-root=flash/yeet/services root@<machine-host>
yeet init

Fresh interactive installs ask where catch should store host data. The default is $HOME/yeet-data on the catch host, with services under that data directory. Existing catch installs keep their current storage layout when you rerun yeet init.

The default catch Tailscale hostname is catch. Use the global --host target before init when adding another catch host to the same tailnet.

For normal setup, run yeet init root@<machine-host> and answer the prompts. For unattended setup, these flags answer init prompts:

Flag	What it does
--ts-client-secret=<secret>	Tailscale OAuth client secret for catch enrollment
--ts-auth-key=<key>	Preauthorized Tailscale auth key for the catch node
--workspace <path>	Create or adopt a service workspace and register it for the selected host
--no-workspace	Skip workspace setup during init
--install-docker	Answers yes to installing Docker when Docker is missing on a supported host
--install-vm-tools	Answers yes to installing VM tools when the host can run VMs

On supported Debian/Ubuntu VM hosts, interactive yeet init can also prepare br0 for VM --net=lan networking after confirmation.

Use Host Setup for the full bootstrap flow.

Change catch host storage after install:

yeet info
yeet host set --data-dir=/srv/yeet-data
yeet host set --services-root=/srv/yeet-services --migrate-services=none
yeet host set --zfs --data-dir=flash/yeet/data --services-root=flash/yeet/services --migrate-services=all

Use --data-dir for catch state and registry data. Use --services-root for the default root of services that do not have their own explicit root. If you change --services-root, choose --migrate-services=all to move affected services or --migrate-services=none to pin them at their existing roots. Run yeet info before or after the change to see the current host data directory, services root, catch service root, and service/VM inventory.

With --zfs, --data-dir and --services-root are dataset names. A ZFS services root is a dataset prefix, so migrated services and catch use child datasets such as flash/yeet/services/<svc>.

Without --yes, yeet prints the plan and asks before applying it. If --migrate-services is omitted in an interactive terminal, yeet asks whether to migrate affected services. With --yes, pass the migration mode explicitly.

When services move, yeet updates matching entries in the local yeet.toml. Pass --config ./yeet.toml when the project config is somewhere else.

Check and install public yeet/catch releases:

yeet upgrade check
yeet upgrade
yeet upgrade --host=<catch-host>
yeet upgrade --force
yeet upgrade --nightly
yeet upgrade check --nightly
yeet upgrade --version v0.6.1 --force

When run from a service workspace with yeet.toml, yeet upgrade includes all project catch hosts plus the default catch host. Use --host=<catch-host> to upgrade one catch host.

Use --nightly to target the latest nightly release. Use --version to target a specific public release tag; do not use both in the same command.

Show the catch server version for the selected host:

yeet version

List tailnet hosts matching tags:

yeet list-hosts

This command uses the local Tailscale client for discovery. Normal yeet commands do not require a local Tailscale client API, but your workstation still needs network reachability to the catch Tailscale address.

Mount a network filesystem on the host. With no arguments, list mounts:

yeet mount host:/export data-share --type=nfs --opts=defaults
yeet mount

Unmount by mount name:

yeet umount data-share