Magicpath

# MagicPath CLI Reference

> **IMPORTANT:** Always pass `-y` to skip interactive prompts when running from an agent context. Use `-o json` for structured output.

## Commands

### `info` — Project and auth context

```bash
magicpath-ai info              # human-readable
magicpath-ai info -o json      # structured JSON
```

Returns auth status, user info, teams, projects (personal + team), and CLI version. The `teams` array shows which teams the user belongs to and their role. Use `list-members` for full member details of a specific team.

### `login` — Authenticate

```bash
magicpath-ai login                    # one-click browser login (auto-completes)
magicpath-ai login --code <code>      # exchange auth code directly (headless fallback)
```

Opens the browser and completes login automatically when the user authorizes.

| Flag | Description |
|------|-------------|
| `--code <code>` | Exchange a browser authorization code directly (headless fallback) |

### `whoami` — Check authentication

```bash
magicpath-ai whoami
magicpath-ai whoami -o json
```

### `list-teams` — List teams

```bash
magicpath-ai list-teams
magicpath-ai list-teams -o json
```

Lists all teams the user belongs to, with their role in each.

JSON output: `{ teams: [{ id, name, role }] }`

### `list-members` — List members of a team

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

Lists all members of the specified team. The `--team` flag is required and accepts a name (case-insensitive) or ID.

JSON output: `{ team: { id, name }, members: [{ id, displayName, email, role }] }`

Use `list-members` to resolve a person's name to their user ID, then use `--created-by <userId>` on `list-components` to find their work.

### `search` — Search components across all projects

```bash
magicpath-ai search "input"
magicpath-ai search "button" -o json
magicpath-ai search "card" --limit 5
magicpath-ai search "header" --team "Acme Inc" -o json
magicpath-ai search "nav" --personal -o json
```

Searches component names (case-insensitive substring match) across all accessible projects (personal + team). Returns matches with project and workspace context. Each result includes `previewImageUrl` — use `list-components` or search results to get preview images when visual context is needed.

| Flag | Description | Default |
|------|-------------|---------|
| `--limit <n>` | Max results | 20 |
| `--team <nameOrId>` | Search only within a specific team | all |
| `--personal` | Search only personal projects | false |

JSON output includes `ownerType` (`"personal"` or `"team"`) and `ownerName` on each result.

### `list-projects` — List all projects

```bash
magicpath-ai list-projects
magicpath-ai list-projects -o json
magicpath-ai list-projects -o json --limit 10
magicpath-ai list-projects --team "Acme Inc" -o json
magicpath-ai list-projects --personal -o json
```

By default, lists all accessible projects (personal + all teams). Use `--team` or `--personal` to filter.

| Flag | Description | Default |
|------|-------------|---------|
| `--limit <n>` | Max results | all |
| `--offset <n>` | Skip first N results | 0 |
| `--team <nameOrId>` | Filter to a specific team (name or ID) | all |
| `--personal` | Show only personal projects | false |

JSON output: `{ projects, pagination: { total, limit, offset, hasMore } }`. Each project includes:
- `ownerType` (`"personal"` or `"team"`) and `ownerName` (user email or team name)
- `createdBy` (object or null) — `{ id, displayName }` of the user who created this project

### `create-project` — Create a new project

```bash
magicpath-ai create-project --name "My Stuff" -o json
magicpath-ai create-project --name "My Stuff" --team "Acme Inc" -o json
magicpath-ai create-project --team "Acme Inc" -o json   # auto-generated name
```

Creates a project in the user's personal workspace, or in a team if `--team` is passed. With `--team`, the u