# 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.10.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`, `codes delete`, `codes unassign`, `codes redeem`,
`codes send`, `messaging send`, `messaging resume`, `messaging cancel`, `messaging unsuppress`) prompt
for confirmation, honor `--yes`, and abort when there is no TTY and no `--yes`. The two `send`
commands queue a real message that cannot be recalled.

## 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.

### codes (writes need the Codes & Coupons module)

Coupon codes of a sweepstakes. Every read works on any account; writes answer 403 until the Codes &
Coupons module is enabled, with the API's own explanation. A code is 1-20 letters, digits, `-` or
`_`, matched exactly and case-sensitively; its status is `not-redeemed`, `redeemed` or `voided`.
Per sweepstakes: at most 50,000 new codes per rolling 24 hours (create + generate combined) and
1,000,000 in total.

- `codes stats <sweepstakes-token>` — total, assigned, unassigned, redeemed, voided and available.
- `codes list <sweepstakes-token> [--status <all|assigned|unassigned|redeemed|not-redeemed|voided|available>
  --search --sort <code|expiration|status|created|redeemed> --desc --include-participant --page
  --limit <1-500>]` — one page, filtered and sorted on the server. `available` = neither assigned nor
  redeemed. The holder's email is personal data: the table shows only whether a code is held unless
  `--include-participant` is passed (`--json` always carries the full record).
- `codes get <coupon-token>` or `codes get --code <CODE> --sweepstakes <token>` — one code, by token or
  by the code a customer presents.
- `codes create <sweepstakes-token> (--code <CODE>... | --codes-file <path|->) [--description --value
  --url <https://…> --expires <YYYY-MM-DD> --expires-time <HH:MM>]` — import 1-1,000 codes you already
  have. The file is a JSON array or one code per line. Duplicates and invalid codes are reported
  back in `Duplicates` / `Invalid` and not inserted; the valid ones are.
- `codes generate <sweepstakes-token> --quantity <1-5000> --length <4-20> [--type <alphanumeric|numeric>
  --case <upper|lower|mixed> --prefix --suffix --description --value --url --expires
  --expires-time]` — random unique codes. Prefix + length + suffix must not exceed 20.
- `codes update <coupon-token> [--code --description --value --url --expires --expires-time --clear
  <description|value|url|expires|expires-time>...]` — partial update. `--clear` sends `null`, which
  removes the attribute. The code itself can be renamed only while unassigned and not redeemed.
- `codes delete (<coupon-token>... | --tokens-file <path|->)` — permanent (confirms), 1-1,000 per
  call. Assigned, redeemed and voided codes are skipped and listed in `Skipped`, never deleted.
- `codes assign <coupon-token> --participant <token>` — give an available code to a participant
  (regular or AMOE) of the same sweepstakes who holds none.
- `codes unassign <coupon-token>` — take it back (confirms); any redemption is cleared with it.
- `codes redeem (<coupon-token> | --code <CODE> --sweepstakes <token>)` — mark redeemed, exactly once
  (confirms). A second redeem answers 409. Voided codes are never redeemable.
- `codes unredeem <coupon-token>` — reverse a redemption made by mistake; the assignment is kept.
- `codes settings <sweepstakes-token>` — how the entry and AMOE pages hand out codes.
- `codes configure <sweepstakes-token> [--entry-page/--amoe-page <none|assign|generate|ask>
  --when-exhausted <nothing|generate> --code-type <numeric|alphanumeric> --code-length <4-20>
  --show-on-confirmation/--hide-on-confirmation --email-code/--no-email-code --sms-code/--no-sms-code
  --reject-invalid/--accept-invalid --case-sensitive/--case-insensitive --invalid-code-message
  --field-label --thank-you-message --clear <invalid-code-message|field-label|thank-you-message>...]`
  — partial update. The API stores the page modes and code type as integers; the CLI takes names.
- `codes send <coupon-token> --channel <email|sms|both> [--idempotency-key <8-64 chars>]` — queue the
  code to the participant who holds it (confirms). Real message; cannot be recalled. The result lists
  each channel's status: a channel can come back `skipped` (e.g. no valid phone number) while the call
  succeeds.

### messaging (writes need the Send Message module)

Email and SMS campaigns, the account's do-not-contact list and direct messages. **Campaigns are
created, reviewed and launched only in the Sweeppea app**; the CLI reads, pauses, resumes and cancels
them. Reads work on any account. A direct send can be refused for five reasons — module off, direct
messages not enabled, channel not in the plan, sending paused, or no SMS sender (10DLC) number —
and `messaging usage` is the command that tells them apart.

- `messaging usage` — module access, direct-message access, and per channel: included in plan, this
  month's used / reserved / remaining allowance, sending pauses and SMS sender readiness.
- `messaging campaigns [--sweepstakes --channel <email|sms> --category <marketing|transactional|referral>
  --status <draft|scheduled|queued|sending|paused|completed|cancelled|failed|blocked> --search
  --archived --page --limit <1-100>]` — newest first. The `Allowed` column shows which of pause /
  resume / cancel the API would accept now.
- `messaging campaign <campaign-token>` — one campaign in full: content, audience, sender, counters
  and allowed actions.
- `messaging report <campaign-token>` — counters, rates over sent, exclusions (no consent,
  suppressed, invalid, capped, duplicate, non-US/CA number, not first-party, over quota), top error
  codes and most-clicked links.
- `messaging recipients <campaign-token> [--status --search <exact address> --page --limit <1-100>]`
  — who a campaign went to and what happened to each message.
- `messaging pause <campaign-token>` — stop a queued or sending campaign; the held allowance stays
  held for a resume.
- `messaging resume <campaign-token>` — resume a paused campaign (confirms).
- `messaging cancel <campaign-token>` — cancel an unfinished campaign and release its allowance
  (confirms). Cannot be undone; `pause` is the reversible option. An illegal transition answers 409.
- `messaging suppressions [--channel --search <exact address> --page --limit <1-100>]` — every address
  that unsubscribed, replied STOP, complained, bounced or was added by hand.
- `messaging suppress --channel <email|sms> (--address <ADDRESS>... | --addresses-file <path|->)` —
  add 1-500 addresses. Idempotent; never downgrades an existing opt-out. Phones in E.164 or 10-digit
  US/CA form.
- `messaging unsuppress --channel <email|sms> (--address <ADDRESS> | --hash <AddressHash>)` — remove
  one address added by hand (confirms). A recipient's own opt-out (`Reason` other than `manual`) is
  never removable.
- `messaging send --participant <token> --channel <email|sms|both> (--message <text> | --message-file
  <path|->) [--subject --idempotency-key]` — queue one message to one participant (confirms). There is
  no address field: the recipient is always a participant of the account. Max 5,000 characters, 1,600
  by SMS. Limits: 200 sends per API key and 3 per recipient every 24 hours. Delivery is asynchronous
  (about a minute; SMS outside quiet hours) and the result lists each channel's status.

## 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 (109 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.