CLI reference

Every subcommand and flag. Exit codes are stable and documented at the bottom.

shipyard deploy

shipyard deploy [config]
  --dry-run                show what would happen, stop after SSH connect
  --skip-health            flip without running the health check (don't)
  --release-id <ts>        override the auto-generated YYYYMMDDhhmmss timestamp
  --force                  ignore an active remote lock and steal it

Runs the full 13-step lifecycle described on the home page. The pipeline:

1. Parse config (strict mode — unknown fields rejected).
2. Run pre_upload hooks locally.
3. SSH connect, host-key verify against ~/.ssh/known_hosts.
4. Acquire remote lockfile (steals stale ones past TTL).
5. SFTP-upload the artifact into _incoming/<timestamp>.<ext>.
6. Extract into releases/<timestamp>/.
7. Symlink shared.files and shared.dirs into the release dir.
8. Run post_extract hooks remotely (cwd: the new release dir).
9. Atomic symlink flip: ln -s …/releases/<ts> current.new && mv -Tf current.new current.
10. Run post_flip hooks remotely. Failure here triggers rollback.
11. Run health check. Failure triggers rollback.
12. Auto-prune (honors releases.keep, never deletes the current release).
13. Release lockfile.

shipyard rollback

shipyard rollback [config]
  --to <timestamp>         roll back to a specific release (default: previous)

Atomically swap the current symlink to the previous (or specified) release, then run on_rollback hooks. Deploys after a rollback continue from the rolled-back state — shipyard deploy picks the next timestamp as expected.

shipyard status

shipyard status [config]
  --format pretty | json   output format (default: pretty)

Shows app, host, release root, current release (highlighted with *), every release on the remote with mtime, and lock state. Pretty mode is for humans; JSON is for scripts.

shipyard releases

shipyard releases [config]

Newest-first list of every releases/<timestamp> directory with the current one marked.

shipyard prune

shipyard prune [config]
  --keep <n>               override config; keep this many releases
  --dry-run                list what would be deleted, do not delete

Manual prune. The auto-prune step at the end of every successful deploy uses the same code path. The current release is never deleted, even if it’s outside the keep window (post-rollback case).

shipyard doctor

shipyard doctor [config]
  --config-only            stop after YAML parse + validation; skip SSH checks

Validates the config and (for the non---config-only path, landing in v0.2) attempts an SSH connection plus a writability check on release_root and shared/. Run this in CI to catch typos before they reach a deploy.

shipyard init

shipyard init

Interactive config generator. Lands in v0.2. Until then, copy an example and edit.

shipyard version

shipyard version

Prints the semver, short commit, and build date. Reproducible from git checkout + go build -ldflags "…" — the exact command is in the version source file.

Global flags

--no-color    disable colored output (also honors NO_COLOR)
--verbose     emit JSON to stderr in addition to pretty stdout
--version     same as 'shipyard version'
--help        help for any command

Exit codes

← Quickstart · ← Config reference