Loading CLI options, configuration and output
CLI options, configuration and output

Reference sz CLI flags, credential precedence, environment variables, JSON and table output, workspace defaults, and exit codes.
# CLI options, configuration and output


The CLI has common options plus command-specific filters. The [command reference](/cli/commands) is generated from the same hand-written metadata as `sz --help`; each command page lists the options documented for that command.

## Help and version

```bash
sz --help
sz help
sz auth login --help
sz campaigns list --help
sz --version
```

`--help` on a registered command prints that command's usage. `sz help` prints the overall command list. `--version` reports the package version. Neither help nor version requires authentication.

## Common options

| Option | Purpose |
| --- | --- |
| `--api-key <key>` | Override environment and saved credentials |
| `--base-url <url>` | Set the API origin |
| `--workspace <id>` | Workspace UUID for campaign commands; limits browser consent on login |
| `--organization <id>` | Limit `workspaces list` to a parent organization UUID |
| `--json` | Emit machine-readable JSON |
| `--format table\|json` | Select an output format explicitly |
| `-h`, `--help` | Show help |
| `-v`, `--version` | Show the package version |

Both `--option value` and `--option=value` syntax are supported for value options. `--workspace-id` and `--organization-id` are accepted aliases. Use UUIDs rather than display names or URL slugs. Unknown options and malformed required IDs result in a usage error.

`--no-browser` is a login option. Campaign list additionally supports `--search`, `--status`, `--limit`, and `--offset`; these do not become filters for other commands just because the argument parser recognizes them. Avoid passing options to commands that do not document them.

## Environment variables

| Variable | Meaning | Default |
| --- | --- | --- |
| `SCHEDULER_ZERO_API_KEY` | Personal API key for API requests | Saved key, if present |
| `SCHEDULER_ZERO_API_URL` | API origin | `https://api.schedulerzero.com` |
| `SCHEDULER_ZERO_APP_URL` | Web app used for browser login and polling | `https://app.schedulerzero.com` |
| `SCHEDULER_ZERO_CONFIG_DIR` | Directory containing `config.json` | OS-specific per-user directory |
| `XDG_CONFIG_HOME` | Linux config base directory | `~/.config` |
| `APPDATA` | Windows config base directory | User-profile roaming-data fallback |

There is no workspace environment variable in the current CLI. Use `--workspace` or the default saved by a single-workspace browser grant. `--organization` only filters a workspace-list request; it does not change credentials or create an ambient active organization.

## Precedence

| Setting | Highest to lowest priority |
| --- | --- |
| API key | `--api-key` → `SCHEDULER_ZERO_API_KEY` → saved `config.json` |
| API URL | `--base-url` → `SCHEDULER_ZERO_API_URL` → production API |
| Workspace | `--workspace` → saved workspace, when present |
| Browser-login origin | `SCHEDULER_ZERO_APP_URL` → production web app |

API and web-login origins are separate settings. An API-origin override alone does not move browser sign-in to a preview. Configure both origins consistently when deliberately using another environment.

## JSON and tables

Use `--json` in scripts. JSON shape depends on the operation: organization/workspace lists are arrays, campaign lists contain `items` and pagination, and identity/detail responses are objects. Empty list responses remain `[]` in JSON mode.

The default `table` format renders arrays as columns and prints `No results.` for empty arrays. Object responses, including identity and paginated campaign results, remain formatted JSON even in table mode. Nested array/object values in tables are serialized into cells; large permission lists can make a workspace table wide.

Successful command data goes to stdout. Login URLs, codes, waiting messages, and errors go to stderr, so a successful `--json` result can be redirected without mixing in login progress. The CLI does not print the API-key secret in its success output.

In 0.2.1 and later, the identity summary's representative workspace is `workspace`. The authenticated API retains the legacy `organization` wire field for this workspace; the CLI translates that presentation name. A representative workspace is neither the full access grant nor a command that selects future workspace context.

## Exit codes and error handling

| Code | Meaning |
| --- | --- |
| `0` | Command completed successfully, including help and version |
| `1` | API, network, login or configuration failure |
| `2` | CLI usage error, such as an unknown command, missing key/workspace or invalid UUID |

Shell interruption can produce shell-specific signal exit codes. An empty campaign list is not an error. Failures print a message to stderr rather than a guaranteed JSON error envelope, even when `--json` is selected. Check the process exit status before parsing stdout.

See [scripting examples](/cli/scripting) for safe shell patterns and [troubleshooting](/cli/troubleshooting) for auth, permission and registry errors. Agents can fetch [this reference as Markdown](/cli/reference.md) and the [CLI command catalog](/cli/catalog.json).