# Scheduler Zero CLI quickstart


This walkthrough connects the Scheduler Zero CLI to your account and reads campaign data. It does not launch, modify, or send a campaign. You need an account with access to at least one workspace; the CLI cannot exceed your current permissions.

## 1. Open browser consent

```bash
npx --yes @scheduler-zero/sz@latest auth login
```

On a remote machine or when you want to open the URL manually:

```bash
bunx @scheduler-zero/sz@latest auth login --no-browser
```

The terminal prints a URL, a confirmation code, and a waiting message. Open the link, sign in if needed, and verify that the browser's code matches the terminal. Choose an organization, selected workspaces or all current and future workspaces, and full or read-only permissions. For this walkthrough, selected workspaces with read-only access are enough when you hold campaign read permission there.

Opening the link does not authorize the CLI. Click **Authorize CLI** to confirm the access choices, or cancel to reject the request. The terminal receives the credential by polling the server; there is no localhost callback or listening port. Requests expire after ten minutes. See [browser login and consent](/cli/authentication) for the full flow.

If you already have a saved or environment-provided key, `auth login` validates that key instead of opening a fresh browser request. To change the consent grant, follow [switch accounts or change access](/cli/authentication).

## 2. Check authentication

```bash
npx --yes @scheduler-zero/sz@latest auth status
npx --yes @scheduler-zero/sz@latest whoami --json
```

Successful login stores the credential in your operating system's per-user config directory. You do not need to log in before every command. `auth status` checks the available credential against the API, so a revoked key can fail even when a local config file still exists.

`whoami` shows a representative visible **workspace**, not every workspace you can reach. In CLI 0.2.1 and later, that field is named `workspace`. Earlier versions labeled the same workspace `organization`; that was a legacy name, not a different parent organization. Use the next step for the full visible hierarchy.

## 3. Find organization and workspace IDs

```bash
npx --yes @scheduler-zero/sz@latest organizations list --json
npx --yes @scheduler-zero/sz@latest workspaces list --json
```

An **organization** is the parent; a **workspace** is where campaigns and other product data live. An unfiltered workspace list adds `organizationId` and `organizationName` to each workspace row. For example, multiple workspaces can all belong to the same organization:

```json
[
  {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "Outbound",
    "organizationId": "22222222-2222-4222-8222-222222222222",
    "organizationName": "Example Company"
  }
]
```

This is an illustrative subset of the response, not a complete schema. Copy a real workspace UUID from your result. Names and slugs are not accepted in place of `--workspace` IDs. Workspace visibility and operations remain subject to the key's restrictions intersected with your live permissions.

## 4. List campaigns in a workspace

Set your own ID locally:

```bash
WORKSPACE_ID="11111111-1111-4111-8111-111111111111"
npx --yes @scheduler-zero/sz@latest campaigns list \
  --workspace "$WORKSPACE_ID" \
  --status active \
  --limit 25 \
  --offset 0 \
  --json
```

Replace the example UUID. A workspace-scoped command needs `--workspace` unless browser login saved a default for one selected workspace. With multiple or all workspaces, pass the workspace explicitly. The returned campaign list is an object with `items` and pagination information; it is not a bare array. See [campaigns list](/cli/commands/campaigns-list) for all filters and pagination.

## 5. Read one campaign

Copy a campaign UUID from `items`, then run:

```bash
CAMPAIGN_ID="33333333-3333-4333-8333-333333333333"
npx --yes @scheduler-zero/sz@latest campaigns get "$CAMPAIGN_ID" \
  --workspace "$WORKSPACE_ID" \
  --json
```

The command requires both a campaign ID and a workspace context. A key that can see one workspace is not thereby authorized for a sibling workspace. Missing campaign read permission or inaccessible resources result in an error, not an automatic permission expansion.

## Next steps

- [CLI command reference](/cli/commands): every shipped command, option and underlying API operation.
- [Shell scripts and CI](/cli/scripting): JSON, exit codes, pagination and environment-provided credentials.
- [Authentication and key lifecycle](/cli/authentication): configuration, expiry, changing access and revocation.
- [REST API quickstart](/rest-api/quickstart) and [MCP tools](/mcp/tools): broader product operations beyond the CLI's current read commands.
- [Markdown and LLM-friendly docs](/markdown): copy this guide or fetch its text without browser rendering.