A CLI wrapper for the Gamma API — built for both humans and AI agents.

Bundled with an Agent Skill for automatic discovery by 30+ AI coding tools.

📟 Quick Start

npm install -g gamma-ai

# Store your API key (one-time)
gamma config set apiKey sk-gamma-xxxxx

Get your key at gamma.app/settings — requires Pro+ plan.

⚡ One-liner

gamma generate -i "5 trends in AI for 2026" -m generate

{
  "generationId": "abc",
  "status": "completed",
  "gammaUrl": "https://gamma.app/docs/xyz",
  "credits": { "deducted": 27, "remaining": 4130 }
}

That's it. One command → a full presentation with a shareable link.

🎯 Why gamma-cli?

| | | |---|---| | JSON output by default | Agents parse it directly, humans add --pretty | | 3 output formats | JSON · table · YAML | | Async workflows | --no-wait to fire-and-forget, status --wait to poll | | Input flexibility | Inline text · @filepath · pipe via stdin | | Local validation | Catches bad values before calling the API (saves credits) | | --dry-run | Preview what would be sent — zero credits spent | | --json-body | Raw JSON escape hatch for full API control | | --open | Auto-open result in browser | | Config persistence | gamma config set apiKey stores key securely | | Single dependency | Just commander — built with TypeScript + tsup |

📝 Usage

Generate content

# Simple presentation
gamma generate -i "Machine learning fundamentals" -m generate

# Full control
gamma generate \
  -i "Machine learning fundamentals" \
  -m generate \
  --type document \
  --amount detailed \
  --tone "professional and concise" \
  --audience "engineering managers" \
  --language es \
  --image-source aiGenerated \
  --image-style "minimalist flat illustrations" \
  --dimensions 16x9 \
  -n 8 \
  --export pdf \
  --open

From a file or stdin

gamma generate -i @research-notes.txt -m preserve

cat article.md | gamma generate -m condense -n 5

From a template

gamma template -g TEMPLATE_ID -p "Fill this sales deck with Q4 results"

Browse themes

gamma themes --all                    # all themes (JSON)
gamma --format table themes -l 5     # human-readable table
gamma themes -q "modern"             # search

Check status

gamma status GENERATION_ID            # one-time check
gamma status GENERATION_ID --wait     # poll until complete

Preview before spending credits

gamma generate -i "test" -m generate --type document --dry-run

{
  "dryRun": true,
  "method": "POST",
  "path": "/v1.0/generations",
  "body": { "inputText": "test", "textMode": "generate", "format": "document" }
}

🎨 Output Formats

gamma --format json themes       # JSON (default — best for agents)
gamma --format table themes      # aligned text table
gamma --format yaml themes       # YAML
gamma --pretty themes            # shorthand for --format table

📃 All Options

gamma generate

| Flag | Values | Description | |------|--------|-------------| | -i, --input | text, @file, - | Input content | | -m, --mode | generate · condense · preserve | How to process input | | --type | presentation · document · webpage · social | Content type | | -n, --num-cards | 1–75 | Number of cards | | -t, --theme | ID | Theme (from gamma themes) | | --amount | brief · medium · detailed · extensive | Text density | | --tone | string | Voice/mood | | --audience | string | Target audience | | --language | ISO code | Output language | | --image-source | aiGenerated · pexels · noImages ... | Image source | | --image-model | ID | AI image model | | --image-style | string | Style direction | | --dimensions | fluid · 16x9 · 4x3 · 1x1 ... | Aspect ratio | | --export | pdf · pptx | Export format | | --email | addresses | Share via email | | --json-body | JSON | Raw API body | | --no-wait | — | Return ID immediately | | --open | — | Open in browser | | --dry-run | — | Preview without sending |

gamma template

| Flag | Values | Description | |------|--------|-------------| | -g, --gamma-id | ID | Template ID (required) | | -p, --prompt | text, @file | Content prompt | | -t, --theme | ID | Override template theme | | --export | pdf · pptx | Export format | | --image-style | string | Image style | | --open | — | Open in browser |

gamma config

gamma config set <key> <value>    # set a value
gamma config get <key>            # read a value
gamma config delete <key>         # remove a value
gamma config list                 # show all config

🛡️ Input Validation

Bad values are caught locally before hitting the API — saves credits, gives instant feedback:

$ gamma generate -i "test" --mode badvalue

{
  "error": "Invalid value for mode: \"badvalue\"",
  "allowed": ["generate", "condense", "preserve"],
  "suggestion": "Use one of: generate, condense, preserve"
}

🤖 Agent Skill

This repo ships with an Agent Skill at skills/gamma/SKILL.md — compatible with 30+ AI coding tools including Claude Code, Cursor, Windsurf, and Copilot.

Install the skill

# Built-in (after npm install -g gamma-ai)
gamma skill --install claude          # → ~/.claude/skills/gamma/SKILL.md
gamma skill --install cursor          # → .cursor/skills/gamma/SKILL.md
gamma skill --install windsurf        # → .windsurf/skills/gamma/SKILL.md
gamma skill --install aios            # → .aios/skills/gamma/SKILL.md

# Or via skills.sh
npx skills add ibbybuilds/gamma-cli

# Or read it inline (agents can pipe this)
gamma skill

Agent workflow patterns

gamma generate -i "quarterly review" -m generate
# Waits ~30-60s, returns JSON with gammaUrl

gamma generate -i "quarterly review" -m generate --no-wait
# {"generationId":"abc","status":"submitted"}

# ... agent does other work ...

gamma status abc --wait
# {"status":"completed","gammaUrl":"https://..."}

gamma generate -i "test" -m generate --dry-run
# Zero credits spent

Why CLI over MCP?

| | CLI | MCP | |---|---|---| | Schema tokens | 0 | 28,000+ | | Training data | Billions of CLI examples | Custom schemas | | Composability | Pipes, files, chaining | Single tool calls | | Error handling | Exit codes + JSON | Protocol errors | | Async | --no-wait + status | Requires session |

🔌 API Coverage

| Endpoint | Command | Status | |----------|---------|--------| | POST /v1.0/generations | gamma generate | ✅ | | POST /v1.0/generations/from-template | gamma template | ✅ | | GET /v1.0/generations/{id} | gamma status | ✅ | | GET /v1.0/themes | gamma themes | ✅ | | GET /v1.0/folders | gamma folders | ✅ |

100% of the Gamma API is covered.

🛠️ Development

git clone https://github.com/ibbybuilds/gamma-cli
cd gamma-cli
npm install
npm run build         # tsup → dist/cli.js
npm run typecheck     # tsc --noEmit
npm test              # build + 13 tests
npm run dev           # tsup --watch
npm link              # global `gamma` command

📄 License

MIT — do whatever you want.

Built for humans and AI agents.