# Sweeppea CLI

> The official Sweeppea command-line interface: a single fast native binary (built in Rust) for managing sweepstakes, participants, winners and more from the terminal. Run it with `npx @sweeppea/cli`. It talks to the Sweeppea REST API v3 and requires a Sweeppea API key tied to an active subscription.

Install with `npx @sweeppea/cli` or `npm install -g @sweeppea/cli`. The npm package ships a prebuilt binary per platform (Linux x64/arm64, macOS Intel/Apple Silicon, Windows x64) via optionalDependencies; npm installs only the matching one. Authenticate with `sweeppea auth login` (the key is validated against `/account/health-check`, stored in the OS keyring, and never logged). `SWEEPPEA_API_KEY` overrides the stored value for CI. Every command supports `--json`; destructive commands (`delete`, `winners draw`) confirm first and honor `--yes`.

## Getting an API key

1. Create an account at https://www.sweeppea.com
2. Choose a plan
3. Get the API key from https://app.sweeppea.com/api-dashboard (API Keys tab)
4. Run `sweeppea auth login`

## Command categories

- auth: login, logout, status
- account: health, profile, business, plan
- sweepstakes: list, create, update, clone, pause, unpause, delete
- participants: add, get, list, count, bonus, delete
- winners: draw, list, schedule, scheduled, unschedule
- groups: list, create, update, delete
- notes: list, get, create, update, delete
- calendar: list, get, create, update, delete
- rules: list, create, update, delete
- files: list, upload, url, send, delete
- billing: wallet, transactions, consumptions, datatransfer
- tickets: list, get, create, update, resolve, delete
- todos (admin only): list, create, update, delete
- invoices (module opt-in): list, get, create, update, delete
- surveys (module opt-in): list, get, create, update, delete, responses, report

The invoices and surveys modules are disabled by default on a Sweeppea account; until an administrator enables them, those commands answer 403.

## Documentation

- [CLI Documentation](https://clidocs.sweeppea.com/): This site — install, authentication, and the full command reference.
- [Full LLM Documentation](https://clidocs.sweeppea.com/llms-full.txt): Extended AI-readable documentation with every command, flag, and output shape.
- [MCP Server Documentation](https://mcpdocs.sweeppea.com/): The same platform for AI assistants — 71 MCP tools for Claude, Cursor, Windsurf, Gemini CLI and more.
- [REST API v3 Documentation](https://apidocs.sweeppea.com/): The HTTP endpoints the CLI and the MCP server both call, with a full OpenAPI specification.

## Links

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

## Agent Skill

An official skill for AI agents driving the CLI is published at
https://clidocs.sweeppea.com/skill/sweeppea-cli.zip (activation guide:
https://clidocs.sweeppea.com/skill/). It documents the full command surface, the API's pagination
and retry behaviour, and the US/Canada sweepstakes compliance rules that the CLI
does not enforce on its own (the MCP server enforces those server-side; the CLI
validates formats only).

Install: unzip it into `~/.claude/skills/`. The repository is private; the zip
on the docs site is the distribution channel.