CLI Reference
Global options
The flags that actually work across every command, odysseus version, and the one flag that's commonly assumed to be global but isn't.
--config FILE
Path to deploy.yml. Default: deploy.yml in the working directory. Every command that reads config does it the same way — options[:config] || 'deploy.yml' — and the dependency and app subcommands parse --config again for themselves.
secrets is the exception: its subcommands take --file (default secrets.yml.enc), not --config, and never read deploy.yml at all. Passing --config to one of them is an error, not a no-op.
odysseus deploy --config path/to/deploy.yml
odysseus dependency status --config path/to/deploy.yml
--debug (and ODYSSEUS_DEBUG=1)
This is the flag worth reaching for first when something doesn't work, because it shows the literal shell line that ran on the host — which is usually where the answer is.
--debug is handled before any command is dispatched: odysseus checks for it (and for ODYSSEUS_DEBUG=1 in the environment) right at the top of main, then deletes --debug from the argument list before anything else looks at it. That's why it works everywhere, including in front of dependency, app, and secrets, whose subcommands have option parsers of their own that never had to define it: --debug never reaches them, because it's already gone.
odysseus deploy --debug
ODYSSEUS_DEBUG=1 odysseus deploy
odysseus app shell web1 --debug
It changes two things:
- Output. The step-by-step spinner UI is replaced by plain-text lines printed as things happen, with no animation to interrupt.
deploy's streamed build/deploy output, which is otherwise cleaned up into single-line steps, prints close to raw instead. - The SSH layer. As of 0.9.0, every SSH connection odysseus opens — not just the ones behind
deploy,build,pussh,rollback, andsetup— printsConnecting to user@host:port...andConnected to hostas the connection opens, and prints> <command>for every command it runs on that connection.doctor,status,containers,logs,cleanup, and theapp/dependencyinteractive commands all build their SSH connection through the same helper, which now defaults its ownverbose:to whatever--debugset — so--debugshows their commands too, not only the commands the five listed above already showed it for through-v.
Debug output is not reliably redacted
Redaction exists, but it covers less than you would expect. It is applied only where the CLI wraps its own stdout for a streamed step — deploy's build and deploy phases, and rollback's roll — so only those show [REDACTED] in place of values that look like keys, tokens or passwords.
Everywhere else, --debug prints the command as it was sent. The SSH layer's own > <command> line does no redaction at all, so build, pussh, setup, doctor, status, logs, and every app and dependency command print raw. Treat --debug output as sensitive: read it, do not paste it into an issue or a screen share without checking it first.
-v, --verbose
This is not a global flag, even though it reads like one. It's defined once, in the option parser shared by deploy, rollback, build, pussh, status, containers, logs, cleanup, validate, doctor, and setup — so it parses without error on all eleven — but only five of those commands ever look at options[:verbose]:
| Command | Reads -v/--verbose? |
|---|---|
deploy | Yes |
build | Yes |
pussh | Yes |
rollback | Yes |
setup | Yes |
status, containers, logs, cleanup, validate, doctor | Parsed, then ignored |
Where it's read, it means exactly what --debug means for that command: verbose = options[:verbose] || @ui.debug? is the line in each of the five. There's no separate "verbose" behavior to learn — -v on deploy gets you the same SSH-command output --debug would, without also switching the rest of the UI to plain text.
odysseus deploy -v --image v1.0.0
odysseus setup --as deploy -v
dependency, app, and secrets subcommands go a step further: their option parsers don't define -v/--verbose at all, so passing it is an unrecognized-option error, not a silent no-op.
odysseus app shell web1 -v
# option-parsing error — app's parser has no -v
If a command isn't in the left column above, reach for --debug instead — it works everywhere -v doesn't.
version, --version
odysseus version
odysseus deploy --version
Either spelling prints the same thing and returns immediately, before odysseus loads a deploy.yml or opens a connection — it's answered first, ahead of everything else in main, specifically so it works with neither. --version is recognized anywhere on the command line, not just as the first argument; version as a bare command has to be first.
There's no -v short form for it: -v is already --verbose, so --version is the only spelling.
Output:
odysseus 0.9.0 (odysseus-core 0.9.0)
ruby 4.0.6p0 [x86_64-linux]
The first line is the CLI gem's own version followed by the odysseus-core library version it's running against — they usually match, but a mismatched install would show up here. The second is whatever ruby -v would report, minus the platform build details odysseus doesn't print: version, patchlevel, and platform.