The command-line reference is easier to read by sections than as one flat list: global options, root commands, managing external servers, the sandbox, the server worker and options of individual commands. That division mirrors the tool's design: some options apply to any run, others make sense only inside their own command. The difference is not cosmetic. A global option once written into a shell alias or an environment variable will apply to every run, including the ones you were not thinking about at the time. An option of a command stays where it is written, and is therefore safer.
This chapter gives a map of the most used rather than a complete list. The complete list for your build is always available through the built-in help - for the program itself and for each of its commands separately. That is not an excuse but a consequence of how the product works: some options appear and disappear with versions, some are marked advanced or hidden and are not shown in the general list, and a static list in a book goes stale faster than it is printed.
It helps to run your eyes over the option groups once so you know what exists at all. The global ones cover authentication, the output mode, continuing a session, choosing a model and a mode, autonomy, the sandbox, workspace trust, the working directory, plugins and trees. Root commands cover sign-in and status, listing models, external servers, the sandbox, the worker, the protocol mode, updates and working with sessions. Knowing the groups matters more than knowing the names: an exact name is clarified in a second, while help will not tell you that a capability exists at all - it is read once you already know what you are looking for.
Options with aliases and short forms deserve separate attention. They save typing, but in scripts the full form is better: six months later the reader of the script cares more about clarity than about saved characters. That is a general automation rule, but it is especially apt here - many short forms look alike and are easily confused, and some aliases are kept for compatibility with older names. A full name survives renames better than a short one and is easier to find with a search across the repository.
When working with the reference it helps to keep in mind the split between what affects boundaries and what affects convenience. Options for autonomy, the sandbox and trust belong to the first class: their values change what the agent can do. Options for output, the model and continuing a session belong to the second. The non-interactive print mode deserves separate remembering: it is meant for scripts, yet it has all the tools at its disposal, including writing files and running shell commands. On its own it restricts nothing, and its boundaries are set with the same options as for interactive work.
It helps to see a summary by group in full once. It is given below - with what each group does and what to watch for. You come back to this map when you need to understand where to look for an option: first determine the group, then check the exact syntax in the built-in help of your version.
| Group | What it covers | What to watch |
|---|---|---|
| Global options | The key and request headers, the output mode, continuing a session | They apply to any run, including scripts |
| Boundaries | Autonomy, the sandbox, workspace trust | These are the options that change what the agent can do |
| Work area | The working directory, trees, the base ref, skipping setup | They determine where the edits happen |
| Model and mode | Model selection, working modes, listing models | The catalog is discovered by request rather than from memory |
| Root commands | Sign-in, status, updates, sessions, rule generation | Some commands are marked advanced or hidden |
| External servers | Sign-in, listing, listing tools, enabling and disabling | Useful for diagnosing a missing tool |
| Sandbox | Enable, disable, reset, run a command in isolation | Separate options for paths and blocking patterns |
| Worker | Starting and debugging the server worker | A server component rather than a developer tool |
There is a short list of markers by which someone else's run demands a separate examination. Forcing commands through, waiving questions about workspace trust, enabling the network inside the sandbox, passing a file with a token, and registering a worker. Each of them widens the execution boundary rather than convenience, so in a script review they are read first - before working out what the script does at all. A practical technique: in team scripts such options are not buried in the general run line but pulled out into a separate variable with a telling name, so that they cannot be missed while reading.
It also helps to understand the applicability boundary of the two groups that are most often misread. Options for the working area and trees determine where exactly the edits land: a run in a separate tree creates an isolated checkout from the given base, and the edits do not mix with current work. The worker is not a developer tool at all: it is a server component that accepts work from the cloud and runs it in your environment, with its own authentication, labels and address for health checks. The first group changes the place where the work happens. The second changes who initiates that work.
The engineering conclusion is simple: the reference is a map and the built-in help is the source of truth. The book helps you understand the design and find the right place, but a specific option's name and behavior are always checked in your own build. That applies especially to options that remove restrictions: their behavior is refined from version to version, and the price of a mistake here is not cosmetic.
The typical failures are predictable. Copying an option from someone else's script without checking it in your version. Using short forms in automation and losing readability. Confusing boundary options with convenience options during review. Treating the non-interactive print mode as safe by default. And treating a static list in a book as exhaustive.