@picahq/cli 0.1.0 → 0.2.0

package/README.md

@@ -18,10 +18,54 @@ Requires Node.js 18+.
 pica init
 ```
 
-This prompts for your Pica API key, saves it to `~/.pica/config.json`, and installs the MCP server into your AI agents (Claude Code, Claude Desktop, Cursor, Windsurf).
+This walks you through:
+1. Entering your Pica API key (validates it)
+2. Choosing which AI agents to install the MCP server into
+3. Choosing global vs project-level installation
 
 Get your API key at [app.picaos.com/settings/api-keys](https://app.picaos.com/settings/api-keys).
 
+Config is saved to `~/.pica/config.json`.
+
+### Re-running init
+
+If you already have a config, `pica init` shows your current setup instead of starting over:
+
+```
+ Pica
+
+  Current Setup
+  ──────────────────────────────────────────
+  API Key:  sk_test_...9j-Y
+  Config:   ~/.pica/config.json
+
+  Agent           Global  Project
+  ──────────────  ──────  ───────
+  Claude Code     ● yes   ● yes
+  Claude Desktop  ● yes   -
+  Cursor          ○ no    ○ no
+  Windsurf        -       -
+
+  - = not detected on this machine
+```
+
+Then it offers targeted actions based on what's missing:
+
+- **Update API key** -- validates the new key, then re-installs to every agent that currently has the MCP (preserving global/project scopes)
+- **Install MCP to more agents** -- only shows detected agents missing the MCP
+- **Install MCP for this project** -- creates `.mcp.json` / `.cursor/mcp.json` in cwd for agents that support project scope
+- **Start fresh** -- full setup flow from scratch
+
+Options that don't apply are hidden. If every detected agent already has the MCP globally, "Install MCP to more agents" won't appear.
+
+### Init flags
+
+| Flag | Effect |
+|------|--------|
+| `-y, --yes` | Skip confirmations |
+| `-g, --global` | Install MCP globally (default, available in all projects) |
+| `-p, --project` | Install MCP for this project only (creates config files in cwd) |
+
 ## Usage
 
 ### Connect a platform
@@ -119,6 +163,19 @@ Every command supports `--json` for machine-readable output.
 
 All API calls route through Pica's passthrough proxy (`api.picaos.com/v1/passthrough`), which injects auth credentials, handles rate limiting, and normalizes responses. Your connection keys tell Pica which credentials to use. You never touch raw OAuth tokens.
 
+## MCP installation
+
+`pica init` writes MCP server configs into the following locations:
+
+| Agent | Global config | Project config |
+|-------|--------------|----------------|
+| Claude Code | `~/.claude.json` | `.mcp.json` |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | n/a |
+| Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | n/a |
+
+Global installs make the MCP available everywhere. Project installs create config files in your current directory that can be committed and shared with your team (each team member needs their own API key).
+
 ## Development
 
 ```bash
@@ -133,7 +190,7 @@ npm run typecheck  # type check without emitting
 src/
   index.ts              # Commander setup and command registration
   commands/
-    init.ts             # pica init (API key + MCP setup)
+    init.ts             # pica init (setup, status display, targeted actions)
     connection.ts       # pica add, pica list
     platforms.ts        # pica platforms
     actions.ts          # pica search, actions knowledge, exec
@@ -142,7 +199,8 @@ src/
     types.ts            # TypeScript interfaces
     actions.ts          # Action ID normalization, path variable helpers
     config.ts           # ~/.pica/config.json read/write
-    agents.ts           # MCP config for Claude, Cursor, Windsurf
+    agents.ts           # Agent detection, MCP config, status reporting
     platforms.ts        # Platform search and fuzzy matching
     browser.ts          # Open browser for OAuth and API key pages
+    table.ts            # Formatted table output
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@picahq/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI for managing Pica integrations",
   "type": "module",
   "bin": {
@@ -26,4 +26,4 @@
   "engines": {
     "node": ">=18"
   }
-}
+}

package/{SKILL.md → skills/pica/SKILL.md}

@@ -20,82 +20,42 @@ triggers:
 
 Pica gives you access to 200+ third-party platforms (Gmail, Slack, HubSpot, Stripe, Shopify, etc.) through a single interface. It handles auth, rate limiting, and retries so you just call the action you need.
 
-## How to interact with Pica
+## Two interfaces: MCP and CLI
 
-Pica provides two interfaces: the **MCP tools** and the **CLI**. Use the right one for the job.
+| Interface | Best for |
+|-----------|----------|
+| **MCP tools** | AI agents doing work (search, inspect, execute actions) |
+| **CLI** (`pica`) | Humans doing setup, OAuth, browsing |
 
-### MCP tools (primary, for AI agents)
+**Rule of thumb:** If you're doing the work, use MCP. If a human needs to interact (OAuth, setup), use CLI.
 
-The Pica MCP is your primary interface. It gives you structured JSON in/out with no parsing overhead. Always prefer MCP tools for discovering, inspecting, and executing actions.
+## MCP tools
 
-The MCP exposes 5 tools:
+The Pica MCP is your primary interface. It gives you structured JSON in/out with no parsing overhead.
 
-| Tool | Purpose |
-|------|---------|
-| `mcp__pica__list_pica_integrations` | List all available platforms and active connections |
+| Tool | What it does |
+|------|-------------|
+| `mcp__pica__list_pica_integrations` | List all platforms and active connections |
 | `mcp__pica__search_pica_platform_actions` | Search for actions on a platform |
-| `mcp__pica__get_pica_action_knowledge` | Get full API docs for an action (MUST call before execute) |
+| `mcp__pica__get_pica_action_knowledge` | Get full API docs for an action (call before execute) |
 | `mcp__pica__execute_pica_action` | Execute an action on a connected platform |
 
-### CLI (secondary, for setup and human-facing tasks)
-
-The `pica` CLI is better for tasks that require a browser (OAuth), interactive prompts, or human-readable output. Use it for:
-
-- **Setup**: `pica init` (configures API key and installs MCP)
-- **Adding connections**: `pica add gmail` (opens browser for OAuth)
-- **Browsing platforms**: `pica platforms` (visual, categorized list)
-- **Quick lookups by a human**: `pica list`, `pica search gmail "send"`
-
-## When to use which
-
-| Task | Use |
-|------|-----|
-| Execute an API action | MCP |
-| Search for actions | MCP |
-| Read action docs | MCP |
-| List connections/platforms | MCP |
-| Add a new connection (OAuth) | CLI |
-| Initial setup | CLI |
-| Show a user what's available (visual output) | CLI |
-
-**Rule of thumb:** If you're doing the work, use MCP. If a human needs to interact (OAuth, setup), use CLI.
+### Standard workflow
 
-## Setup and prerequisites
-
-The MCP server is installed via `pica init`. If the MCP tools are not available, the CLI needs to be installed and init needs to run:
-
-```bash
-pica --version
 ```
-
-If the command is not found, install it:
-
-```bash
-cd /Users/moe/projects/one/connection-cli
-npm install
-npm run build
-npm link
-```
-
-Then run setup:
-
-```bash
-pica init
+1. list_pica_integrations          -> get connection keys and platform names
+2. search_pica_platform_actions    -> find the right action
+3. get_pica_action_knowledge       -> read the docs (REQUIRED before execute)
+4. execute_pica_action             -> do the thing
 ```
 
-This stores the API key in `~/.pica/config.json` and installs the MCP server into Claude Code, Claude Desktop, Cursor, and Windsurf. After init, the MCP tools will be available.
-
-## MCP workflow
-
-This is the standard workflow for any integration task.
-
 ### Step 1: List connections and platforms
 
 ```
 mcp__pica__list_pica_integrations()
 ```
 
-Returns all active connections (with connection keys) and available platforms. Check this first to see what's connected.
+Returns all active connections (with connection keys) and available platforms. Always check this first.
 
 ### Step 2: Search for the right action
 
@@ -107,9 +67,10 @@ mcp__pica__search_pica_platform_actions({
 })
 ```
 
-Use `agentType: "execute"` when the intent is to run the action. Use `"knowledge"` when the user wants to understand the API or write code against it.
-
-The platform name must be in kebab-case (e.g., `ship-station`, `hubspot`, `google-calendar`). Get the exact name from `list_pica_integrations`.
+- `agentType: "execute"` when you intend to run the action
+- `agentType: "knowledge"` when you want to understand the API or write code
+- Platform names are kebab-case: `gmail`, `hubspot`, `google-calendar`, `ship-station`
+- Get the exact platform name from `list_pica_integrations`
 
 ### Step 3: Get action knowledge (required before execute)
 
@@ -120,7 +81,7 @@ mcp__pica__get_pica_action_knowledge({
 })
 ```
 
-This returns full API documentation: parameters, request/response schemas, caveats, examples. You MUST call this before executing to understand what the action expects.
+Returns parameters, request/response schemas, caveats, and examples. You MUST call this before executing.
 
 ### Step 4: Execute
 
@@ -134,23 +95,63 @@ mcp__pica__execute_pica_action({
 })
 ```
 
-Pass the `connectionKey` from step 1, the `actionId` from step 2, and the parameters from step 3.
+Pass: `connectionKey` from step 1, `actionId` from step 2, parameters from step 3.
 
 ## CLI reference
 
-For when you need the CLI (setup, OAuth, human-facing output):
+For setup, OAuth, and human-facing tasks.
+
+### Setup: `pica init`
+
+First run prompts for API key, validates it, and installs the MCP into your AI agents.
+
+Re-running `pica init` after setup shows a status dashboard:
+
+```
+  Current Setup
+  ──────────────────────────────────────────
+  API Key:  sk_test_...9j-Y
+  Config:   ~/.pica/config.json
+
+  Agent           Global  Project
+  ──────────────  ──────  ───────
+  Claude Code     ● yes   ● yes
+  Claude Desktop  ● yes   -
+  Cursor          ○ no    ○ no
+  Windsurf        -       -
+
+  - = not detected on this machine
+```
+
+Then offers targeted actions (only relevant options shown):
+
+| Action | What it does |
+|--------|-------------|
+| Update API key | Validates new key, re-installs MCP to all agents that have it |
+| Install MCP to more agents | Shows only detected agents missing the MCP |
+| Install MCP for this project | Creates project-level configs in cwd |
+| Start fresh | Full setup from scratch |
+
+Flags: `-y` (skip confirmations), `-g` (global install), `-p` (project install).
+
+### Other commands
 
 | Command | Description |
 |---------|-------------|
-| `pica init` | Set up API key and install MCP |
+| `pica add <platform>` | Connect a platform via OAuth (opens browser) |
 | `pica list` | List connections with keys |
-| `pica add <platform>` | Add a new connection via OAuth (opens browser) |
-| `pica platforms` | Browse all available platforms |
+| `pica platforms` | Browse all 200+ platforms |
 | `pica search <platform> [query]` | Search for actions |
 | `pica actions knowledge <id>` | Get API docs for an action |
 | `pica exec <id>` | Execute an action |
 
-### CLI options for exec
+All commands support `--json` for machine-readable output.
+
+### Aliases
+
+`pica ls` = list, `pica p` = platforms, `pica a search` = actions search, `pica a k` = actions knowledge, `pica a x` = actions execute.
+
+### Exec flags
 
 ```bash
 pica exec <actionId> \
@@ -161,16 +162,35 @@ pica exec <actionId> \
   --json
 ```
 
-All commands support `--json` for machine-readable output.
-
 ## Key concepts
 
-- **Connection key**: Identifies which authenticated connection to use. Format: `live::gmail::default::abc123` or `test::gmail::default::abc123`. Get these from `list_pica_integrations` or `pica list`.
-- **Action ID**: Identifies a specific API action. Always starts with `conn_mod_def::`. Get these from search results.
-- **Platform name**: Kebab-case identifier (e.g., `gmail`, `hubspot`, `google-calendar`, `ship-station`). Get the exact name from `list_pica_integrations`.
+- **Connection key**: Identifies which authenticated connection to use. Format: `live::gmail::default::abc123`. Get from `list_pica_integrations` or `pica list`.
+- **Action ID**: Identifies a specific API action. Starts with `conn_mod_def::`. Get from search results.
+- **Platform name**: Kebab-case identifier (`gmail`, `hubspot`, `google-calendar`, `ship-station`). Get from `list_pica_integrations`.
 - **Passthrough proxy**: All actions route through Pica's proxy which injects auth, handles rate limits, and normalizes responses. You never touch raw OAuth tokens.
 - **Pagination**: Some actions return `nextPageToken` or similar. Pass it back in subsequent requests to page through results.
 
+## MCP installation details
+
+`pica init` writes MCP configs here:
+
+| Agent | Global | Project |
+|-------|--------|---------|
+| Claude Code | `~/.claude.json` | `.mcp.json` |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | n/a |
+| Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | n/a |
+
+Global = available everywhere. Project = committed to repo, shared with team (each person needs their own API key).
+
+If MCP tools are not available, install and init:
+
+```bash
+cd /Users/moe/projects/one/connection-cli
+npm install && npm run build && npm link
+pica init
+```
+
 ## Common patterns
 
 ### Send an email
@@ -189,7 +209,7 @@ All commands support `--json` for machine-readable output.
 3. Execute with `data: { channel, text }`
 
 ### CRM operations
-1. Search: `platform: "hubspot"` or `"attio"`, query: `"create contact"` / `"list contacts"` / etc.
+1. Search: `platform: "hubspot"` or `"attio"`, query: `"create contact"` / `"list contacts"`
 2. Knowledge: understand required fields
 3. Execute with the right data shape