# flow-plugins-cli

TUI for browsing and installing Claude Code plugins from the Flow ecosystem.

## Installation

```bash
npm install -g @ciandt-flow/cli
```

## Quick Start

```bash
# Authenticate with your Flow credentials
flow auth login

# Launch the interactive plugin browser
flow
```

## Commands

### `flow` (no arguments)

Launches the interactive TUI to browse and manage plugins.

---

### `auth`

Authentication commands.

#### `auth login`

Authenticate and save credentials.

```bash
flow auth login [options]
```

| Option | Description |
|---|---|
| `--client-id <id>` | Client ID |
| `--client-secret <secret>` | Client Secret |
| `--tenant <tenant>` | Tenant |
| `--starter-kit <slug>` | Starter kit slug to install after authentication |

When called **without options**, enters interactive mode — prompts for each field in the terminal.
When called **with all three options**, runs non-interactively and saves credentials directly.

```bash
# interactive mode
flow auth login

# non-interactive mode
flow auth login --client-id <id> --client-secret <secret> --tenant <tenant>

# with starter kit selection
flow auth login --client-id <id> --client-secret <secret> --tenant <tenant> --starter-kit dev
```

#### `auth logout`

Remove saved credentials.

```bash
flow auth logout [--force]
```

#### `auth status`

Show current authentication status.

```bash
flow auth status
```

---

### `plugin`

Plugin management commands.

#### `plugin list`

List plugins.

```bash
flow plugin list [options]
```

| Option | Description |
|---|---|
| `--available` | Show all plugins from catalog with install status |
| `--outdated` | Show installed plugins with updates available |
| `--json` | Output as JSON |

```bash
flow plugin list                  # list installed plugins
flow plugin list --available      # list all plugins from catalog
flow plugin list --outdated       # list plugins with updates available
flow plugin list --json           # output as JSON
```

#### `plugin install <name...>`

Install one or more plugins.

```bash
flow plugin install <name...> [options]
```

| Option | Description |
|---|---|
| `--force` | Reinstall even if already installed |
| `--verbose` | Display each installation step |
| `--silent` | Output as JSON only |
| `--marketplace-source <source>` | GitHub source (owner/repo) for marketplace auto-add when installing external plugins |
| `--scope <scope>` | Scope to install into: `user`, `project`, or `local` |

```bash
flow plugin install flow-adr-writer
flow plugin install flow-adr-writer --scope project
flow plugin install flow-adr-writer flow-prd-writer
flow plugin install flow-adr-writer --force
flow plugin install superpowers@claude-plugins-official
flow plugin install agent-sdk-dev@claude-code-plugins --marketplace-source anthropics/claude-code
```

#### `plugin uninstall <name>`

Uninstall a plugin.

```bash
flow plugin uninstall <name> [options]
```

| Option | Description |
|---|---|
| `--force` | Skip interactive confirmation |
| `--scope <scope>` | Scope to uninstall from: `user`, `project`, or `local` |

```bash
flow plugin uninstall flow-adr-writer
flow plugin uninstall flow-adr-writer --scope project
flow plugin uninstall startup-pack-ai --force
```

#### `plugin enable <name>`

Enable an installed plugin.

```bash
flow plugin enable <name> [options]
```

| Option | Description |
|---|---|
| `--scope <scope>` | Scope to enable in: `user`, `project`, or `local` |

```bash
flow plugin enable flow-adr-writer
flow plugin enable flow-adr-writer --scope project
```

#### `plugin disable <name>`

Disable an installed plugin.

```bash
flow plugin disable <name> [options]
```

| Option | Description |
|---|---|
| `--scope <scope>` | Scope to disable in: `user`, `project`, or `local` |

```bash
flow plugin disable flow-adr-writer
flow plugin disable flow-adr-writer --scope project
```

#### `plugin marketplace add <source>`

Register a plugin marketplace in Claude Code.

```bash
flow plugin marketplace add <source> [options]
```

| Option | Description |
|---|---|
| `--force` | Skip confirmation prompt |
| `--verbose` | Display command output |
| `--silent` | Output as JSON only |

```bash
flow plugin marketplace add anthropics/claude-code
flow plugin marketplace add https://github.com/owner/repo
flow plugin marketplace add anthropics/claude-code --force
```

#### `plugin update [name]`

Update plugins to the latest version. Omit the name to update all installed plugins.

```bash
flow plugin update [name] [options]
```

| Option | Description |
|---|---|
| `--force` | Force update even if already on latest version |
| `--dry-run` | Preview what would be updated without making changes |
| `--verbose` | Display each update step |
| `--silent` | Output as JSON only |
| `--scope <scope>` | Scope to update in: `user`, `project`, or `local` |

```bash
flow plugin update flow-adr-writer
flow plugin update flow-adr-writer --scope project
flow plugin update                  # update all
flow plugin update --dry-run        # preview only
```

---

### `mcp`

MCP server management commands.

#### `mcp add <name> [args...]`

Install an MCP server into Claude Code.

```bash
flow mcp add <name> [args...] --transport <http|stdio> [options]
```

| Option | Description |
|---|---|
| `--transport <type>` | Transport type: `http` or `stdio` (required) |
| `--scope <scope>` | Scope to install into: `user`, `project`, or `local` |
| `--force` | Skip confirmation prompt |
| `--verbose` | Display command output |
| `--silent` | Output as JSON only |

```bash
flow mcp add notion --transport http https://mcp.notion.com/mcp
flow mcp add mcp-chrome --transport stdio uvx mcp-chrome
flow mcp add playwright-mcp --transport stdio uvx playwright-mcp --force
flow mcp add notion --transport http https://mcp.notion.com/mcp --scope project
```

#### `mcp remove <name>`

Remove an MCP server from Claude Code.

```bash
flow mcp remove <name> [options]
```

| Option | Description |
|---|---|
| `--scope <scope>` | Scope to remove from: `user`, `project`, or `local` |
| `--force` | Skip confirmation prompt |
| `--verbose` | Display command output |
| `--silent` | Output as JSON only |

```bash
flow mcp remove notion
flow mcp remove notion --scope project
flow mcp remove playwright-mcp --force
```

---

### `skills`

Manage skills for Claude Code from GitHub repositories or local paths.

#### `skills add <source>`

Install skills from a GitHub repo or local path into Claude Code.

```bash
flow skills add <source> [options]
```

| Option | Description |
|---|---|
| `-g, --global` | Install globally (`~/.claude/skills/`) |
| `-s, --skill <names...>` | Install only specific skills by name |
| `-y, --yes` | Skip confirmation prompts |
| `--list` | List available skills without installing |

```bash
flow skills add vercel-labs/agent-skills
flow skills add owner/repo -g
flow skills add owner/repo -s my-skill
flow skills add owner/repo --list
flow skills add ./local/path
```

#### `skills list`

List installed skills.

```bash
flow skills list [options]
```

| Option | Description |
|---|---|
| `-g, --global` | List globally installed skills |
| `--json` | Output as JSON |

```bash
flow skills list
flow skills list --global
flow skills list --json
```

#### `skills remove [name]`

Remove an installed skill.

```bash
flow skills remove [name] [options]
```

| Option | Description |
|---|---|
| `-g, --global` | Remove from global scope |
| `-f, --force` | Skip confirmation prompt |

```bash
flow skills remove my-skill
flow skills remove my-skill --force
flow skills remove --global my-skill
```

---

### `bundle`

Manage Flow bundles (Findr use-case collections).

#### `bundle install <name>`

Install all artifacts from a Findr bundle in a single operation. Fetches the bundle by name, shows a summary of its artifacts, asks for confirmation, then installs each available artifact sequentially.

```bash
flow bundle install <name>
```

```bash
flow bundle install "My React Kit"
flow bundle install "Squad Setup Bundle"
```

---

### `health`

Run diagnostic checks.

```bash
flow health
```

---

## License

Copyright (c) CI&T Inc. All rights reserved. See LICENSE.md for details.