@picahq/cli 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run build:*)",
+      "Bash(npm link)",
+      "Bash(pica:*)",
+      "Bash(npm install:*)",
+      "Bash(npm unlink:*)"
+    ]
+  }
+}

package/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish Package to NPM
+on:
+  release:
+    types: [created]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          registry-url: 'https://registry.npmjs.org/'
+      - name: Install latest npm
+        run: npm install -g npm@latest
+      - name: Install dependencies
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          else
+            npm install
+          fi
+      - name: Build
+        run: npm run build
+      - name: Publish
+        run: npm publish --access public

package/README.md

@@ -0,0 +1,148 @@
+# pica
+
+CLI for managing Pica integrations. Connect to 200+ platforms, discover their APIs, and execute actions from the terminal.
+
+## Install
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+Requires Node.js 18+.
+
+## Setup
+
+```bash
+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).
+
+Get your API key at [app.picaos.com/settings/api-keys](https://app.picaos.com/settings/api-keys).
+
+## Usage
+
+### Connect a platform
+
+```bash
+pica add gmail
+```
+
+Opens a browser to complete OAuth. The CLI polls until the connection is live.
+
+### List connections
+
+```bash
+pica list
+```
+
+```
+  ● gmail      operational
+    live::gmail::default::abc123
+  ● slack      operational
+    live::slack::default::def456
+```
+
+### Browse platforms
+
+```bash
+pica platforms
+pica platforms -c "CRM"
+```
+
+### Search actions
+
+Find available API actions on any connected platform:
+
+```bash
+pica search gmail "send email"
+pica search slack "post message"
+pica search stripe "list payments"
+```
+
+```
+  POST    /gmail/v1/users/{{userId}}/messages/send
+         Send Message
+         conn_mod_def::ABC123::XYZ789
+```
+
+### Read API docs
+
+```bash
+pica actions knowledge <actionId>
+pica actions k <actionId> --full    # no truncation
+```
+
+Shows method, path, path variables, parameter schemas, and request/response examples.
+
+### Execute an action
+
+```bash
+pica exec <actionId> \
+  -c live::gmail::default::abc123 \
+  -d '{"to": "test@example.com", "subject": "Hello", "body": "Hi there"}' \
+  -p userId=me
+```
+
+If you omit flags, the CLI prompts interactively:
+- Auto-selects the connection if only one exists for the platform
+- Prompts for each `{{path variable}}` not provided via `-p`
+- Prompts for the request body on POST/PUT/PATCH if `-d` is missing
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `pica init` | Set up API key and install MCP |
+| `pica add <platform>` | Connect a platform via OAuth |
+| `pica list` | List connections with keys |
+| `pica platforms` | Browse available platforms |
+| `pica search <platform> [query]` | Search for actions |
+| `pica actions knowledge <id>` | Get API docs for an action |
+| `pica exec <id>` | Execute an action |
+
+Every command supports `--json` for machine-readable output.
+
+### Aliases
+
+| Short | Full |
+|-------|------|
+| `pica ls` | `pica list` |
+| `pica p` | `pica platforms` |
+| `pica a search` | `pica actions search` |
+| `pica a k` | `pica actions knowledge` |
+| `pica a x` | `pica actions execute` |
+
+## How it works
+
+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.
+
+## Development
+
+```bash
+npm run dev        # watch mode
+npm run build      # production build
+npm run typecheck  # type check without emitting
+```
+
+## Project structure
+
+```
+src/
+  index.ts              # Commander setup and command registration
+  commands/
+    init.ts             # pica init (API key + MCP setup)
+    connection.ts       # pica add, pica list
+    platforms.ts        # pica platforms
+    actions.ts          # pica search, actions knowledge, exec
+  lib/
+    api.ts              # HTTP client for Pica API
+    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
+    platforms.ts        # Platform search and fuzzy matching
+    browser.ts          # Open browser for OAuth and API key pages
+```

package/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: pica
+description: Interact with third-party platforms (Gmail, Slack, HubSpot, Stripe, etc.) via Pica. Use when the user wants to search for available API actions, read API documentation, execute API calls, manage connections, or do anything involving third-party integrations.
+triggers:
+  - "search actions"
+  - "find actions"
+  - "execute action"
+  - "run action"
+  - "list connections"
+  - "add connection"
+  - "list platforms"
+  - "pica"
+  - "integration"
+  - "send email"
+  - "check calendar"
+  - "post to slack"
+---
+
+# Pica
+
+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
+
+Pica provides two interfaces: the **MCP tools** and the **CLI**. Use the right one for the job.
+
+### MCP tools (primary, for AI agents)
+
+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.
+
+The MCP exposes 5 tools:
+
+| Tool | Purpose |
+|------|---------|
+| `mcp__pica__list_pica_integrations` | List all available 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__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.
+
+## 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
+```
+
+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.
+
+### Step 2: Search for the right action
+
+```
+mcp__pica__search_pica_platform_actions({
+  platform: "gmail",
+  query: "send email",
+  agentType: "execute"
+})
+```
+
+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`.
+
+### Step 3: Get action knowledge (required before execute)
+
+```
+mcp__pica__get_pica_action_knowledge({
+  actionId: "conn_mod_def::ABC123::XYZ789",
+  platform: "gmail"
+})
+```
+
+This returns full API documentation: parameters, request/response schemas, caveats, examples. You MUST call this before executing to understand what the action expects.
+
+### Step 4: Execute
+
+```
+mcp__pica__execute_pica_action({
+  actionId: "conn_mod_def::ABC123::XYZ789",
+  connectionKey: "live::gmail::default::abc123",
+  platform: "gmail",
+  data: { to: "someone@example.com", subject: "Hello", body: "Hi there" },
+  pathVariables: { userId: "me" }
+})
+```
+
+Pass the `connectionKey` from step 1, the `actionId` from step 2, and the parameters from step 3.
+
+## CLI reference
+
+For when you need the CLI (setup, OAuth, human-facing output):
+
+| Command | Description |
+|---------|-------------|
+| `pica init` | Set up API key and install MCP |
+| `pica list` | List connections with keys |
+| `pica add <platform>` | Add a new connection via OAuth (opens browser) |
+| `pica platforms` | Browse all available 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
+
+```bash
+pica exec <actionId> \
+  -c <connectionKey> \
+  -d '{"key": "value"}' \
+  -p pathVar=value \
+  -q queryParam=value \
+  --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`.
+- **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.
+
+## Common patterns
+
+### Send an email
+1. Search: `platform: "gmail", query: "send email"`
+2. Knowledge: get the action docs
+3. Execute with `data: { to, subject, body, connectionKey }`
+
+### Read emails
+1. Search: `platform: "gmail", query: "get emails"`
+2. Knowledge: understand pagination (numberOfEmails, pageToken)
+3. Execute with `data: { connectionKey, numberOfEmails, label, query }`
+
+### Post to Slack
+1. Search: `platform: "slack", query: "post message"`
+2. Knowledge: get channel ID format
+3. Execute with `data: { channel, text }`
+
+### CRM operations
+1. Search: `platform: "hubspot"` or `"attio"`, query: `"create contact"` / `"list contacts"` / etc.
+2. Knowledge: understand required fields
+3. Execute with the right data shape
+
+### Calendar
+1. Search: `platform: "google-calendar", query: "list events"`
+2. Knowledge: understand time format, calendar ID
+3. Execute with date range parameters

package/bin/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../dist/index.js';

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@picahq/cli",
+  "version": "0.1.0",
+  "description": "CLI for managing Pica integrations",
+  "type": "module",
+  "bin": {
+    "pica": "./bin/cli.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "start": "node bin/cli.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "commander": "^13.1.0",
+    "open": "^10.1.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.1",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}