MagicPath CLI

A component platform for AI agents. Search, share, and add UI components from MagicPath directly into your projects — works with Claude Code, Cursor, and GitHub Copilot.

Quick Start

npm install -g magicpath-ai
magicpath-ai login
magicpath-ai setup-skills  # run in your project directory

After setup-skills, Claude Code, Cursor, and GitHub Copilot automatically pick up MagicPath skills — just mention MagicPath in conversation and your agent knows what to do.

Commands

Auth

login

Log in to your MagicPath account. Opens your browser for one-click authentication.

magicpath-ai login
magicpath-ai login --code <code>   # headless fallback

logout

Clear stored credentials.

magicpath-ai logout

whoami

Show the currently authenticated user.

magicpath-ai whoami

Workspaces & teams

list-teams

List the teams the current user belongs to, with their role in each.

magicpath-ai list-teams
magicpath-ai list-teams -o json

list-members

List members of a team. --team accepts a name (case-insensitive) or an ID.

magicpath-ai list-members --team "Acme Inc"
magicpath-ai list-members --team <teamId> -o json

Discovery

search

Search component names across all accessible projects (personal + team).

magicpath-ai search "button"
magicpath-ai search "nav" --limit 5
magicpath-ai search "header" --team "Acme Inc"

| Option | Description | |--------|-------------| | --limit <n> | Max results (default: 20) | | --team <nameOrId> | Search only within a specific team | | --personal | Search only personal projects |

list-projects

List all projects. By default returns personal + every team you belong to.

magicpath-ai list-projects
magicpath-ai list-projects --team "Acme Inc"
magicpath-ai list-projects --personal

| Option | Description | |--------|-------------| | --limit <n> | Max results | | --offset <n> | Skip first N results (default: 0) | | --team <nameOrId> | Filter to a specific team | | --personal | Show only personal projects |

list-components

List components in a project. Cursor-based pagination — pass pagination.lastId as --after to get the next page.

magicpath-ai list-components <projectId>
magicpath-ai list-components <projectId> --created-by <userId> --sort-by createdAt --order desc

| Option | Description | |--------|-------------| | --limit <n> | Max results per page (default: 100) | | --after <id> | Fetch components after this ID | | --sort-by <field> | Sort by name or createdAt (default: name) | | --order <dir> | asc or desc (default: asc) | | --created-by <userId> | Filter to components created or last-edited by this user |

list-installed

List MagicPath components already installed in the current project (scans src/components/magicpath/ by default).

magicpath-ai list-installed
magicpath-ai list-installed --path src/components/custom

Components

view

Open a component preview in the default browser. In JSON mode, returns the URL without opening.

magicpath-ai view <generatedName>

share

Print a shareable preview URL on stdout — does not open a browser. Use this when an agent needs to present a link in chat.

magicpath-ai share <generatedName>
magicpath-ai share <generatedName> -o json   # { url, generatedName }

inspect

View a component's source code, dependencies, and import info without installing anything. Read-only — no files are written, no package.json is required.

Works in any project type. For non-React projects (Swift, Python, etc.), use inspect to read MagicPath component source as a reference for recreating the component in your target language.

magicpath-ai inspect <generatedName>
magicpath-ai inspect wispy-river-5234 -o json

add

Add a MagicPath component to your project. Fetches the component files, writes them to src/components/magicpath/, and installs any required npm dependencies.

Note: add is for React/TypeScript projects only — it writes .tsx files and installs npm packages. For non-JS projects, use inspect to read the source code and translate it into your target language.

magicpath-ai add <generatedName>
magicpath-ai add <generatedName> --path src/components/ui
magicpath-ai add <generatedName> --dry-run     # preview file list only

| Option | Description | |--------|-------------| | -p, --path <path> | Custom component path (default: src/components/magicpath) | | --dry-run | Preview file list without writing | | -y, --yes | Skip confirmation prompts | | --overwrite | Overwrite existing files |

Themes (design systems)

list-themes

List design systems for the current user, or for a specific team with --team.

magicpath-ai list-themes
magicpath-ai list-themes --team "Acme Inc"

get-theme

Fetch a theme's CSS variables, fonts, and styling prompt. Accepts a numeric ID or a name (case-insensitive).

magicpath-ai get-theme <themeIdOrName>
magicpath-ai get-theme "My Brand Theme" --team "Acme Inc" -o json

| Option | Description | |--------|-------------| | --team <nameOrId> | Look up the theme within a specific team |

Canvas context (for agents)

selection

Return the component(s) and image(s) currently selected in the MagicPath web app canvas, along with the project(s) the user has open. Empty arrays if nothing is selected / no canvas is open.

magicpath-ai selection -o json

active-project

Return the project(s) the user currently has open. Lighter than selection — use this when you only need the project context, not the selection.

magicpath-ai active-project -o json

Projects

create-project

Create a project in the user's personal workspace, or in a team if --team is passed.

magicpath-ai create-project --name "My Stuff"
magicpath-ai create-project --name "Marketing" --team "Acme Inc"
magicpath-ai create-project --team "Acme Inc"  # auto-generated name

| Option | Description | |--------|-------------| | --name <name> | Project name (auto-generated if omitted) | | --team <nameOrId> | Create the project in this team |

Authoring canvas components from code

The code family lets agents create or edit a MagicPath canvas component's source files locally, then submit them back to the platform. State persists in <dir>/magicpath-code.json.

Editable file boundary: src/App.tsx, src/index.css, src/components/generated/**, and assets/** (for temporary image assets). No package.json, no Vite config, no lockfile edits.

code start

Stateful entrypoint for both create and edit. With --project, creates a pending component revision and scaffolds a working starter app for the component. With --component, creates or reuses a pending edit revision and writes the editable source files.

magicpath-ai code start --project <projectId> --dir ./mp-new --name "Hero Card"
magicpath-ai code start --component <componentId> --dir ./mp-work

| Option | Description | |--------|-------------| | --project <projectId> | Target project ID for create. Use exactly one of --project or --component. | | --component <componentId> | Existing component ID for edit. Use exactly one of --project or --component. | | --revision <revisionId> | Revision to start editing (defaults to the component's selected revision) | | --dir <dir> | Working directory to initialize (default: .) | | --name <name> | Component name | | --width <px> | Canvas width for new components (use with --height; only valid with --project) | | --height <px> | Canvas height for new components (use with --width; only valid with --project) |

code context

Fetch existing component source read-only. Does not create a pending revision or write a manifest. Use code start --component if you intend to submit edits.

magicpath-ai code context <componentId> --dir ./mp-work

code submit

Submit changed editable files (and any deletions inferred from the working directory) from <dir>. Use --wait to block until the build completes.

magicpath-ai code submit --dir ./mp-work --wait

| Option | Description | |--------|-------------| | --dir <dir> | Working directory containing magicpath-code.json (default: .) | | --wait | Wait for the build job to finish | | --interval <ms> | Polling interval when --wait is set (default: 2000) | | --width <px> | Updated canvas width (use with --height) | | --height <px> | Updated canvas height (use with --width) |

code create

Convenience: runs code start --project followed by an upload of the files already in <dir>. Prefer the explicit two-step flow when generating code from scratch — the split surfaces the pending component on the canvas while files are still being written.

magicpath-ai code create --project <projectId> --dir ./mp-new --name "Hero Card" --wait

code status

Poll a build job. Returns pending, processing, completed, failed, or cancelled. Failed jobs include sanitized build diagnostics.

magicpath-ai code status <jobId> -o json

Setup & introspection

setup-skills

Install MagicPath skill files for AI agents.

magicpath-ai setup-skills

info

Show auth status, user info, teams, and projects.

magicpath-ai info

clone

Download and unpack a full MagicPath project using a one-time access key.

magicpath-ai clone -k <accessKey>

| Option | Description | |--------|-------------| | -k, --key <accessKey> | Access key (required) | | -i, --ide <ide> | Open in IDE (cursor, antigravity, vscode, webstorm) | | --dir <directory> | Target directory (non-interactive) | | --name <projectName> | Project name (non-interactive) |

Global Options

| Option | Description | |--------|-------------| | -o json | Structured JSON output (also skips interactive prompts) |

Environment Variables

| Variable | Description | |----------|-------------| | MAGICPATH_TOKEN | Auth token (bypasses login flow) |

AI Agent Integration

Running magicpath-ai setup-skills in your project creates skill files that teach AI agents how to use MagicPath:

• Claude Code — .claude/skills/magicpath/SKILL.md
• Cursor — .cursor/rules/magicpath.mdc
• GitHub Copilot — .github/instructions/magicpath.instructions.md

Once set up, agents automatically know how to search for components, share preview links, and add components to your project.

Requirements

• Node.js >= 16.0.0
• npm or yarn

Support

• Issues: GitHub Issues
• Email: [email protected]
• Website: magicpath.ai

License

MIT - Jack Beoris

Made with love by the MagicPath team