@chowderr/gamma-cli

Terminal client for Gamma API — create AI-powered presentations, documents, social posts, and webpages from the command line.

Wraps @chowderr/gamma-sdk so every Gamma endpoint that has a CLI surface here is backed by a real API call — no stubs.

Install

npm install -g @chowderr/gamma-cli

Or run ad-hoc without installing:

npx @chowderr/gamma-cli generate "five tips for productivity"

Requires Node.js >= 18.

Quick start

Get an API key from https://gamma.app/settings/api.
Save it to your local config:
```
gamma config init
```

Generate something:

gamma generate "five tips for productivity"

The CLI polls until generation completes (about 30–90 seconds) and prints the Gamma URL, PDF URL, and credits used.

Authentication

The CLI resolves your API key in this order:

GAMMA_API_KEY environment variable (highest precedence)
api_key field in the YAML config file
Fail with a clear error message

Config file location

gamma config init writes a YAML file at a platform-appropriate path:

Platform	Path
Windows	`%APPDATA%\gamma-cli\config.yaml`
macOS	`~/Library/Application Support/gamma-cli/config.yaml`
Linux	`$XDG_CONFIG_HOME/gamma-cli/config.yaml` (or `~/.config/gamma-cli/config.yaml`)

The file is created with mode 0600 (owner read/write only) so the API key is not world-readable.

Override the path per-invocation with -c <path> / --config <path>.

Example config file:

api_key: gamma_sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Commands

Command	What it does
`gamma generate <prompt>`	Generate a presentation, document, social post, or webpage from a text prompt
`gamma generate-from-template <gamma-id> <prompt>`	Generate from an existing gamma used as a template (beta)
`gamma status <generation-id>`	Check progress for a previously kicked-off generation
`gamma themes list`	List available themes (custom + built-in)
`gamma folders list`	List folders you can save generations into
`gamma config init`	Interactive setup — write API key to the config file
`gamma config show`	Show the resolved config (API key always masked)

`gamma generate <prompt>`

Generate a presentation, document, social post, or webpage from a text prompt.

Usage: gamma generate [options] [prompt]

Arguments:
  prompt                            Text prompt (use "-" to read from stdin)

Options:
  --from-file <path>                Read prompt from a file
  --type <type>                     Output type: slides, document, social,
                                    webpage (default: "slides")
  --text-mode <mode>                Text handling: generate, condense, preserve
                                    (default: "generate")
  --theme <id>                      Theme UUID
  --folder <id>                     Save to folder UUID (repeatable)
  --language <code>                 Output language code
  --cards <n>                       Number of cards/slides (1-75) (default: "10")
  --additional-instructions <text>  Additional AI instructions
  --text-amount <amount>            Text density: brief, medium, detailed,
                                    extensive
  --tone <text>                     Text tone/voice (<=500 chars)
  --audience <text>                 Target audience description (<=500 chars)
  --image-source <source>           Image source enum (e.g. aiGenerated, pexels,
                                    noImages)
  --image-model <model>             AI image model (when --image-source=aiGenerated)
  --image-style <text>              Artistic style for AI images (<=500 chars)
  --dimensions <value>              Card dimensions (format-dependent)
  --card-split <mode>               Card splitting: auto or inputTextBreaks
  --header-footer <json>            Header/footer config as JSON
  --export-as <format>              Export format: pdf or pptx
  --workspace-access <level>        Workspace access: noAccess, view, comment,
                                    edit, fullAccess
  --external-access <level>         External access: noAccess, view, comment, edit
  --share-email <addr>              Email to share with (repeatable)
  --share-access <level>            Access for --share-email recipients: view,
                                    comment, edit, fullAccess
  --timeout <seconds>               Polling timeout in seconds (default: "600")
  --wait                            Wait for generation to complete (default)
  --no-wait                         Return generation ID immediately without waiting

Prompt input

The prompt argument accepts a literal string. To pass long input use either:

--from-file <path> — read the prompt from a file (the positional prompt is then ignored)
Pass - as the prompt and pipe content on stdin: cat brief.md | gamma generate -

Prompts must be between 1 and 400,000 characters.

Text controls

Flag	Effect
`--text-mode`	`generate` (default) — treat the prompt as an instruction. `condense` — shorten the source text. `preserve` — keep the source text verbatim.
`--text-amount`	Density of generated text per card: `brief`, `medium`, `detailed`, `extensive`.
`--tone`	Free-text tone/voice direction, up to 500 characters (e.g. `"confident, data-driven"`).
`--audience`	Free-text target audience, up to 500 characters (e.g. `"technical founders"`).

Image controls

Flag	Effect
`--image-source`	Image source enum (e.g. `aiGenerated`, `pexels`, `noImages`).
`--image-model`	AI image model — only used when `--image-source=aiGenerated`.
`--image-style`	Artistic style direction for AI-generated images, up to 500 characters.

Card controls

Flag	Effect
`--cards`	Number of cards/slides, 1–75 (default `10`).
`--dimensions`	Card dimensions — values are format-dependent: presentations accept `fluid`, `16x9`, `4x3`; documents accept `fluid`, `pageless`, `letter`, `a4`; social posts accept `1x1`, `4x5`, `9x16`. Rejected when `--type=webpage`.
`--card-split`	`auto` (default behavior) or `inputTextBreaks` to honor blank-line breaks in the source.

Export

Flag	Effect
`--export-as`	Also export to `pdf` or `pptx`. The export URL is included in the final output alongside `gammaUrl`.

Sharing

Flag	Effect
`--workspace-access`	Workspace-wide access level: `noAccess`, `view`, `comment`, `edit`, `fullAccess`.
`--external-access`	Public/external-link access level: `noAccess`, `view`, `comment`, `edit`.
`--share-email`	Email to share the gamma with. Repeatable for multiple recipients.
`--share-access`	Access level applied to every `--share-email` recipient: `view`, `comment`, `edit`, `fullAccess`.

Advanced

Flag	Effect
`--header-footer <json>`	Raw JSON object matching the SDK's `HeaderFooterOptions` (e.g. `'{"header":{"text":"Acme"}}'`). Rejected when `--type=webpage`.
`--folder <id>`	Save the generation into a folder UUID. Repeatable to file it into multiple folders.
`--timeout <seconds>`	Max time to wait when polling for completion (default `600`). Only meaningful when `--wait` is set (which it is by default).
`--wait` / `--no-wait`	Block until completion (default) or print the generation ID immediately.

Example:

gamma generate "Q4 strategy review for a fintech startup" \
  --type slides \
  --cards 15 \
  --theme 2c3a4b5c-6d7e-8f90-1234-567890abcdef \
  --text-amount detailed \
  --tone "confident, data-driven" \
  --audience "early-stage investors" \
  --image-source aiGenerated \
  --image-style "minimal editorial photography" \
  --dimensions 16x9 \
  --export-as pdf \
  --additional-instructions "Open with a one-slide TL;DR."

With --no-wait, the command prints the generation ID immediately so you can poll later with gamma status.

`gamma generate-from-template <gamma-id> <prompt>`

Generate a new gamma from an existing gamma used as a template (beta). The template's structure, layout, and theme are reused; only the content is regenerated from the prompt.

Usage: gamma generate-from-template [options] <gamma-id> [prompt]

Arguments:
  gamma-id                    Template gamma ID (e.g. g_abcdef123456)
  prompt                      Text prompt (use "-" to read from stdin)

Options:
  --from-file <path>          Read prompt from a file
  --theme <id>                Override the template theme
  --folder <id>               Save to folder UUID (repeatable)
  --export-as <format>        Export format: pdf or pptx
  --image-model <model>       AI image model (only used if template uses AI
                              images)
  --image-style <text>        Artistic style for AI images (<=500 chars)
  --workspace-access <level>  Workspace access: noAccess, view, comment, edit,
                              fullAccess
  --external-access <level>   External access: noAccess, view, comment, edit
  --share-email <addr>        Email to share with (repeatable)
  --share-access <level>      Access for --share-email recipients: view,
                              comment, edit, fullAccess
  --timeout <seconds>         Polling timeout in seconds (default: "600")
  --wait                      Wait for generation to complete (default)
  --no-wait                   Return generation ID immediately without waiting

The prompt argument accepts the same --from-file <path> and - (stdin) inputs as gamma generate.

Example:

gamma generate-from-template g_template123abc \
  "Weekly product update for the engineering team — week of May 19" \
  --folder 11111111-2222-3333-4444-555555555555 \
  --export-as pdf \
  --share-email teamlead@example.com \
  --share-access view

`gamma status <generation-id>`

Check generation progress.

Usage: gamma status [options] <generation-id>

Arguments:
  generation-id        Generation ID to check

Options:
  --wait               Poll until complete (default: false)
  --timeout <seconds>  Polling timeout in seconds (only with --wait) (default: "600")

Example:

gamma status gen_abc123
gamma status gen_abc123 --wait
gamma status gen_abc123 --wait --timeout 1200

`gamma themes list`

List available themes (custom + built-in).

Usage: gamma themes list [options]

Options:
  --query <text>    Search themes by name
  --limit <n>       Max results (default: "25")
  --all             Fetch every page until exhausted (ignores --limit)
  --cursor <token>  Start from a specific pagination cursor

Pass --all to auto-paginate every page (useful for piping into jq); pass --cursor <token> to resume from a known cursor returned by an earlier call.

Example:

gamma themes list --query dark --limit 10
gamma themes list --all --json | jq 'length'

`gamma folders list`

List folders you can save generations into.

Usage: gamma folders list [options]

Options:
  --query <text>    Search folders by name
  --limit <n>       Max results (default: "25")
  --all             Fetch every page until exhausted (ignores --limit)
  --cursor <token>  Start from a specific pagination cursor

Example:

gamma folders list --query "Q4"
gamma folders list --all --json | jq -r '.[].id'

`gamma config init`

Interactive setup — prompts for your API key and saves it to the config file (mode 0600).

gamma config init

`gamma config show`

Show the resolved config. The API key is masked unless --json is passed (and even then only its source is shown, never the raw value).

gamma config show
gamma config show --json

Global options

These work on every command:

Option	Description
`--json`	Emit machine-parseable JSON instead of human text
`-v`, `--verbose`	Verbose output (request details, poll counts)
`-q`, `--quiet`	Suppress non-essential output
`--no-color`	Disable ANSI color codes
`-c`, `--config <path>`	Use a specific config file path
`-V`, `--version`	Print CLI version
`-h`, `--help`	Print help for any command

JSON output

Pass --json to any command to get a stable, machine-parseable shape suitable for piping into jq, scripts, or LLM tool-use:

gamma generate "Intro to vector databases" --json | jq '.gammaUrl'

For introspection — for example to teach an LLM the command surface — dump the full Commander schema:

gamma --help-json

This emits a JSON tree of every command, argument, option, and default. It is intended specifically for LLM tool-calling and code generation.

Exit codes

Code	Meaning
`0`	Success
`1`	Error (validation failure, API error, timeout, missing API key, etc.)

Errors are written to stderr; successful output goes to stdout, so you can pipe safely.

Examples

Generate a deck and save it directly to a folder

FOLDER_ID=$(gamma folders list --query "Client Decks" --json | jq -r '.[0].id')

gamma generate "Acme Corp onboarding deck" \
  --type slides \
  --cards 12 \
  --folder "$FOLDER_ID"

Generate from a long brief stored in a file

gamma generate --from-file brief.md \
  --type document \
  --text-mode preserve \
  --additional-instructions "Keep the original structure and headings."

You can also pipe the brief on stdin by passing - as the prompt:

cat brief.md | gamma generate - \
  --type document \
  --text-mode preserve

--text-mode preserve keeps the source text intact; condense shortens it; generate (default) treats the prompt as an instruction.

Generate from an existing template

gamma generate-from-template g_template123abc \
  "Weekly engineering update — week of May 19" \
  --export-as pdf

Kick off a long job, poll it from another shell

Shell A:

GEN_ID=$(gamma generate "Comprehensive guide to event-driven architecture" \
  --cards 50 \
  --no-wait \
  --json | jq -r '.generationId')

echo "$GEN_ID" > /tmp/gamma-job

Shell B:

gamma status "$(cat /tmp/gamma-job)" --wait --timeout 1800

Auto-paginate every theme

gamma themes list --all --json | jq -r '.[] | "\(.id)\t\(.name)"'

Pipe a list of prompts into Gamma

while read -r prompt; do
  gamma generate "$prompt" --json --quiet | jq -r '.gammaUrl'
done < prompts.txt

Share a generation with reviewers as you create it

gamma generate "Series A pitch — Acme Robotics" \
  --type slides \
  --cards 14 \
  --share-email reviewer1@example.com \
  --share-email reviewer2@example.com \
  --share-access comment \
  --external-access noAccess

License

MIT © chowderr

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.beads		.beads
.github/workflows		.github/workflows
e2e		e2e
src		src
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

@chowderr/gamma-cli

Install

Quick start

Authentication

Config file location

Commands

`gamma generate <prompt>`

Prompt input

Text controls

Image controls

Card controls

Export

Sharing

Advanced

`gamma generate-from-template <gamma-id> <prompt>`

`gamma status <generation-id>`

`gamma themes list`

`gamma folders list`

`gamma config init`

`gamma config show`

Global options

JSON output

Exit codes

Examples

Generate a deck and save it directly to a folder

Generate from a long brief stored in a file

Generate from an existing template

Kick off a long job, poll it from another shell

Auto-paginate every theme

Pipe a list of prompts into Gamma

Share a generation with reviewers as you create it

Related

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

@chowderr/gamma-cli

Install

Quick start

Authentication

Config file location

Commands

gamma generate <prompt>

Prompt input

Text controls

Image controls

Card controls

Export

Sharing

Advanced

gamma generate-from-template <gamma-id> <prompt>

gamma status <generation-id>

gamma themes list

gamma folders list

gamma config init

gamma config show

Global options

JSON output

Exit codes

Examples

Generate a deck and save it directly to a folder

Generate from a long brief stored in a file

Generate from an existing template

Kick off a long job, poll it from another shell

Auto-paginate every theme

Pipe a list of prompts into Gamma

Share a generation with reviewers as you create it

Related

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`gamma generate <prompt>`

`gamma generate-from-template <gamma-id> <prompt>`

`gamma status <generation-id>`

`gamma themes list`

`gamma folders list`

`gamma config init`

`gamma config show`