@picahq/cli 0.1.0 → 0.3.0

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@picahq/cli",
-  "version": "0.1.0",
-  "description": "CLI for managing Pica integrations",
+  "version": "0.3.0",
+  "description": "CLI for managing Pica",
   "type": "module",
+  "files": [
+    "bin",
+    "dist"
+  ],
   "bin": {
     "pica": "./bin/cli.js"
   },
@@ -26,4 +30,4 @@
   "engines": {
     "node": ">=18"
   }
-}
+}

package/.claude/settings.local.json

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

package/.github/workflows/publish.yml

@@ -1,29 +0,0 @@
-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/SKILL.md

@@ -1,199 +0,0 @@
----
-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/src/commands/actions.ts

@@ -1,385 +0,0 @@
-import * as p from '@clack/prompts';
-import pc from 'picocolors';
-import { getApiKey } from '../lib/config.js';
-import { PicaApi } from '../lib/api.js';
-import { extractPathVariables, resolveTemplateVariables } from '../lib/actions.js';
-import { printTable } from '../lib/table.js';
-import type { PlatformAction, ActionKnowledge } from '../lib/types.js';
-
-function getApi(): PicaApi {
-  const apiKey = getApiKey();
-  if (!apiKey) {
-    p.cancel('Not configured. Run `pica init` first.');
-    process.exit(1);
-  }
-  return new PicaApi(apiKey);
-}
-
-function colorMethod(method: string): string {
-  const m = method.toUpperCase();
-  switch (m) {
-    case 'GET': return pc.green(m);
-    case 'POST': return pc.yellow(m);
-    case 'PUT': return pc.blue(m);
-    case 'PATCH': return pc.cyan(m);
-    case 'DELETE': return pc.red(m);
-    default: return pc.dim(m);
-  }
-}
-
-function padMethod(method: string): string {
-  return method.toUpperCase().padEnd(7);
-}
-
-// --- Search ---
-
-export async function actionsSearchCommand(
-  platform: string,
-  query?: string,
-  options: { json?: boolean; limit?: string } = {}
-): Promise<void> {
-  const api = getApi();
-
-  if (!query) {
-    const input = await p.text({
-      message: `Search actions on ${pc.cyan(platform)}:`,
-      placeholder: 'send email, create contact, list orders...',
-    });
-    if (p.isCancel(input)) {
-      p.cancel('Cancelled.');
-      process.exit(0);
-    }
-    query = input;
-  }
-
-  const spinner = p.spinner();
-  spinner.start(`Searching ${platform} actions...`);
-
-  try {
-    const limit = options.limit ? parseInt(options.limit, 10) : 10;
-    const actions = await api.searchActions(platform, query, limit);
-    spinner.stop(`${actions.length} action${actions.length === 1 ? '' : 's'} found`);
-
-    if (options.json) {
-      console.log(JSON.stringify(actions, null, 2));
-      return;
-    }
-
-    if (actions.length === 0) {
-      p.note(`No actions found for "${query}" on ${platform}.`, 'No Results');
-      return;
-    }
-
-    console.log();
-
-    const rows = actions.map(action => ({
-      method: colorMethod(padMethod(action.method)),
-      path: action.path,
-      title: action.title,
-      id: action._id,
-    }));
-
-    printTable(
-      [
-        { key: 'method', label: 'Method' },
-        { key: 'title', label: 'Title' },
-        { key: 'path', label: 'Path', color: pc.dim },
-        { key: 'id', label: 'Action ID', color: pc.dim },
-      ],
-      rows
-    );
-
-    console.log();
-    p.note(
-      `Get docs:  ${pc.cyan('pica actions knowledge <actionId>')}\n` +
-      `Execute:   ${pc.cyan('pica actions execute <actionId>')}`,
-      'Next Steps'
-    );
-  } catch (error) {
-    spinner.stop('Search failed');
-    p.cancel(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
-    process.exit(1);
-  }
-}
-
-// --- Knowledge ---
-
-export async function actionsKnowledgeCommand(
-  actionId: string,
-  options: { json?: boolean; full?: boolean } = {}
-): Promise<void> {
-  const api = getApi();
-
-  const spinner = p.spinner();
-  spinner.start('Loading action knowledge...');
-
-  try {
-    const knowledge = await api.getActionKnowledge(actionId);
-    spinner.stop('Action knowledge loaded');
-
-    if (!knowledge) {
-      p.cancel(`No knowledge found for action: ${actionId}`);
-      process.exit(1);
-    }
-
-    if (options.json) {
-      console.log(JSON.stringify(knowledge, null, 2));
-      return;
-    }
-
-    printKnowledge(knowledge, options.full);
-  } catch (error) {
-    spinner.stop('Failed to load knowledge');
-    p.cancel(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
-    process.exit(1);
-  }
-}
-
-function printKnowledge(k: ActionKnowledge, full?: boolean): void {
-  console.log();
-  console.log(pc.bold(`  ${k.title}`));
-  console.log();
-  console.log(`  Platform:  ${pc.cyan(k.connectionPlatform)}`);
-  console.log(`  Method:    ${colorMethod(k.method)}`);
-  console.log(`  Path:      ${k.path}`);
-  console.log(`  Base URL:  ${pc.dim(k.baseUrl)}`);
-
-  if (k.tags?.length) {
-    console.log(`  Tags:      ${k.tags.map(t => pc.dim(t)).join(', ')}`);
-  }
-
-  const pathVars = extractPathVariables(k.path);
-  if (pathVars.length > 0) {
-    console.log(`  Path Vars: ${pathVars.map(v => pc.yellow(`{{${v}}}`)).join(', ')}`);
-  }
-
-  console.log(`  Active:    ${k.active ? pc.green('yes') : pc.red('no')}`);
-  console.log(`  ID:        ${pc.dim(k._id)}`);
-
-  if (k.knowledge) {
-    console.log();
-    console.log(pc.bold('  API Documentation'));
-    console.log(pc.dim('  ' + '─'.repeat(40)));
-    console.log();
-
-    const lines = k.knowledge.split('\n');
-    const displayLines = full ? lines : lines.slice(0, 50);
-
-    for (const line of displayLines) {
-      console.log(`  ${line}`);
-    }
-
-    if (!full && lines.length > 50) {
-      console.log();
-      console.log(pc.dim(`  ... ${lines.length - 50} more lines. Use --full to see all.`));
-    }
-  }
-
-  console.log();
-}
-
-// --- Execute ---
-
-export async function actionsExecuteCommand(
-  actionId: string,
-  options: {
-    json?: boolean;
-    connection?: string;
-    data?: string;
-    pathVar?: string[];
-    query?: string[];
-    formData?: boolean;
-    formUrlencoded?: boolean;
-  } = {}
-): Promise<void> {
-  const api = getApi();
-
-  // 1. Fetch action knowledge to get method + path
-  const spinner = p.spinner();
-  spinner.start('Loading action details...');
-
-  let knowledge: ActionKnowledge;
-  try {
-    const k = await api.getActionKnowledge(actionId);
-    if (!k) {
-      spinner.stop('Action not found');
-      p.cancel(`No action found for: ${actionId}`);
-      process.exit(1);
-    }
-    knowledge = k;
-    spinner.stop(`${colorMethod(knowledge.method)} ${knowledge.path}`);
-  } catch (error) {
-    spinner.stop('Failed to load action');
-    p.cancel(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
-    process.exit(1);
-  }
-
-  // 2. Resolve connection key
-  let connectionKey = options.connection;
-  if (!connectionKey) {
-    connectionKey = await resolveConnection(api, knowledge.connectionPlatform);
-  }
-
-  // 3. Resolve path variables
-  const pathVarMap = parseKeyValuePairs(options.pathVar || []);
-  const pathVars = extractPathVariables(knowledge.path);
-  for (const v of pathVars) {
-    if (!pathVarMap[v]) {
-      const input = await p.text({
-        message: `Value for path variable ${pc.yellow(`{{${v}}}`)}:`,
-        validate: (val) => val.trim() ? undefined : 'Value is required',
-      });
-      if (p.isCancel(input)) {
-        p.cancel('Cancelled.');
-        process.exit(0);
-      }
-      pathVarMap[v] = input;
-    }
-  }
-
-  // 4. Resolve body data
-  let bodyData: Record<string, unknown> = {};
-  if (options.data) {
-    try {
-      bodyData = JSON.parse(options.data);
-    } catch {
-      p.cancel('Invalid JSON in --data flag.');
-      process.exit(1);
-    }
-  } else if (!['GET', 'DELETE', 'HEAD'].includes(knowledge.method.toUpperCase())) {
-    const input = await p.text({
-      message: 'Request body (JSON):',
-      placeholder: '{"key": "value"} or leave empty',
-    });
-    if (p.isCancel(input)) {
-      p.cancel('Cancelled.');
-      process.exit(0);
-    }
-    if (input.trim()) {
-      try {
-        bodyData = JSON.parse(input);
-      } catch {
-        p.cancel('Invalid JSON.');
-        process.exit(1);
-      }
-    }
-  }
-
-  // 5. Resolve query params
-  const queryParams = parseKeyValuePairs(options.query || []);
-
-  // 6. Resolve template variables in path
-  const { resolvedPath, remainingData } = resolveTemplateVariables(
-    knowledge.path,
-    bodyData,
-    pathVarMap
-  );
-
-  // 7. Show summary
-  console.log();
-  console.log(pc.bold('  Request Summary'));
-  console.log(`  ${colorMethod(knowledge.method)} ${knowledge.baseUrl}${resolvedPath}`);
-  console.log(`  Connection: ${pc.dim(connectionKey)}`);
-  if (Object.keys(remainingData).length > 0) {
-    console.log(`  Body: ${pc.dim(JSON.stringify(remainingData))}`);
-  }
-  if (Object.keys(queryParams).length > 0) {
-    console.log(`  Query: ${pc.dim(JSON.stringify(queryParams))}`);
-  }
-  console.log();
-
-  // 8. Execute
-  const execSpinner = p.spinner();
-  execSpinner.start('Executing...');
-
-  try {
-    const result = await api.executeAction({
-      method: knowledge.method,
-      path: resolvedPath,
-      actionId,
-      connectionKey,
-      data: Object.keys(remainingData).length > 0 ? remainingData : undefined,
-      queryParams: Object.keys(queryParams).length > 0 ? queryParams : undefined,
-      isFormData: options.formData,
-      isFormUrlEncoded: options.formUrlencoded,
-    });
-
-    execSpinner.stop(pc.green('Success'));
-
-    if (options.json) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log();
-      console.log(pc.bold('  Response'));
-      console.log(pc.dim('  ' + '─'.repeat(40)));
-      console.log();
-      console.log(formatResponse(result));
-      console.log();
-    }
-  } catch (error) {
-    execSpinner.stop(pc.red('Failed'));
-    const msg = error instanceof Error ? error.message : 'Unknown error';
-    p.cancel(`Execution failed: ${msg}`);
-    process.exit(1);
-  }
-}
-
-// --- Helpers ---
-
-async function resolveConnection(api: PicaApi, platform: string): Promise<string> {
-  const spinner = p.spinner();
-  spinner.start('Loading connections...');
-
-  const connections = await api.listConnections();
-  const matching = connections.filter(
-    c => c.platform.toLowerCase() === platform.toLowerCase()
-  );
-  spinner.stop(`${matching.length} ${platform} connection${matching.length === 1 ? '' : 's'} found`);
-
-  if (matching.length === 0) {
-    p.cancel(
-      `No ${platform} connections found.\n\n` +
-      `Add one with: ${pc.cyan(`pica connection add ${platform}`)}`
-    );
-    process.exit(1);
-  }
-
-  if (matching.length === 1) {
-    p.log.info(`Using connection: ${pc.dim(matching[0].key)}`);
-    return matching[0].key;
-  }
-
-  const selected = await p.select({
-    message: `Multiple ${platform} connections found. Which one?`,
-    options: matching.map(c => ({
-      value: c.key,
-      label: `${c.key}`,
-      hint: c.state,
-    })),
-  });
-
-  if (p.isCancel(selected)) {
-    p.cancel('Cancelled.');
-    process.exit(0);
-  }
-
-  return selected as string;
-}
-
-function parseKeyValuePairs(pairs: string[]): Record<string, string> {
-  const result: Record<string, string> = {};
-  for (const pair of pairs) {
-    const eqIdx = pair.indexOf('=');
-    if (eqIdx === -1) continue;
-    const key = pair.slice(0, eqIdx);
-    const value = pair.slice(eqIdx + 1);
-    result[key] = value;
-  }
-  return result;
-}
-
-function formatResponse(data: unknown, indent = 2): string {
-  const prefix = ' '.repeat(indent);
-  const json = JSON.stringify(data, null, 2);
-  return json.split('\n').map(line => `${prefix}${line}`).join('\n');
-}