⚡ gamma-ai

Create presentations, documents, webpages & social posts — right from your terminal.

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-ai?

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

Pattern	Usage
Blocking	gamma generate -i "quarterly review" -m generate # Waits ~30-60s, returns JSON with gammaUrl
Async	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://..."}
Preview	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.