❯ sweeppea cli

Official Sweeppea CLI · Agent Skill

Teach your agent
to run sweepstakes.

Download the skill →

A skill is a folder of markdown an agent reads on demand. This one gives it the whole CLI — every command, how the API behaves under load, and the US and Canada compliance rules the CLI does not enforce by itself.

#

Why it exists

The short version: the CLI has no legal guardrails, and the MCP server does.

The Sweeppea MCP server enforces three rules server-side, before any tool runs. It refuses illegal lotteries — entry that requires a purchase with no free alternate method — it refuses an age minimum under 13, and it refuses an alcohol promotion without a 21+ age gate. Those checks fail closed: if the check itself errors, the tool is still blocked.

The CLI has none of them. Its validation covers formats: that an email looks like an email, that a handler is A-Z0-9_, that a date parses. Nothing in it knows what an AMOE is, and nothing stops sweeppea winners draw against a campaign with no official rules.

So when a task moves from the MCP to the CLI, the safety net does not come along. This skill is what puts it back — the agent becomes the guardrail, and it knows what to check.

Before a drawing

Rules exist? Entry period over? Enough entrants? And the one the CLI cannot see: does entry involve a purchase without an AMOE?

Before a delete

Eleven commands cannot be undone. The skill has the agent explain what disappears and get an explicit yes for that specific target.

#

Activation

Three mechanisms, depending on what your agent supports. Pick the row that matches your tool.

1 · Native skill directory

The format loads as designed: only the name and description sit in context until the skill is needed, and the reference files load one at a time when a task calls for them.

Claude Code

Download and unzip. It is picked up on the next session — no config, no restart flag.

$ curl -sL https://clidocs.sweeppea.com/skill/sweeppea-cli.zip -o skill.zip
$ unzip -q skill.zip -d ~/.claude/skills/   # every project
$ unzip -q skill.zip -d .claude/skills/    # just this one

Verify with /skills — sweeppea-cli should be listed.

opencode

Reads ~/.claude/skills/ for Claude Code compatibility, so the install above covers it too. Nothing further to do.

If skills are disabled in your setup, check that OPENCODE_DISABLE_CLAUDE_CODE_SKILLS is not set.

2 · Upload

Skills do not sync between surfaces — one uploaded to claude.ai is not available in the API, and neither sees the Claude Code copy. Upload wherever you need it.

claude.ai

  1. Download sweeppea-cli.zip
  2. Open Settings → Features and upload it under Skills
  3. Requires a plan with code execution enabled. Skills there are per user, not shared across your team

Claude API / Agent SDK

Upload through the Skills API, then reference the returned skill_id in the container parameter alongside the code execution tool. Uploaded skills are workspace-wide.

$ curl https://api.anthropic.com/v1/skills \
    -H "anthropic-beta: skills-2025-10-02" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -F "file=@sweeppea-cli.zip"

Note the API sandbox has no network access, so the agent cannot call the Sweeppea API from inside it. Use this surface for reasoning about the CLI, not for running it.

3 · AGENTS.md

Everything else reads AGENTS.md — Codex, Cursor, Windsurf, GitHub Copilot, Gemini CLI, Zed, VS Code, JetBrains Junie and a dozen more. You do not copy the skill into each one; you point at it once, in the repository where you run the CLI.

Any AGENTS.md tool

Unzip the skill into the repository where you run the CLI, then add the pointer at the root. The nearest AGENTS.md in the tree wins, so a subdirectory can narrow it further.

$ curl -sL https://clidocs.sweeppea.com/skill/sweeppea-cli.zip -o skill.zip
$ unzip -q skill.zip -d .   # -> ./sweeppea-cli/
# AGENTS.md
## Sweeppea

This repo uses the Sweeppea CLI. Before any task involving sweepstakes,
entrants, prize drawings or the `sweeppea` command, read
`sweeppea-cli/SKILL.md` and follow it.

It matters because the CLI has no legal guardrails: it will draw winners
on a campaign with no official rules. The skill carries the checks.

Load the reference files only when the task needs them — sweeppea-cli/references/commands.md for flags, sweeppea-cli/references/compliance.md before creating a sweepstakes or drawing.

Cursor

AGENTS.md works as-is. For the native path use .cursor/rules/*.mdc with description set, so the agent pulls it in when a request is relevant.

Windsurf

AGENTS.md at the root is always-on. Native equivalent: .windsurf/rules/*.md with trigger: model_decision.

GitHub Copilot

Reads AGENTS.md anywhere in the tree, and .github/copilot-instructions.md repository-wide.

Codex · Gemini CLI

AGENTS.md at the repository root. Gemini CLI also accepts GEMINI.md.

The tradeoff: the native format loads reference files on demand, so a simple "list my sweepstakes" never pulls in the legal appendix. With AGENTS.md you are giving the agent a pointer and trusting it to follow. In practice it does — but if your tool supports the native format, prefer it.

#

What is inside

Four files. SKILL.md loads when the skill triggers; the references load only when a task calls for them.

SKILL.mdSession 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.mdEvery command and flag, by category — generated from sweeppea <category> --help on the real binary, so it cannot disagree with what you run.
references/compliance.mdThe US and Canada checklist: official rules, AMOE, age gates, state registration thresholds, prohibited and restricted categories.
references/recipes.mdWorked pipelines — export winners, audit every campaign, bulk load from CSV, run in CI, and how retry and gateway errors behave.

What it cannot do

Entry-page settings and the official-rules wizard are not reachable from the CLI, and those are where AMOE, the age gate and the rules consent checkbox live. The skill says so and routes the task to the MCP server or the web app instead of approximating it.

Kept honest

The command reference is generated, not written. Pagination sizes, retry policy, file limits and the exact gap between the CLI and the MCP were each checked against the source of both projects.

#

The Sweeppea developer ecosystem

Three ways to drive the same platform. All of them speak to the Sweeppea API v3 and use the same API key.

❯ CLI

A native binary for your shell and CI. Scriptable, --json everywhere.

clidocs.sweeppea.com

◆ MCP Server

71 tools for AI assistants — Claude, Cursor, Windsurf, Gemini CLI and more.

mcpdocs.sweeppea.com ↗

▮ REST API v3

The HTTP endpoints underneath it all, with a full OpenAPI specification.

apidocs.sweeppea.com ↗