# The CLI
The `rototo` command line is how you create, check, and explore a package by
hand - and how CI does the same thing automatically. This page is the reference
for every command and flag.
Everything follows one shape:
```text
rototo <verb> [package-source] [selectors] [flags]
```
A **verb** says what to do (`lint`, `resolve`, `show`…). The **package source**
says which package to do it to. **Selectors** narrow it down to specific
variables or qualifiers. And a few **flags** work everywhere. Let's cover the
things that are shared first, then go command by command.
## The package argument
Most commands take a package source as their first argument. That's the same
flexible string described in full on the [package sources](./package-sources.md)
page - a local folder, a git repo, an HTTPS archive.
And for the everyday commands, you can leave it off entirely. When you do, rototo
looks in the current directory and walks upward until it finds a
`rototo-package.toml`. So when you're standing inside your package, `rototo lint`
just works.
(A couple of commands - `init` and `diff` - only make sense against a local
folder, so their argument is a plain path, not a full source. Noted below where
it matters.)
## Global flags
These three work on every command:
- **`--json`** - emit machine-readable JSON instead of the human-readable view.
This is the stable interface for scripts and CI.
- **`--quiet`** - suppress the "all good" success output from lint. Failures
still print.
- **`--package-token <token>`** - a bearer token for private HTTPS archive
downloads. You can also set `ROTOTO_PACKAGE_TOKEN` in the environment instead,
which is usually nicer for CI and services.
## Selectors
Several commands - `lint`, `show`, `inspect`, `resolve`, `fixtures` - let you
zoom in on part of the package instead of the whole thing. The pattern is always
the same: a singular flag picks one thing by id (and repeats), a plural flag
picks all of that kind.
```sh
rototo lint --variable checkout-redesign # just this variable
rototo lint --variable a --variable b # a couple of them
rototo lint --variables # every variable
```
The full set of selectors:
| `--variable <id>` | `--variables` | variables |
| `--qualifier <id>` | `--qualifiers` | qualifiers |
| `--catalog <id>` | `--catalogs` | catalogs |
| `--lint-rule <authority/rule>` | `--lint-rules` | diagnostic rules |
| `--lint-authority <authority>` | `--lint-authorities` | lint authorities |
| `--linter <id>` | `--linters` | your Lua linters |
Not every command takes every selector - `resolve` and `fixtures`, for instance,
only deal in variables and qualifiers, because resolving a catalog or a lint rule
doesn't mean anything. The per-command sections below say which ones apply.
## Context inputs
The commands that evaluate things against runtime facts - `resolve`, `inspect`,
`diff` - take `--context`. You can give it three ways, and they merge left to
right, with later values winning:
```sh
# a path=value pair (dots build nested objects)
--context user.tier=premium
# a raw JSON object
--context '{"user": {"tier": "premium"}}'
# a file of JSON, with a leading @
--context @app-config/evaluation-contexts/request-samples/premium.json
```
Mixing them is fine: `--context @base.json --context user.tier=premium` loads a
file and then overrides one field. If you pass nothing, the context is `{}`.
---
## init - start a new package or add to one
`init` writes files for you so you don't have to remember the folder layout. The
argument is a local path (not a source).
```sh
rototo init app-config # a fresh, empty package
rototo init app-config --variable free-shipping # + a variable template
rototo init app-config --qualifier premium-users # + a qualifier template
rototo init app-config --catalog checkout-redesign # + a catalog template
rototo init app-config --evaluation-context # + an evaluation context
rototo init app-config --evaluation-context request # named "request"
```
Each `--qualifier`, `--variable`, `--catalog`, and `--evaluation-context` takes
the id to create. `--evaluation-context` is special: give it a name, or leave the
name off and it creates `evaluation-contexts/evaluation.schema.json`.
Useful extras:
- **`--update`** (with `--evaluation-context`) - add newly inferred context paths
to an existing schema without clobbering what you've already reviewed.
- **`--dry-run`** - print what *would* be written, change nothing.
- **`--force`** - overwrite files this command created before. (Can't combine
with `--update`.)
## lint - check the package
`lint` is the first gate. It validates the whole rototo model: files parse,
references resolve, schemas compile, values match their types, catalog entries
fit their schemas, custom Lua registers cleanly. Run it constantly while editing,
not just at the end.
```sh
rototo lint # the package you're standing in
rototo lint app-config # a specific one
rototo lint app-config --variable checkout # just one variable
rototo lint app-config --json # structured output
```
Takes all the selectors. What it reports - the diagnostics, their rule names, and
the `--json` shape - is covered on the [diagnostics](./diagnostics.md) page. The
short version of `--json`:
```json
{
"package": "/abs/path/app-config",
"documents": [ { "id": 0, "path": "rototo-package.toml", "kind": "manifest" } ],
"diagnostics": [ ]
}
```
An empty `diagnostics` list means a clean package.
## show - a readable inventory
`show` is the quick "what's in here?" It lists the package's variables,
qualifiers, catalogs, and lint metadata in an easy-to-read form. Reach for it
when you want to confirm a file you edited actually became the variable or
qualifier you intended.
```sh
rototo show app-config
rototo show app-config --variables
rototo show --lint-rules # the diagnostics catalog (see Diagnostics)
```
Takes all the selectors, and supports `--json`.
## inspect - the deep view
`inspect` is `show`'s thorough sibling. Where `show` gives you the inventory,
`inspect` explains how rototo *sees* the package - dependencies, diagnostics,
lint metadata, and the shape it'll use to resolve values. It's especially handy
right before review: a reviewer reads the file diff, and `inspect` shows whether
the model still lines up with those edits.
```sh
rototo inspect app-config --variable checkout-redesign
rototo inspect app-config --qualifier premium-users
rototo inspect app-config --context user.tier=premium
```
Takes all the selectors, plus `--context` (so you can see how things look against
specific facts), and `--json`.
## resolve - evaluate against real facts
`resolve` is where you test behavior. Hand it a context and it tells you what a
variable or qualifier actually comes out to. This is also the command CI leans on
to protect the cases that must never drift.
```sh
# a variable, against a sample context
rototo resolve app-config --variable checkout-redesign \
--context @app-config/evaluation-contexts/request-samples/premium.json
# a qualifier, against an inline fact
rototo resolve app-config --qualifier premium-users --context user.tier=premium
```
It only takes the variable and qualifier selectors (resolving a catalog or rule
doesn't mean anything), plus `--context`.
The `--json` output is the stable interface for tests. A variable resolution
gives you the chosen `value`, where it came from (`source`), and - handy for
debugging - the default and every rule that was considered:
```json
{
"package": "app-config",
"variables": [
{
"resolution": {
"id": "checkout-redesign",
"value": { "variant": "premium" },
"source": { "kind": "catalog", "catalog": "checkout-redesign", "value": "premium" }
},
"default_value": { "variant": "control" },
"default_source": { "kind": "catalog", "catalog": "checkout-redesign", "value": "control" },
"rules": [ { "index": 0, "condition": "env.qualifier[\"premium-users\"]", "value": { } } ]
}
],
"qualifiers": []
}
```
A qualifier resolution is simpler - its `value` is just true or false:
```json
{
"package": "app-config",
"variables": [],
"qualifiers": [
{ "id": "premium-users", "when": "(context.user.tier == \"premium\")", "value": true }
]
}
```
The `source.kind` is `literal` for a plain value, `catalog` for a single catalog
entry, or `catalog_list` for a `list<catalog:...>` query result.
## diff - what changed, behaviorally
A file diff shows *what* changed in the TOML. `diff` shows what that change
*does* - which variable now picks a different value, which qualifier started
matching. The argument is a local path, because it works across git refs of that
checkout.
```sh
# working tree vs HEAD (the default)
rototo diff app-config --context @app-config/evaluation-contexts/request-samples/premium.json
# compare two committed states
rototo diff app-config --from origin/main --to HEAD --context @.../premium.json
# leave --to off to keep the "after" side as your working tree
rototo diff app-config --from origin/main
```
- **`--from <ref>`** - the "before" side. Defaults to `HEAD`.
- **`--to <ref>`** - the "after" side. Defaults to your current working tree.
- **`--context`** - the facts to report impact against. Use the same samples you
resolve with, so the diff stays grounded in a real case.
## fixtures - print ready-to-run resolve commands
`fixtures` generates readable examples of how your package resolves - as actual
`rototo resolve` commands you can run or paste into docs and reviews. It's a way
to turn "here's how this behaves" into something concrete.
```sh
rototo fixtures app-config --variables
rototo fixtures app-config --variable checkout-redesign --qualifiers
rototo fixtures app-config --variables --context-form json
```
Takes the variable and qualifier selectors. The one extra flag:
- **`--context-form path|json`** - how the printed context looks. `path` (the
default) breaks it into `--context a.b=value` arguments; `json` emits a single
`--context '<json>'`.
## package - build a distributable archive
`package` bundles the package into a deterministic, content-addressed `.tar.gz`
for production distribution - the artifact you upload to an object store. (Same
idea as the [package sources](./package-sources.md) and
[format](./package-format.md) pages describe.)
```sh
rototo package app-config # writes into the current directory
rototo package app-config -o ./dist # ...or somewhere else
```
- **`--output <dir>`** / **`-o`** - where to write the archive. Defaults to `.`.
The file is named by its own SHA-256 digest, so the same package always produces
the same file name and bytes.
## docs - read the bundled documentation
rototo ships its own docs inside the binary - these very pages - so you (and your
agent) can read them offline.
```sh
rototo docs # list the pages
rototo docs -p concepts # render a page by id prefix
rototo docs -s "refresh" # search pages with a regex
rototo docs --export ./site # export the whole thing as static HTML
```
- **`--page <prefix>`** / **`-p`** - render the page whose id starts with this.
- **`--search <regex>`** / **`-s`** - search across pages.
- **`--export [dir]`** - write the docs as a static HTML site (defaults to
`./site`).
(There are also `--package-readme`, `--out`, and `--docs-base-url` flags used by
the release tooling to generate SDK package READMEs from these docs.)
## setup - wire up your shell, editor, and agent
`setup` connects rototo to the tools around it: shell completions, editor
feedback through the language server, and guidance for your coding agent.
```sh
rototo setup # interactive - asks what to connect
rototo setup --all # connect everything it can
rototo setup --shell zsh
rototo setup --editor neovim
rototo setup --agent claude
```
- **`--all`** - set up every supported integration.
- **`--shell <shell>`** - `auto`, `bash`, `fish`, `zsh`, `elvish`, `powershell`,
or `none`.
- **`--editor <editor>`** - `all`, `neovim`, or `none`.
- **`--agent <agent>`** - `all`, `claude`, `codex`, or `none`. Agent guidance is
written into a clearly marked, managed block.
- **`--print`** - print the generated content instead of writing files.
- **`--dry-run`** - show planned changes without touching the filesystem.
- **`--force`** - overwrite rototo-owned generated files that already exist.
## console - the web UI
`console` serves the rototo console - a web UI plus a JSON API - from the same
binary, over a package.
```sh
rototo console --package app-config
rototo console --package app-config --bind 127.0.0.1:8080
```
The main flags:
- **`--package <source>`** - the package to open at startup.
- **`--bind <addr>`** - the address to listen on.
- **`--data-dir <dir>`** - where console state lives (also
`ROTOTO_CONSOLE_DATA_DIR`).
- **`--public-url <url>`** - the public origin, for running behind a reverse
proxy (also `ROTOTO_CONSOLE_PUBLIC_URL`).
- **`--state ephemeral|persistent`**, **`--deployment local|hosted`**,
**`--write disabled|pull-request|direct-push`** - control persistence,
deployment mode, and how edits are written back. Each has a sensible default
based on whether you opened a local folder or a remote source.
## lsp - the language server
`lsp` runs the rototo language server over stdin/stdout. You don't usually run
this by hand - `rototo setup` points your editor at it. It's what gives you
inline feedback and help while editing package files.
```sh
rototo lsp
```
No arguments.