---
title: "CLI Reference"
description: "Every Orbit command, the flags worth knowing, and the exit codes CI can rely on."
canonical: "https://orbit-handbook.sitesmojo.com/docs/cli-reference/"
---

# CLI Reference

The commands you will actually type. Every command accepts `--env <name>` and
`--help`.

| Command | What it does |
|---------|--------------|
| `orbit init` | Detect the project, write a starter `orbit.yaml` |
| `orbit plan` | Compute and print the release plan; change nothing |
| `orbit deploy` | Plan, show the diff, confirm, apply, verify |
| `orbit promote` | Move an existing release between environments |
| `orbit rollback` | Flip back to a previous release |
| `orbit releases` | List retained releases for an environment |
| `orbit status` | What is live where, and since when |
| `orbit logs` | Tail the live release's logs |
| `orbit doctor` | Diagnose the local setup and print fixes |
| `orbit login` | Authenticate a laptop (device flow) |
| `orbit self-update` | Upgrade the CLI in place |

## Flags worth knowing

| Flag | Where | Effect |
|------|-------|--------|
| `--yes` | `deploy`, `promote`, `rollback` | Skip confirmation (CI) - the diff still prints |
| `--dry-run` | `deploy` | Stop after the diff; apply nothing |
| `--to <n>` | `rollback` | Target a specific release instead of the previous |
| `--json` | `plan`, `status`, `releases` | Machine-readable output for scripts |

## Exit codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Deploy failed; environment left unchanged |
| 2 | Plan produced no changes (useful as a CI gate) |
| 3 | Configuration error - the message names the line |