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

--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:

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) and --team-id. Leave out --yes (or run video quote with the same flags) to print the most the video can charge, and what that covers, without starting anything.

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).

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

Environment Variables

A saved mindframes login is sent only to the server that issued it, and a key saved with mindframes config set api-key only to the API URL it was saved for. When the API URL points elsewhere and no other credential applies, a command that needs to sign in prints a message naming both servers and exits with code 2. Credentialed requests never follow a redirect to another server. mindframes whoami and mindframes config show report the credential in use without printing it. After upgrading the CLI, log in again: credentials saved by earlier versions are not used.

Requirements

• Node.js 22.22.x

License

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