Mindframes CLI

Command-line tool for Mindframes — presentations, videos, avatars, audio, branding, media and research.

Run mindframes capabilities at any time for the full, always-current list of callable capabilities, and mindframes <group> --help to drill into one.

Installation

npm install -g @conceptcraft/mindframes

Or use directly with npx:

npx @conceptcraft/mindframes create "Topic" --context "your content"

Setup

Get your API key from Mindframes Settings, then configure:

# Interactive setup (recommended)
mindframes config init

# Or set directly
mindframes config set api-key YOUR_API_KEY

# Or use environment variable
export MINDFRAMES_API_KEY="your-api-key"

Usage

Create a Presentation

Context is required for meaningful presentations. Provide it via one of these methods:

# Direct text context
mindframes create "Q4 Report" --context "Revenue: $10M, Growth: 25%, New customers: 500"

# From a file (markdown, text, or JSON)
mindframes create "Research Summary" --context-file ./research.md

# Pipe content from another command (stdin is read automatically when piped)
cat notes.md | mindframes create "Meeting Notes"

# Upload source documents (PDF, PPTX, DOCX, images)
mindframes create "Competitor Analysis" --file ./competitor-report.pdf

# Brand and style the deck
mindframes create "Board Update" --branding-id <brand-id> --template <template-id>

To use a web page as context, scrape it first and pipe the text in:

mindframes scrape https://example.com/report | mindframes create "Competitor Analysis"

Create Options

| Option | Description | Default | |--------|-------------|---------| | -n, --slides <count> | Number of slides (1-20) | server default | | -m, --mode <mode> | Quality: best, balanced, fast, ultrafast, instant, image-min, image, image-max | fast | | --image-tier <tier> | Embedded-image quality for HTML modes: smart, fast, balanced, best | smart | | -t, --tone <tone> | Tone: creative, professional, educational, formal, casual | server default | | --amount <amount> | Density: minimal, concise, detailed, extensive | server default | | --audience <text> | Target audience description | - | | -g, --goal <type> | Goal: inform, persuade, train, learn, entertain, report | - | | -l, --language <lang> | Output language | - | | --branding-id <id> | Saved brand profile ID (see mindframes branding list) | - | | --brand-domain <url> | Brand the deck by website/domain of a saved brand | - | | --template <id> | Slide template ID (see mindframes templates) | auto | | -c, --context <text> | Inline text context | - | | --context-file <path> | Read context from a file | - | | --stdin | Read context from stdin (also auto-detected when piped) | - | | -f, --file <paths...> | Upload source files (PDF, PPTX, DOCX, images) | - | | --styling <mode> | freeform, brand-only, brand-plus-style, style-only, no-styling | server default | | --reference-url <url> | Image URL used as a visual style reference | - | | --thinking-depth <depth> | AI depth: quick, moderate, deep, profound | server default | | --theme <preset> | instant mode only — blue, violet, rose, orange, green | - | | --primary-color <hex> | instant mode only — primary color | - | | --decorations <style> | instant mode only — none, waves-bottom-left, waves-top-right, blob-corners, minimal | - | | --team-id <id> | Team/workspace override | - | | -o, --output <format> | Output: human, json, quiet | human | | --no-stream | Wait for completion without streaming progress | - | | --wait | Poll until generation completes | - | | --open | Open the deck in a browser when done | - | | --debug | Enable debug logging | - |

--secondary-color, --accent-color, --background-color, --foreground-color, --id and --studio are also available; run mindframes create --help for the full list.

Examples

# High-quality investor pitch
mindframes create "Series A Pitch" -m best -t formal --slides 12 \
  --audience "Venture capitalists" --context-file ./pitch-notes.md

# Quick internal update
mindframes create "Weekly Update" -m instant -t casual --slides 5 \
  --context "Shipped 3 features, fixed 12 bugs, 2 new hires joining Monday"

# Educational content built from uploaded research
mindframes create "AI in Healthcare" -t educational --amount detailed \
  --file ./research-paper.pdf

# JSON output for scripting
URL=$(mindframes create "Demo" --context "..." -o json | jq -r '.viewUrl')

List Presentations

mindframes presentation list                 # List recent presentations
mindframes presentation list --sort title    # Sort by title
mindframes presentation list --json          # JSON for scripting
mindframes presentation list --limit 50      # More results

View Presentation Details

mindframes get <id>                # Get presentation details
mindframes get <id> --format json  # JSON format

Delete Presentation

mindframes delete <id>             # Delete with confirmation
mindframes delete <id> --force     # Skip confirmation

Export & Import

# Export to ZIP
mindframes export <id> -o presentation.zip

# Import from ZIP
mindframes import presentation.zip
mindframes import presentation.zip --dry-run  # Validate only

Branding

mindframes branding list                 # List brand profiles
mindframes branding find "acme"          # Find a saved brand by name or URL
mindframes branding get <id>             # Brand profile details
mindframes branding extract <url>        # Extract a brand profile from a website
mindframes branding status <run-id>      # Check an extraction run
mindframes branding set-default <id>     # Make a brand the workspace default
mindframes branding profile [brand-id]   # Read design tokens
mindframes branding set [brand-id] ...   # Write design tokens (key=value or design.md)
mindframes branding logo set ...         # Set logo, dark variant, or favicon
mindframes branding competitor list|add  # Competitors
mindframes branding social add ...       # Social handles

Configuration

mindframes config init             # Interactive setup
mindframes config show             # Show current config
mindframes config set api-key KEY  # Set API key
mindframes config set api-url URL  # Set custom API URL
mindframes config refresh          # Refresh feature flags (unlocks gated commands)
mindframes config pull             # Pull workspace config
mindframes config path             # Show config file path
mindframes config clear            # Clear all config

Check Authentication

mindframes whoami                  # Show current user and team

AI Coding Assistant Integration

Install the skill for Claude Code, Cursor, and other AI coding assistants:

mindframes skill install           # Auto-detect and install to all editors
mindframes skill install --local   # Install to current project only
mindframes skill show              # View skill content
mindframes skill uninstall         # Remove skill from editors

Supported editors: Claude Code, GitHub Copilot, Cursor, Codex, OpenCode, Windsurf, Agent

Two different video pipelines

The CLI has two unrelated video paths. Picking the wrong one is the most common mistake:

| You want | Use | |----------|-----| | Turn a finished presentation into an MP4 with narration, avatar, music and captions | mindframes presentation video | | Build a video from a brief/storyboard with stock + generated footage | mindframes video |

They share no state: presentation video renders slides you already have, video produces a new film.

Presentation → MP4 (presentation video)

# 1) Create (or reuse) a video project for a deck
mindframes presentation video prepare <presentation-id> --yes

# 2) Inspect the project and its ordered scene timeline
mindframes presentation video inspect <project-id>

# 3) Optional: persist render settings for the project
mindframes presentation video settings <project-id> --settings ./settings.json --yes

# 4) Render the MP4
mindframes presentation video <presentation-id> --render-engine remotion --yes
mindframes presentation video <presentation-id> --render-engine hyperframes --yes

# 5) Poll the render
mindframes presentation video status <run-id>

prepare accepts --force-new, --team-id, --idempotency-key and requires --yes.

The render itself takes either a <presentation-id> argument or --project-id <id> (never both), plus --settings <json-or-path>, --force-new, --force-rerender, --render-engine <remotion|hyperframes> (remotion = Standard, hyperframes = Premium), --team-id, --idempotency-key, and --yes to confirm. --settings and --force-new only work with a presentation id, not --project-id.

Editing the video draft

mindframes presentation video edit <project-id> --edit ./edit.json     # one atomic draft edit
mindframes presentation video refresh <project-id>                     # re-pull slides from the deck
mindframes presentation video versions <project-id>                    # list saved draft versions
mindframes presentation video restore <project-id> <version-number>    # restore a version
mindframes presentation video presenter <project-id> <slide-id> --avatar-id <id>
mindframes video library list <project-id>                              # reusable clips/recordings

presenter takes exactly one of --avatar-id, --cast-preset-id or --inherit; --render-tier <basic|standard|premium> is only valid with --avatar-id, and --no-apply-preset-voice keeps the scene's current voice when applying a cast preset. Avatar and voice IDs come from mindframes avatar options.

Narration and speaker notes

# Regenerate one slide's narration inside a video draft
mindframes presentation video-narration <project-id> --slide-id <id> --instructions "warmer, shorter"
mindframes presentation video-narration-status <run-id>

# Persisted deck speaker notes
mindframes presentation speaker-notes <presentation-id> --mode ensure --style concise
mindframes presentation speaker-notes <presentation-id> --mode regenerate --slide-id <id> --language de
mindframes presentation speaker-notes-status <run-id>

Both follow the run by default; pass --no-follow (or -f json) to get the run ID back immediately.

PowerPoint import and run status

mindframes presentation import --file deck.pptx --mode preserve
mindframes presentation import --file deck.pptx --mode rebrand --branding-id <id>
mindframes presentation import transform <import-id>
mindframes presentation import status <run-id>
mindframes presentation import transform-status <run-id>
mindframes presentation status <run-id>          # deck generation run

Video from a storyboard (video)

The hosted pipeline builds a video from a Markdown storyboard revision.

# Optional: analyze a reference video and reuse it as a media binding
mindframes video reference analyze --file ./ref.mp4 --idempotency-key ref-1
mindframes video reference status <run-id>

# 1) Create a versioned Markdown storyboard
mindframes video storyboard create --file ./storyboard.md --duration 30 --aspect 16:9 \
  --idempotency-key sb-1 --title "Launch teaser"

# 2) Revise it (immutable revisions)
mindframes video storyboard revise <storyboard-id> --base-revision <rev-id> \
  --file ./storyboard-v2.md --duration 30 --aspect 16:9 --idempotency-key sb-2

# 3) Read it back
mindframes video storyboard show <storyboard-id> --json

# 4) Render from a pinned revision (this is the terminal step)
mindframes video create --storyboard-revision <rev-id> --idempotency-key run-1 --yes

# 5) Poll
mindframes video status <run-id>

video create also accepts --source-video <id>, --release (720p; the default render is 480p), --team-id and --approval-receipt. Omit --approval-receipt on the first call to get the browser confirmation URL back.

Poster frames

To attach a poster frame to a finished MP4:

mindframes video thumbnail inject -i out/video.mp4 -t out/thumb.png -o out/final.mp4

Supporting video commands

mindframes video find "city timelapse"                      # stock/web video search
mindframes video lipsync --source-video-id <uuid> --audio-url <url> -o out.mp4
mindframes video translate --source-video-id <uuid> --output-dir ./translated
mindframes video translate-languages                        # supported target languages
mindframes video library list <project-id>                  # reusable clips

Video-aware music and SFX

Generate TTS and finalize the timeline first. Then pass factual video data to the backend; the CLI does not author provider prompts or music plans.

mindframes music generate --request music-request.json --output public/audio/music.mp3
mindframes sfx generate --request sfx-request.json --output public/audio/logo-lock.mp3

Both JSON files use schema_version: 1, video_description, duration_s, and narration. An SFX request also includes one visual_event; include narration word timings when TTS provides them. Gemini turns those final facts into the provider-ready music or SFX prompt on the backend.

Command groups

mindframes capabilities lists every callable capability with its exact command path, and mindframes <group> --help drills into any group below. Some groups appear only after mindframes login + mindframes config refresh (feature-flag gated — derive is the clearest example).

| Group | Purpose | |-------|---------| | create | Create a presentation | | list / get / delete | List, inspect and delete presentations | | export / import | Export a deck to ZIP; import one back (import is admin-only) | | templates | List slide design templates for create --template | | ideas | Generate presentation topic ideas | | presentation | Deck → MP4, speaker notes, PowerPoint import, run status | | video | Storyboard-driven video generation, stock search, lipsync, translation, analysis | | derive | Derivative content from a deck (blog, tweets, LinkedIn, red-team questions, cheat sheet) — feature-flag gated | | branding | Brand profiles, design tokens, logos, competitors, social handles | | avatar | Presenter clips and looks (avatar options lists avatars and voices) | | cast | The faces and voices your videos can use, incl. saved presets | | tts / music / sfx / mix | Voiceover, video-aware music, sound effects, audio mixing | | image | Image search and AI image generation | | search | Web, news, image and stock-video search | | scrape / content / transcript | Extract text from a URL, a file, or a YouTube video | | media | Ingest and transcribe recordings you already own | | document | Create, read and edit Library documents (with versions/restore) | | library | Library folders and filing | | knowledge | Search the workspace Knowledge Hub and read knowledge bundles | | agent | Scheduled agents; read, edit or erase agent memory | | poll | Standalone polls | | microsite | Shareable multi-section web microsite from a brief | | ad-set | Ad creatives (hooks, copy, visuals) from a campaign brief | | visual-abstract | One-page visual abstract graphic from a dense brief | | capabilities | List every callable capability and its parity state | | config / login / logout / whoami | Auth and configuration | | skill | Install the agent skill into Claude Code, Cursor, Codex, … | | runner | Run agent work locally with your own Claude Code / Codex login |

Scripting Examples

# Batch export all presentations
mindframes presentation list --json | jq -r '.[].id' | xargs -I {} mindframes export {} -o {}.zip

# Filter presentations by JSON
mindframes presentation list --json | jq '.[] | select(.numberOfSlides > 10)'

# Generate from file and open URL
mindframes create "Report" --context-file data.md -o json | jq -r '.viewUrl' | xargs open

Output Formats

• human (default): Colored, formatted output for terminal
• json: Machine-readable JSON
• quiet: Minimal output, just errors
• table: Tabular format for list commands

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 2 | Authentication error | | 3 | Not found | | 4 | Rate limit exceeded | | 5 | Network error | | 6 | Invalid input |

Environment Variables

| Variable | Description | |----------|-------------| | MINDFRAMES_API_KEY | API key for authentication | | MINDFRAMES_API_URL | Custom API URL (default: https://www.mindframes.app) |

Requirements

• Node.js 22.22.x

License

Proprietary - Copyright (c) 2024-present Mindframes. All rights reserved.