# Sweeppea CLI — full reference

The official Sweeppea command-line interface. A single native binary built in Rust (instant startup, no
runtime), distributed on npm as `@sweeppea/cli` and run with `npx @sweeppea/cli`. It is a third client over
the same Sweeppea REST API v3 that the MCP server (`renaissance-mcp`) wraps, and reaches full parity with the
MCP's resource categories.

## Install

- `npx @sweeppea/cli <command>` — run on demand.
- `npm install -g @sweeppea/cli` — installs the `sweeppea` command globally.
- The package ships a prebuilt binary per platform via optionalDependencies; npm installs only the one
  matching the user's OS/CPU. Supported: Linux x64, Linux arm64, macOS x64 (Intel), macOS arm64 (Apple
  Silicon), Windows x64.
- `sweeppea --version` → `sweeppea 0.9.0`.

## Authentication & pricing

The CLI requires a Sweeppea API key tied to an **active subscription**. Sweeppea handles the legal complexity
of running sweepstakes in the US/Canada (per-state registration, bonding, void-where-prohibited, prize
disclosure, compliant official rules, multi-state eligibility, entry limits, auditable participant/winner
records).

To get a key: create an account at https://www.sweeppea.com, choose a plan, and copy the key from the API
dashboard at https://app.sweeppea.com/api-dashboard (API Keys tab).

Store it with `sweeppea auth login` — the key is validated against `POST /account/health-check` before being
saved, stored in the OS keyring (Keychain on macOS, Credential Manager on Windows, a `0600` file on Linux),
and never logged. `SWEEPPEA_API_KEY` overrides the stored value (useful for CI).

## Global flags

- `--json` — machine-readable output (supported by every command).
- `--yes` / `-y` — skip confirmation prompts for destructive actions.
- `--api-base <URL>` — override the API base URL (advanced; HTTPS enforced except loopback).

Safety: destructive/irreversible actions (`sweepstakes delete`, `participants delete`, `winners draw`,
`groups delete`, `notes delete`, `calendar delete`, `rules delete`, `files delete`, `tickets delete`,
`todos delete`, `invoices delete`, `surveys delete`) prompt for confirmation, honor `--yes`, and abort
when there is no TTY and no `--yes`.

## Commands

### auth
- `auth login` — store your API key (hidden prompt; also reads stdin, e.g. `pbpaste | sweeppea auth login`).
- `auth logout` — remove stored credentials.
- `auth status` — show whether you are logged in and if the key is valid.

### account
- `account health` — verify credentials and connectivity.
- `account profile` — your user profile.
- `account business` — your business information.
- `account plan` — your active subscription plan.

### sweepstakes
- `sweepstakes list` — list sweepstakes (table or `--json`); archived hidden unless `--all`.
- `sweepstakes create --name --type <sms|email|social> --handler --start-date --end-date --start-time --end-time` — create.
- `sweepstakes update <token> [--name --start-date --end-date --start-time --end-time]` — partial update.
- `sweepstakes clone <handler> --new-handler --name --start-date --end-date --start-time --end-time` — clone.
- `sweepstakes pause <token>` / `unpause <token>` — pause or resume.
- `sweepstakes delete <token>` — permanent (confirms).

### participants
- `participants list <sweepstakes-token>` — paginated (`--page`, `--all`), with `--search` / date filters.
- `participants add <sweepstakes-token> --email/--phone --field "K=V" [--fields-json] [--bonus] [--lang]` — add one.
- `participants get <sweepstakes-token> --token/--email/--phone` — fetch one.
- `participants count <sweepstakes-token> [--filter-type all|participants|amoe|optouts]` — counts.
- `participants bonus <sweepstakes-token> <participant-token> <value>` — set bonus entries.
- `participants delete <sweepstakes-token> <participant-token>` — permanent (confirms).

### winners
- `winners draw <sweepstakes-token> --winners N [--group --completed-entries --include-opted-out --exclude-spam]` — immediate draw (confirms; irreversible).
- `winners list <sweepstakes-token>` — paginated (`--page`, `--items-per-page`, `--all`).
- `winners schedule <sweepstakes-token> --winners --date --time --timezone [--group --mode --notify --message ...]` — schedule a future drawing.
- `winners scheduled <sweepstakes-token>` — list scheduled drawings.
- `winners unschedule <sweepstakes-token> <schedule-token>` — delete a pending scheduled drawing (confirms).

### groups
- `groups list <sweepstakes-token>` — list groups.
- `groups create <sweepstakes-token> <name>` — create.
- `groups update <sweepstakes-token> <group-token> <name>` — rename.
- `groups delete <sweepstakes-token> <group-token>` — permanent (confirms).

### notes (account-level)
- `notes list` / `notes get <note-token>` — list or fetch.
- `notes create --title --note [--pinned]` — create.
- `notes update <note-token> [--title --note --pinned/--unpin]` — partial update.
- `notes delete <note-token>` — permanent (confirms).

### calendar (account-level)
- `calendar list` / `calendar get <event-token>` — list or fetch.
- `calendar create --title --start-date --end-date [--description --location --start-time --end-time --color --all-day --url]` — create.
- `calendar update <event-token> [...same optionals]` — partial update.
- `calendar delete <event-token>` — permanent (confirms).

### rules
- `rules list <sweepstakes-token>` — list official rules.
- `rules create <sweepstakes-token> --title (--content | --content-file)` — create a rules document.
- `rules update <sweepstakes-token> <rules-token> [--title --content/--content-file --abbreviated-shopify]` — partial update.
- `rules delete <sweepstakes-token> <rules-token>` — permanent (confirms).

### files (drive)
- `files list [--page --limit]` — list files with storage usage.
- `files upload <path> [--mime --public]` — upload (base64, max 10 MB; private by default).
- `files url <file-token> [--mode preview|download --expires <secs>]` — presigned URL.
- `files send <file-token> <recipient-email> [--subject --message]` — email a file.
- `files delete <file-token>` — permanent (confirms).

### billing (read-only)
- `billing wallet` — wallet transactions.
- `billing transactions` — billing transactions.
- `billing consumptions` — monthly/yearly consumption totals.
- `billing datatransfer <sweepstakes-token>` — data-transfer records.

### tickets (support)
- `tickets list [--closed --search --platform --priority --page]` — open (or `--closed`) tickets.
- `tickets get <case-number>` — full ticket details.
- `tickets create --title --description --priority <low|medium|high> [--assign-to]` — open a ticket.
- `tickets update <case-id> [--title --description]` — partial update.
- `tickets resolve <case-id>` — close a ticket.
- `tickets delete <case-id>` — permanent (confirms).

### todos (admin only)
- `todos list [--page --search --status --priority --resource --pinned]` — list to-dos.
- `todos create --title --priority [--description --resource --pin --deadline]` — create.
- `todos update <todo-token> [--title --description --priority --resource --pin --deadline --complete/--incomplete --completion]` — partial update.
- `todos delete <todo-token>` — permanent (confirms).

### invoices (module opt-in)

The Invoices module is disabled by default on an account; until an administrator
enables it, every command below answers 403. Subtotal, tax and total are always
computed server-side from the line items, so an `Amount` is never sent.

- `invoices list [--status <draft|pending|paid|cancelled> --from --to --page --limit]` — paginated
  list plus an account-wide summary (counts and totals per status).
- `invoices get <invoice-token> [--no-events --no-qr]` — full detail: recipient, items, payment,
  view statistics and the event timeline. `--no-qr` drops the base64 QR data URL, which dominates
  the `--json` output.
- `invoices create --to-name --to-email [--to-phone --to-company --to-address --to-city --to-state
  --to-zip --to-country --to-tax-id] (--item ... | --items-file <path|->) [--title --issue-date
  --due-date --discount --tax-rate --tax-label --payment-method <card|check|transfer>
  --payment-instructions --notes --terms --publish]` — a line item is `Description|Quantity|Rate`,
  repeatable; `--items-file` takes a JSON array (`-` reads stdin) and is the way in when a
  description contains a `|`. Creates a draft unless `--publish` is passed. Never emails the
  recipient. Maximum 60 line items.
- `invoices update <invoice-token> [--status <pending|cancelled> --title --issue-date --due-date
  --discount --tax-rate --tax-label --no-tax --payment-method --payment-instructions --notes
  --terms --item/--items-file --to-name --to-email …]` — partial update. `--status pending`
  publishes a draft, `--status cancelled` voids it; an invoice can never go back to draft, and a
  paid or cancelled one is immutable (409). `--item`/`--items-file` and the `--to-*` flags replace
  what is stored rather than merging into it.
- `invoices delete <invoice-token>` — permanent (confirms). Cancelling is usually what you want for
  an issued invoice; deleting keeps the wallet transaction and commission of a paid one.

### surveys (module opt-in)

The Surveys module is disabled by default on an account; until an administrator enables it, every
command below answers 403. A survey's `Status` is a boolean (enabled/disabled), not a string.

- `surveys list [--sweepstakes <token> --enabled/--disabled --archived/--active --page --limit]` —
  paginated list. The `State` column shows `enabled`/`disabled` plus `archived` and `locked`.
- `surveys get <survey-token>` — the survey plus its full question set, sorted by page then order.
- `surveys create --sweepstakes <token> --name [--questions-file <path|-> --settings-file <path|->
  --description --questions-per-page <1-5> --language <en|es> --disabled]` — all-or-nothing:
  nothing is written unless the whole payload validates. Limits: 5 questions per page, 50 pages,
  250 questions, 30 options per question. A question is
  `{"Page":1,"QuestionText":"…","FieldType":"…","Required":true,"Options":[{"Label":"…"}]}`;
  `FieldType` is one of text, textarea, radio, checkbox, select, slider, rating, nps, yesno, date.
  The individual flags override the matching keys of `--settings-file`.
- `surveys update <survey-token> [--name --enable/--disable --archive/--restore --questions-file
  --settings-file --description --questions-per-page --language]` — partial update.
  `--questions-file` replaces the whole question set and is rejected with 409 once the survey has
  collected a single response (the stored answers point at the question tokens it would destroy).
- `surveys responses <survey-token> [--completed/--abandoned --from --to --include-metadata --page
  --limit]` — individual responses, newest first, up to 100 per page. `--include-metadata` adds IP
  address, user agent and device details, which are personal data and left out by default.
- `surveys report <survey-token> [--timeline-days <1-365>]` — aggregated report: visits, starts,
  completion rate, completion times, devices, browsers, a daily timeline and per-question answer
  distributions (capped at the 25 most frequent answers per question). A survey with no traffic
  returns a report of zeros rather than an error.
- `surveys delete <survey-token>` — permanent (confirms). Takes the questions, responses,
  statistics and uploaded files with it.

## The Sweeppea developer ecosystem

Three clients, one platform, one API key. All of them talk to the Sweeppea REST API v3.

- CLI (this document) — https://clidocs.sweeppea.com/ · llms.txt: https://clidocs.sweeppea.com/llms.txt
- MCP server (71 tools for AI assistants) — https://mcpdocs.sweeppea.com/ · llms.txt: https://mcpdocs.sweeppea.com/llms.txt
- REST API v3 (HTTP endpoints + OpenAPI) — https://apidocs.sweeppea.com/ · OpenAPI: https://apidocs.sweeppea.com/openapi.json

## Links

- npm: https://www.npmjs.com/package/@sweeppea/cli
- Sweeppea: https://www.sweeppea.com

## Agent Skill

The official skill for AI agents operating this CLI is published at
https://clidocs.sweeppea.com/skill/sweeppea-cli.zip. Unzip it into
`~/.claude/skills/` (Claude Code, opencode), upload it to claude.ai or the
Claude API, or point an `AGENTS.md` at it for Codex, Cursor, Windsurf, Copilot
and Gemini CLI. Activation guide: https://clidocs.sweeppea.com/skill/

- `SKILL.md` — session start, the CLI's contract (exit codes, --json, tokens,
  pagination, concurrency), destructive-action handling, the pre-drawing
  checklist, and what the CLI cannot do.
- `references/commands.md` — every command and flag, generated from the binary.
- `references/compliance.md` — the US/Canada legal checklist, prohibited and
  restricted categories, state registration thresholds.
- `references/recipes.md` — export, audit, bulk load, CI, retry behaviour.

Key fact for any agent: the MCP server enforces legal guardrails server-side
(illegal lottery / COPPA / alcohol age gate) before a tool runs. The CLI does
not — it validates formats only. Entry-page settings (AMOE, age gate, official
rules consent checkbox) and the rules wizard are not reachable from the CLI;
route those to the MCP server or the web app.