Troubleshoot the Scheduler Zero CLI
Fix CLI package-resolution errors, browser-login timeouts, missing credentials, workspace access failures, and confusing JSON output.
# Troubleshoot the Scheduler Zero CLI
Start with the package version, effective credential and workspace list. These read-only commands distinguish installation, authentication and authorization problems without changing product data:
```bash
npx --yes @scheduler-zero/sz@latest --version
npx --yes @scheduler-zero/sz@latest auth status --json
npx --yes @scheduler-zero/sz@latest workspaces list --json
```
Do not paste API keys, config files, authentication factors or private session details into a bug report. Report the version, command with secrets removed, error message, and whether the issue occurs before or after consent.
## Package version not found
If `bunx` reports “No version matching” or npm reports `ETARGET` / `E404` for a newly released version, check the public registry:
```bash
npm view @scheduler-zero/sz version --prefer-online
npm view @scheduler-zero/sz versions --json --prefer-online
```
A successful publish can be followed by npm processing time before the version is downloadable. Verify that the desired version appears in the registry before retrying the package runner. Repeated publishing or creating another tag does not resolve that delay. If it is not a new release, verify the package name is scoped: `@scheduler-zero/sz`.
After a version is visible, request it explicitly, for example `bunx @scheduler-zero/sz@0.2.1 --version`. If a runner in the monorepo selects an unexpected executable, try the same command outside the repository. For npm, you can also explicitly select the package and executable:
```bash
npx --yes --package=@scheduler-zero/sz@0.2.1 sz --help
```
See [installation](/cli/installation) for global PATH setup and package-manager choices.
## Browser did not open
Open the printed URL manually, or use `auth login --no-browser`. A desktop opener is not required for SSH or containers. Keep the originating command running until you approve or cancel; starting a second command creates a different request and confirmation code.
If login returns immediately without printing a URL, a saved, environment or explicitly provided key may already be available. The CLI validates it instead of starting browser consent. Follow [change access](/cli/authentication) to request a fresh grant.
## Login expired, timed out or was canceled
Requests expire after ten minutes. Reopen login with a fresh request rather than reusing an old URL. Compare its new code before approving. A consumed or expired request cannot be redeemed again.
Cancellation on the consent screen is an expected denial, not a successful login. If the terminal was interrupted after approval, a key may already have been created; check **Settings → Personal → API keys** and revoke an unused key before retrying. Do not assume that interrupting a terminal revokes a credential.
Polling requires outbound access to the web app; credential validation requires access to the API. For a preview, check both `SCHEDULER_ZERO_APP_URL` and `SCHEDULER_ZERO_API_URL`. Rate-limited initiation asks you to retry later, and polling honors the server's retry delay. Do not start many concurrent login requests as a workaround.
## No API key found
Use browser login or supply `SCHEDULER_ZERO_API_KEY` from a secret manager. A saved file belongs to the current OS user and config directory; another shell, container, home directory or config override may not see it. `auth logout` deliberately removes that saved file.
If logout appears ineffective, an environment key can still override the absent local key. Unset it using your shell's syntax. For revoked or expired keys, obtain a new valid credential; a local file's existence does not prove validity.
## Workspace required or invalid UUID
`campaigns list` and `campaigns get` require a workspace UUID. If you authorized more than one workspace, pass `--workspace` explicitly. Copy the `id` from `workspaces list --json`; a slug such as `outbound` is not an ID.
Likewise, `campaigns get` requires a campaign UUID, and `workspaces list --organization` expects the parent organization's UUID. Invalid IDs are rejected locally before the corresponding API call.
## Access denied, not found or an unexpectedly short list
The key can only use its approved grants intersected with the owner's live authority. A workspace may be omitted or treated as not found rather than exposing data to an unauthorized credential. Check the grant in **Settings → Personal → API keys**, your current membership, the requested workspace, and the effective key source.
Full and read-only consent are different. A key with read permission can inspect campaigns but cannot thereby launch or modify them through the API/MCP. All-workspace access refers to workspaces in the approved parent organization, not every organization on the platform. To request wider access, create a new human-approved grant; retrying an operation does not widen the key.
## Why does whoami show only one workspace?
`whoami` is a credential summary with a representative visible workspace. It is not the workspace directory. Use `workspaces list --json` for all visible workspace rows and parent names. Versions through 0.2.0 labeled that representative workspace `organization`; update to 0.2.1 or later for the corrected `workspace` label.
An unfiltered workspace list contains `organizationId` and `organizationName`. With `--organization`, the CLI returns the underlying workspace rows without those added parent fields. Permission metadata alone is not a list of shipped CLI commands; use [the command reference](/cli/commands).
## JSON parsing or unexpected output shape
Add `--json` for scripts and check the exit code before parsing. Campaign lists are objects with `items`, whereas organization and workspace lists are arrays. Object responses remain JSON even in default table mode. Errors go to stderr as messages, not a guaranteed JSON envelope.
Older automation reading `whoami.organization` must migrate to `whoami.workspace` for CLI 0.2.1 and later. The REST API's legacy wire shape is separate from the CLI presentation. See [output and exit-code reference](/cli/reference) and [scripting recipes](/cli/scripting).
## Commands for publishing or sending are missing
The current CLI exposes authentication, organization/workspace discovery, and campaign reads. It does not currently implement campaign creation, launch, pause, sending, or npm release management. Those product operations are available where supported through the [authenticated REST API](/rest-api/reference) and [MCP tool catalog](/mcp/tools), with their own permissions and confirmation requirements.
For text-only troubleshooting, download [this guide as Markdown](/cli/troubleshooting.md) or [all CLI documentation](/cli/llms-full.txt).
Scheduler Zero