# rototo CLI reference
## Global Flags
- `--json`: emit machine-readable JSON where supported.
- `--quiet`: suppress success output from lint commands.
- `--workspace-token`: bearer token for `https://` workspace archive sources.
Can also be set with `ROTOTO_WORKSPACE_TOKEN`.
- `--version`: print the rototo version.
- `--help`: print command help.
## Workspace Commands
- `rototo inspect <workspace> [-v <variable> ...] [-q <qualifier> ...]`
- `rototo lint <workspace> [-v <variable> ...] [-q <qualifier> ...] [--verbose]`
- `rototo list <workspace> [-v] [-q]`
- `rototo get <workspace> [-v <variable> ...] [-q <qualifier> ...]`
- `rototo resolve <workspace> [-v <variable> ...] [-q <qualifier> ...] --env <env> -c <context> [--verbose]`
`inspect` is an orientation command. It confirms which workspace was loaded,
shows the environment and context schema, maps variables to environment defaults
and qualifier-backed rules, shows qualifier dependencies, shows where qualifiers
are used, and prints the next commands to lint or resolve the loaded
configuration.
When `inspect` receives `-v` or `-q`, it switches from the workspace map to a
detailed entity view. Variable inspection shows the source file, description,
contract, custom lint, expanded values, environment defaults, and qualifier
rules. Qualifier inspection shows the source file, description, and predicates.
Workspace inputs can be local paths, `file://` URIs, `git+file://`,
`git+https://`, `git+ssh://`, or `https://` archive URLs. Plain `http://`
sources are rejected. Git sources support `#ref:subdir`; archive URLs support
`#:subdir`.
Use `-v` or `--variable` to select variables. Use `-q` or `--qualifier` to
select qualifiers. Flags that take ids are repeatable, so one command can lint,
get, or resolve several workspace entities against the same workspace and
context.
When no `-v` or `-q` flag is passed to `lint`, rototo lints the whole
workspace. When no `-v` or `-q` flag is passed to `list`, rototo lists both
variables and qualifiers. `get` and `resolve` require at least one selected
variable or qualifier. Resolving variables requires `--env`; resolving only
qualifiers does not.
Pass `--verbose` to `lint` when you need to see which workspace was staged and
which lint targets ran. Pass `--verbose` to `resolve` when you need to see the
workspace source, staged workspace path, selected targets, merged context,
environment fallback, rule order, qualifier definitions, predicates, bucket
math, and selected values before the normal result. Verbose traces are
human-readable only; `--json` output stays machine-readable and omits the trace.
Resolution commands accept repeatable `-c` or `--context` inputs. Each value can
be a JSON object, `@path/to/context.json`, or `path=value`; later inputs override
earlier ones. Qualifiers are resolved against that context. Variables resolve by
environment, applying matching rules before the environment's fallback value.
## Examples
```sh
rototo resolve ./workspace -v llm-agent-config --env prod \
-c '{"user":{"tier":"premium"}}'
rototo resolve ./workspace -v llm-agent-config -v checkout-redesign --env prod \
-c @context.json
rototo resolve ./workspace -q enterprise-accounts \
-c account.plan=enterprise -c account.seats=250
rototo lint git+https://github.com/acme/config.git#main:rototo
ROTOTO_WORKSPACE_TOKEN=secret rototo inspect \
https://example.com/rototo-workspace.tar.gz#:workspace
```
## Documentation Commands
- `rototo docs`
- `rototo docs --page <page-prefix>`
- `rototo docs -p <page-prefix>`
- `rototo docs --search <regex> [regex ...]`
- `rototo docs -s <regex> [regex ...]`
The CLI bundles documentation as Markdown. With no flags, `rototo docs` lists
the bundled pages. `--page` and `-p` pretty-print one page in the terminal.
`--search` and `-s` search page ids and Markdown content with one or more regex
terms; all terms must match for a page to be listed. For example, use
`rototo docs -s 'refresh|last-known-good'` to search with a regex. HTML export
and local serving are left to the public documentation site toolchain.
## Terminal Color
Human-readable CLI output uses rototo terminal colors when stdout or stderr is
a terminal. Machine-readable `--json` output is never styled. Set `NO_COLOR` to
disable color. Set `CLICOLOR_FORCE=1` to force color in a non-terminal.
The palette uses the terminal-specific design-system tokens: foreground labels,
clay URI accents, blue IDs, dim paths, green success states, and red errors.
The CLI only styles foreground text; the terminal background remains controlled
by the user's terminal profile.
## Diagnostic Commands
- `rototo diagnostics list`
- `rototo diagnostics get <code>`
Diagnostics are global today.
## Shell Completions
- `rototo completions bash`
- `rototo completions elvish`
- `rototo completions fish`
- `rototo completions power-shell`
- `rototo completions zsh`
## Exit Policy
- `0`: command succeeded.
- `1`: lint found diagnostics, the command was used incorrectly, or rototo
could not complete the request.