@conceptcraft/mindframes

Command-line tool for creating AI-powered presentations with Mindframes.

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 CC_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
cat notes.md | mindframes create "Meeting Notes"

# Scrape content from URLs
mindframes create "Competitor Analysis" --sources https://example.com/report

# Combine multiple sources
cat data.json | mindframes create "Analysis" --sources https://article.com --context "Focus on Q4"

Create Options

| Option | Description | Default | |--------|-------------|---------| | -n, --slides <count> | Number of slides (1-20) | 10 | | -m, --mode <mode> | Quality: best, balanced, fast, ultrafast, instant | balanced | | -t, --tone <tone> | Tone: creative, professional, educational, formal, casual | professional | | --amount <amount> | Density: minimal, concise, detailed, extensive | concise | | --audience <text> | Target audience description | General Audience | | -l, --language <lang> | Output language code | en | | -b, --brand <id\|url> | Branding ID or URL | - | | -c, --context <text> | Direct text context | - | | --context-file <path> | Read context from file | - | | --sources <urls...> | URLs to scrape for context | - | | --styling <mode> | freeform, brand-only, brand-plus-style, style-only, no-styling | freeform | | --reference-url <url> | Style reference image URL | - | | --thinking-depth <depth> | AI depth: quick, moderate, deep, profound | moderate | | -o, --output <format> | Output: human, json, quiet | human | | --no-stream | Disable progress streaming | - | | --debug | Enable debug logging | - |

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 with research
mindframes create "AI in Healthcare" -t educational --amount detailed \
  --sources https://research-paper.pdf https://news-article.com

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

List Presentations

mindframes list                    # List recent presentations
mindframes list --format table     # Table format
mindframes list --format json      # JSON for scripting
mindframes 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 extract <url>  # Extract branding from website

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 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 Mindframes 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, Cursor, Codex, OpenCode, Windsurf, Agent

Scripting Examples

# Batch export all presentations
mindframes list --format ids | xargs -I {} mindframes export {} -o {}.zip

# Filter presentations by JSON
mindframes list --format json | jq '.[] | select(.slides > 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 | |----------|-------------| | CC_MINDFRAMES_API_KEY | API key for authentication | | CC_SLIDES_API_URL | Custom API URL (default: https://mindframes.app) |

Requirements

• Node.js 20.0.0 or higher

Development

# Clone and install
cd packages/cli
pnpm install

# Build
pnpm build

# Run locally
./bin/cli.js --help

# Watch mode
pnpm dev

Publishing

The CLI is published to npm under the @conceptcraft organization.

npm org: @conceptcraft

Release Process

1. Manual release (recommended):

   • Go to GitHub Actions → "Publish CLI to npm"
   • Click "Run workflow"
   • Enter version (e.g., 0.2.0)
   • Select dist-tag (latest, beta, or next)

2. Tag-based release:

   git tag cli-v0.2.0
   git push origin cli-v0.2.0

Required Secrets

• NPM_TOKEN: npm automation token with publish access to @conceptcraft org

License

MIT