@picahq/cli 1.8.0 → 1.9.0

package/README.md

@@ -1,163 +1,234 @@
-# pica
+# Pica CLI
 
-CLI for managing Pica integrations. Connect to 200+ platforms, discover their APIs, and execute actions from the terminal.
+One CLI to connect AI agents to every API on the internet.
+
+Pica gives your AI agent authenticated access to 200+ platforms — Gmail, Slack, Shopify, HubSpot, Stripe, Notion, and everything else — through a single interface. No API keys to juggle, no OAuth flows to build, no request formats to memorize. Connect a platform once, and your agent can search for actions, read the docs, and execute API calls in seconds.
 
 ## Install
 
 ```bash
-npm install
-npm run build
-npm link
+npx @picahq/cli@latest init
 ```
 
-Requires Node.js 18+.
-
-## Setup
+Or install globally:
 
 ```bash
+npm install -g @picahq/cli
 pica init
 ```
 
-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
+`pica init` walks you through setup: enter your [API key](https://app.picaos.com/settings/api-keys), pick your AI agents, and you're done. The MCP server gets installed automatically.
 
-Get your API key at [app.picaos.com/settings/api-keys](https://app.picaos.com/settings/api-keys).
+Requires Node.js 18+.
+
+## Quick start
+
+```bash
+# Connect a platform
+pica add gmail
 
-Config is saved to `~/.pica/config.json`.
+# See what you're connected to
+pica list
 
-### Re-running init
+# Search for actions you can take
+pica actions search gmail "send email" -t execute
 
-If you already have a config, `pica init` shows your current setup instead of starting over:
+# Read the docs for an action
+pica actions knowledge gmail <actionId>
 
+# Execute it
+pica actions execute gmail <actionId> <connectionKey> \
+  -d '{"to": "jane@example.com", "subject": "Hello", "body": "Sent from my AI agent"}'
 ```
- Pica
 
-  Current Setup
-  ──────────────────────────────────────────
-  API Key:  sk_test_...9j-Y
-  Config:   ~/.pica/config.json
+That's it. Five commands to go from zero to sending an email through Gmail's API — fully authenticated, correctly formatted, without touching a single OAuth token.
 
-  Agent           Global  Project
-  ──────────────  ──────  ───────
-  Claude Code     ● yes   ● yes
-  Claude Desktop  ● yes   -
-  Cursor          ○ no    ○ no
-  Windsurf        -       -
-  Codex           ● yes   ○ no
-  Kiro            ○ no    ○ no
+## How it works
 
-  - = not detected on this machine
+```
+Your AI Agent
+    ↓
+  Pica CLI
+    ↓
+  Pica API (api.picaos.com/v1/passthrough)
+    ↓
+  Gmail / Slack / Shopify / HubSpot / Stripe / ...
 ```
 
-Then it offers targeted actions based on what's missing:
+Every API call routes through Pica's passthrough proxy. Pica injects the right credentials, handles rate limiting, and normalizes responses. You never see or manage raw OAuth tokens — your connection key is all you need.
 
-- **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` / `.codex/config.toml` / `.kiro/settings/mcp.json` in cwd for agents that support project scope
-- **Start fresh** -- full setup flow from scratch
+## Commands
 
-Options that don't apply are hidden. If every detected agent already has the MCP globally, "Install MCP to more agents" won't appear.
+### `pica init`
 
-### Init flags
+Set up your API key and install the MCP server into your AI agents.
 
-| 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) |
+```bash
+pica init
+```
+
+Supports Claude Code, Claude Desktop, Cursor, Windsurf, Codex, and Kiro. Installs globally by default, or per-project with `-p` so your team can share configs (each person uses their own API key).
+
+If you've already set up, `pica init` shows your current status and lets you update your key, install to more agents, or reconfigure.
+
+| Flag | What it does |
+|------|-------------|
+| `-y` | Skip confirmations |
+| `-g` | Install globally (default) |
+| `-p` | Install for current project only |
 
-## Usage
+### `pica add <platform>`
 
-### Connect a platform
+Connect a new platform via OAuth.
 
 ```bash
+pica add shopify
+pica add hub-spot
 pica add gmail
 ```
 
-Opens a browser to complete OAuth. The CLI polls until the connection is live.
+Opens your browser, you authorize, done. The CLI polls until the connection is live. Platform names are kebab-case — run `pica platforms` to see them all.
 
-### List connections
+### `pica list`
+
+List your active connections with their status and connection keys.
 
 ```bash
 pica list
 ```
 
 ```
-  ● gmail      operational
-    live::gmail::default::abc123
-  ● slack      operational
-    live::slack::default::def456
+  ● gmail       operational   live::gmail::default::abc123
+  ● slack       operational   live::slack::default::def456
+  ● shopify     operational   live::shopify::default::ghi789
 ```
 
-### Browse platforms
+You need the connection key (rightmost column) when executing actions.
+
+### `pica platforms`
+
+Browse all 200+ available platforms.
 
 ```bash
-pica platforms
-pica platforms -c "CRM"
+pica platforms              # all platforms
+pica platforms -c "CRM"     # filter by category
+pica platforms --json       # machine-readable output
 ```
 
-## Commands
+### `pica actions search <platform> <query>`
+
+Search for API actions on a connected platform using natural language.
 
-| 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 |
+```bash
+pica actions search shopify "list products"
+pica actions search hub-spot "create contact" -t execute
+pica actions search gmail "send email"
+```
 
-Every command supports `--json` for machine-readable output.
+Returns the top 5 matching actions with their action IDs, HTTP methods, and paths. Use `-t execute` when you intend to run the action, or `-t knowledge` (default) when you want to learn about it or write code against it.
 
-### Aliases
+### `pica actions knowledge <platform> <actionId>`
 
-| Short | Full |
-|-------|------|
-| `pica ls` | `pica list` |
-| `pica p` | `pica platforms` |
+Get the full documentation for an action — parameters, validation rules, request/response structure, examples, and the exact API request format.
 
-## How it works
+```bash
+pica actions knowledge shopify 67890abcdef
+```
+
+Always read the knowledge before executing. It tells you exactly what parameters are required, what format they need, and any platform-specific quirks.
+
+### `pica actions execute <platform> <actionId> <connectionKey>`
+
+Execute an API action on a connected platform.
+
+```bash
+# Simple GET
+pica actions execute shopify <actionId> <connectionKey>
+
+# POST with data
+pica actions execute hub-spot <actionId> <connectionKey> \
+  -d '{"properties": {"email": "jane@example.com", "firstname": "Jane"}}'
+
+# With path variables
+pica actions execute shopify <actionId> <connectionKey> \
+  --path-vars '{"order_id": "12345"}'
+
+# With query params
+pica actions execute stripe <actionId> <connectionKey> \
+  --query-params '{"limit": "10"}'
+```
+
+| Option | What it does |
+|--------|-------------|
+| `-d, --data <json>` | Request body (POST, PUT, PATCH) |
+| `--path-vars <json>` | Replace `{variables}` in the URL path |
+| `--query-params <json>` | Query string parameters |
+| `--headers <json>` | Additional request headers |
+| `--form-data` | Send as multipart/form-data |
+| `--form-url-encoded` | Send as application/x-www-form-urlencoded |
+
+### `pica config`
+
+Configure access control for the MCP server. Optional — full access is the default.
+
+```bash
+pica config
+```
+
+| Setting | Options | Default |
+|---------|---------|---------|
+| Permission level | `admin` / `write` / `read` | `admin` |
+| Connection scope | All or specific connections | All |
+| Action scope | All or specific action IDs | All |
+| Knowledge-only mode | Enable/disable execution | Off |
+
+Settings propagate automatically to all installed agent configs.
+
+## The workflow
+
+The power of Pica is in the workflow. Every interaction follows the same pattern:
+
+```
+pica list                    → What am I connected to?
+pica actions search          → What can I do?
+pica actions knowledge       → How do I do it?
+pica actions execute         → Do it.
+```
+
+This is the same workflow whether you're sending emails, creating CRM contacts, processing payments, managing inventory, or posting to Slack. One pattern, any platform.
+
+## For AI agents
+
+If you're an AI agent using the Pica MCP server, the tools map directly:
+
+| MCP Tool | CLI Command |
+|----------|------------|
+| `list_pica_integrations` | `pica list` + `pica platforms` |
+| `search_pica_platform_actions` | `pica actions search` |
+| `get_pica_action_knowledge` | `pica actions knowledge` |
+| `execute_pica_action` | `pica actions execute` |
 
-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.
+The workflow is the same: list → search → knowledge → execute. Never skip the knowledge step — it contains required parameter info and platform-specific details that are critical for building correct requests.
 
-## MCP installation
+## MCP server installation
 
-`pica init` writes MCP server configs into the following locations:
+`pica init` handles this automatically. Here's where configs go:
 
-| Agent | Global config | Project config |
-|-------|--------------|----------------|
+| Agent | Global | Project |
+|-------|--------|---------|
 | Claude Code | `~/.claude.json` | `.mcp.json` |
-| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | n/a |
+| Claude Desktop | Platform-specific app support dir | — |
 | Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` |
-| Windsurf | `~/.codeium/windsurf/mcp_config.json` | n/a |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | — |
 | Codex | `~/.codex/config.toml` | `.codex/config.toml` |
 | Kiro | `~/.kiro/settings/mcp.json` | `.kiro/settings/mcp.json` |
 
-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).
+Project configs can be committed to your repo. Each team member runs `pica init` with their own API key.
 
 ## 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 (setup, status display, targeted actions)
-    connection.ts       # pica add, pica list
-    platforms.ts        # pica platforms
-  lib/
-    api.ts              # HTTP client for Pica API
-    types.ts            # TypeScript interfaces
-    config.ts           # ~/.pica/config.json read/write
-    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
+npm run typecheck  # type check
 ```

package/dist/index.js

@@ -73,11 +73,11 @@ import fs2 from "fs";
 import path2 from "path";
 import os2 from "os";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
-function expandPath(p5) {
-  if (p5.startsWith("~/")) {
-    return path2.join(os2.homedir(), p5.slice(2));
+function expandPath(p6) {
+  if (p6.startsWith("~/")) {
+    return path2.join(os2.homedir(), p6.slice(2));
   }
-  return p5;
+  return p6;
 }
 function getClaudeDesktopConfigPath() {
   switch (process.platform) {
@@ -320,6 +320,140 @@ var PicaApi = class {
     } while (page <= totalPages);
     return allPlatforms;
   }
+  async searchActions(platform, query, agentType) {
+    const isKnowledgeAgent = !agentType || agentType === "knowledge";
+    const queryParams = {
+      query,
+      limit: "5"
+    };
+    if (isKnowledgeAgent) {
+      queryParams.knowledgeAgent = "true";
+    } else {
+      queryParams.executeAgent = "true";
+    }
+    const response = await this.requestFull({
+      path: `/available-actions/search/${platform}`,
+      queryParams
+    });
+    return response || [];
+  }
+  async getActionDetails(actionId) {
+    const response = await this.requestFull({
+      path: "/knowledge",
+      queryParams: { _id: actionId }
+    });
+    const actions2 = response?.rows || [];
+    if (actions2.length === 0) {
+      throw new ApiError(404, `Action with ID ${actionId} not found`);
+    }
+    return actions2[0];
+  }
+  async getActionKnowledge(actionId) {
+    const action = await this.getActionDetails(actionId);
+    if (!action.knowledge || !action.method) {
+      return {
+        knowledge: "No knowledge was found",
+        method: "No method was found"
+      };
+    }
+    return {
+      knowledge: action.knowledge,
+      method: action.method
+    };
+  }
+  async executePassthroughRequest(args, preloadedAction) {
+    const action = preloadedAction ?? await this.getActionDetails(args.actionId);
+    const method = action.method;
+    const contentType = args.isFormData ? "multipart/form-data" : args.isFormUrlEncoded ? "application/x-www-form-urlencoded" : "application/json";
+    const requestHeaders = {
+      "x-pica-secret": this.apiKey,
+      "x-pica-connection-key": args.connectionKey,
+      "x-pica-action-id": action._id,
+      "Content-Type": contentType,
+      ...args.headers
+    };
+    const finalActionPath = args.pathVariables ? replacePathVariables(action.path, args.pathVariables) : action.path;
+    const normalizedPath = finalActionPath.startsWith("/") ? finalActionPath : `/${finalActionPath}`;
+    const url = `${API_BASE.replace("/v1", "")}/v1/passthrough${normalizedPath}`;
+    const isCustomAction = action.tags?.includes("custom");
+    let requestData = args.data;
+    if (isCustomAction && method?.toLowerCase() !== "get") {
+      requestData = {
+        ...args.data,
+        connectionKey: args.connectionKey
+      };
+    }
+    let queryString = "";
+    if (args.queryParams && Object.keys(args.queryParams).length > 0) {
+      const params = new URLSearchParams(
+        Object.entries(args.queryParams).map(([k, v]) => [k, String(v)])
+      );
+      queryString = `?${params.toString()}`;
+    }
+    const fullUrl = `${url}${queryString}`;
+    const fetchOpts = {
+      method,
+      headers: requestHeaders
+    };
+    if (method?.toLowerCase() !== "get" && requestData !== void 0) {
+      if (args.isFormUrlEncoded) {
+        const params = new URLSearchParams();
+        if (requestData && typeof requestData === "object" && !Array.isArray(requestData)) {
+          Object.entries(requestData).forEach(([key, value]) => {
+            if (typeof value === "object") {
+              params.append(key, JSON.stringify(value));
+            } else {
+              params.append(key, String(value));
+            }
+          });
+        }
+        fetchOpts.body = params.toString();
+      } else if (args.isFormData) {
+        const boundary = `----FormBoundary${Date.now()}`;
+        requestHeaders["Content-Type"] = `multipart/form-data; boundary=${boundary}`;
+        let body = "";
+        if (requestData && typeof requestData === "object" && !Array.isArray(requestData)) {
+          Object.entries(requestData).forEach(([key, value]) => {
+            body += `--${boundary}\r
+`;
+            body += `Content-Disposition: form-data; name="${key}"\r
+\r
+`;
+            body += typeof value === "object" ? JSON.stringify(value) : String(value);
+            body += "\r\n";
+          });
+        }
+        body += `--${boundary}--\r
+`;
+        fetchOpts.body = body;
+        fetchOpts.headers = requestHeaders;
+      } else {
+        fetchOpts.body = JSON.stringify(requestData);
+      }
+    }
+    const sanitizedConfig = {
+      url: fullUrl,
+      method,
+      headers: {
+        ...requestHeaders,
+        "x-pica-secret": "***REDACTED***"
+      },
+      params: args.queryParams ? Object.fromEntries(
+        Object.entries(args.queryParams).map(([k, v]) => [k, String(v)])
+      ) : void 0,
+      data: requestData
+    };
+    const response = await fetch(fullUrl, fetchOpts);
+    if (!response.ok) {
+      const text4 = await response.text();
+      throw new ApiError(response.status, text4 || `HTTP ${response.status}`);
+    }
+    const responseData = await response.json();
+    return {
+      requestConfig: sanitizedConfig,
+      responseData
+    };
+  }
   async waitForConnection(platform, timeoutMs = 5 * 60 * 1e3, pollIntervalMs = 5e3, onPoll) {
     const startTime = Date.now();
     const existingConnections = await this.listConnections();
@@ -347,6 +481,72 @@ var TimeoutError = class extends Error {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function replacePathVariables(path3, variables) {
+  if (!path3) return path3;
+  let result = path3;
+  result = result.replace(/\{\{([^}]+)\}\}/g, (_match, variable) => {
+    const trimmedVariable = variable.trim();
+    const value = variables[trimmedVariable];
+    if (value === void 0 || value === null || value === "") {
+      throw new Error(`Missing value for path variable: ${trimmedVariable}`);
+    }
+    return encodeURIComponent(value.toString());
+  });
+  result = result.replace(/\{([^}]+)\}/g, (_match, variable) => {
+    const trimmedVariable = variable.trim();
+    const value = variables[trimmedVariable];
+    if (value === void 0 || value === null || value === "") {
+      throw new Error(`Missing value for path variable: ${trimmedVariable}`);
+    }
+    return encodeURIComponent(value.toString());
+  });
+  return result;
+}
+var PERMISSION_METHODS = {
+  read: ["GET"],
+  write: ["GET", "POST", "PUT", "PATCH"],
+  admin: null
+};
+function filterByPermissions(actions2, permissions) {
+  const allowed = PERMISSION_METHODS[permissions];
+  if (allowed === null) return actions2;
+  return actions2.filter((a) => allowed.includes(a.method.toUpperCase()));
+}
+function isMethodAllowed(method, permissions) {
+  const allowed = PERMISSION_METHODS[permissions];
+  if (allowed === null) return true;
+  return allowed.includes(method.toUpperCase());
+}
+function isActionAllowed(actionId, allowedActionIds) {
+  return allowedActionIds.includes("*") || allowedActionIds.includes(actionId);
+}
+function buildActionKnowledgeWithGuidance(knowledge, method, platform, actionId) {
+  const baseUrl = "https://api.picaos.com";
+  return `${knowledge}
+
+API REQUEST STRUCTURE
+======================
+URL: ${baseUrl}/v1/passthrough/{{PATH}}
+
+IMPORTANT: When constructing the URL, only include the API endpoint path after the base URL.
+Do NOT include the full third-party API URL.
+
+Examples:
+  Correct: ${baseUrl}/v1/passthrough/crm/v3/objects/contacts/search
+  Incorrect: ${baseUrl}/v1/passthrough/https://api.hubapi.com/crm/v3/objects/contacts/search
+
+METHOD: ${method}
+
+HEADERS:
+- x-pica-secret: {{process.env.PICA_SECRET}}
+- x-pica-connection-key: {{process.env.PICA_${platform.toUpperCase()}_CONNECTION_KEY}}
+- x-pica-action-id: ${actionId}
+- ... (other headers)
+
+BODY: {{BODY}}
+
+QUERY PARAMS: {{QUERY_PARAMS}}`;
+}
 
 // src/lib/browser.ts
 import open from "open";
@@ -484,16 +684,16 @@ async function configCommand() {
   p.outro("Access control updated.");
 }
 async function selectConnections(apiKey) {
-  const spinner5 = p.spinner();
-  spinner5.start("Fetching connections...");
+  const spinner6 = p.spinner();
+  spinner6.start("Fetching connections...");
   let connections;
   try {
     const api = new PicaApi(apiKey);
     const rawConnections = await api.listConnections();
     connections = rawConnections.map((c) => ({ platform: c.platform, key: c.key }));
-    spinner5.stop(`Found ${connections.length} connection(s)`);
+    spinner6.stop(`Found ${connections.length} connection(s)`);
   } catch {
-    spinner5.stop("Could not fetch connections");
+    spinner6.stop("Could not fetch connections");
     const manual = await p.text({
       message: "Enter connection keys manually (comma-separated):",
       placeholder: "conn_key_1, conn_key_2",
@@ -695,16 +895,16 @@ ${pc3.cyan(getApiKeyUrl())}`, "API Key");
     p2.cancel("Cancelled.");
     process.exit(0);
   }
-  const spinner5 = p2.spinner();
-  spinner5.start("Validating API key...");
+  const spinner6 = p2.spinner();
+  spinner6.start("Validating API key...");
   const api = new PicaApi(newKey);
   const isValid = await api.validateApiKey();
   if (!isValid) {
-    spinner5.stop("Invalid API key");
+    spinner6.stop("Invalid API key");
     p2.cancel(`Invalid API key. Get a valid key at ${getApiKeyUrl()}`);
     process.exit(1);
   }
-  spinner5.stop("API key validated");
+  spinner6.stop("API key validated");
   const ac = getAccessControl();
   const reinstalled = [];
   for (const s of statuses) {
@@ -840,16 +1040,16 @@ ${pc3.cyan(getApiKeyUrl())}`, "API Key");
     p2.cancel("Setup cancelled.");
     process.exit(0);
   }
-  const spinner5 = p2.spinner();
-  spinner5.start("Validating API key...");
+  const spinner6 = p2.spinner();
+  spinner6.start("Validating API key...");
   const api = new PicaApi(apiKey);
   const isValid = await api.validateApiKey();
   if (!isValid) {
-    spinner5.stop("Invalid API key");
+    spinner6.stop("Invalid API key");
     p2.cancel(`Invalid API key. Get a valid key at ${getApiKeyUrl()}`);
     process.exit(1);
   }
-  spinner5.stop("API key validated");
+  spinner6.stop("API key validated");
   writeConfig({
     apiKey,
     installedAgents: [],
@@ -1049,16 +1249,16 @@ async function promptConnectIntegrations(apiKey) {
       p2.log.warn("Could not open browser automatically.");
       p2.note(url, "Open manually");
     }
-    const spinner5 = p2.spinner();
-    spinner5.start("Waiting for connection... (complete auth in browser)");
+    const spinner6 = p2.spinner();
+    spinner6.start("Waiting for connection... (complete auth in browser)");
     try {
       await api.waitForConnection(platform, 5 * 60 * 1e3, 5e3);
-      spinner5.stop(`${label} connected!`);
+      spinner6.stop(`${label} connected!`);
       p2.log.success(`${pc3.green("\u2713")} ${label} is now available to your AI agents`);
       connected.push(platform);
       first = false;
     } catch (error) {
-      spinner5.stop("Connection timed out");
+      spinner6.stop("Connection timed out");
       if (error instanceof TimeoutError) {
         p2.log.warn(`No worries. Connect later with: ${pc3.cyan(`pica add ${platform}`)}`);
       }
@@ -1091,16 +1291,16 @@ import pc4 from "picocolors";
 function findPlatform(platforms, query) {
   const normalizedQuery = query.toLowerCase().trim();
   const exact = platforms.find(
-    (p5) => p5.platform.toLowerCase() === normalizedQuery || p5.name.toLowerCase() === normalizedQuery
+    (p6) => p6.platform.toLowerCase() === normalizedQuery || p6.name.toLowerCase() === normalizedQuery
   );
   if (exact) return exact;
   return null;
 }
 function findSimilarPlatforms(platforms, query, limit = 3) {
   const normalizedQuery = query.toLowerCase().trim();
-  const scored = platforms.map((p5) => {
-    const name = p5.name.toLowerCase();
-    const slug = p5.platform.toLowerCase();
+  const scored = platforms.map((p6) => {
+    const name = p6.name.toLowerCase();
+    const slug = p6.platform.toLowerCase();
     let score = 0;
     if (name.includes(normalizedQuery) || slug.includes(normalizedQuery)) {
       score = 10;
@@ -1109,7 +1309,7 @@ function findSimilarPlatforms(platforms, query, limit = 3) {
     } else {
       score = countMatchingChars(normalizedQuery, slug);
     }
-    return { platform: p5, score };
+    return { platform: p6, score };
   }).filter((item) => item.score > 0).sort((a, b) => b.score - a.score).slice(0, limit);
   return scored.map((item) => item.platform);
 }
@@ -1131,14 +1331,14 @@ async function connectionAddCommand(platformArg) {
     process.exit(1);
   }
   const api = new PicaApi(apiKey);
-  const spinner5 = p3.spinner();
-  spinner5.start("Loading platforms...");
+  const spinner6 = p3.spinner();
+  spinner6.start("Loading platforms...");
   let platforms;
   try {
     platforms = await api.listPlatforms();
-    spinner5.stop(`${platforms.length} platforms available`);
+    spinner6.stop(`${platforms.length} platforms available`);
   } catch (error) {
-    spinner5.stop("Failed to load platforms");
+    spinner6.stop("Failed to load platforms");
     p3.cancel(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
     process.exit(1);
   }
@@ -1236,11 +1436,11 @@ async function connectionListCommand() {
     process.exit(1);
   }
   const api = new PicaApi(apiKey);
-  const spinner5 = p3.spinner();
-  spinner5.start("Loading connections...");
+  const spinner6 = p3.spinner();
+  spinner6.start("Loading connections...");
   try {
     const connections = await api.listConnections();
-    spinner5.stop(`${connections.length} connection${connections.length === 1 ? "" : "s"} found`);
+    spinner6.stop(`${connections.length} connection${connections.length === 1 ? "" : "s"} found`);
     if (connections.length === 0) {
       p3.note(
         `No connections yet.
@@ -1269,7 +1469,7 @@ Add one with: ${pc4.cyan("pica connection add gmail")}`,
     console.log();
     p3.note(`Add more with: ${pc4.cyan("pica connection add <platform>")}`, "Tip");
   } catch (error) {
-    spinner5.stop("Failed to load connections");
+    spinner6.stop("Failed to load connections");
     p3.cancel(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
     process.exit(1);
   }
@@ -1297,11 +1497,11 @@ async function platformsCommand(options) {
     process.exit(1);
   }
   const api = new PicaApi(apiKey);
-  const spinner5 = p4.spinner();
-  spinner5.start("Loading platforms...");
+  const spinner6 = p4.spinner();
+  spinner6.start("Loading platforms...");
   try {
     const platforms = await api.listPlatforms();
-    spinner5.stop(`${platforms.length} platforms available`);
+    spinner6.stop(`${platforms.length} platforms available`);
     if (options.json) {
       console.log(JSON.stringify(platforms, null, 2));
       return;
@@ -1353,12 +1553,246 @@ async function platformsCommand(options) {
     console.log();
     p4.note(`Connect with: ${pc5.cyan("pica connection add <platform>")}`, "Tip");
   } catch (error) {
-    spinner5.stop("Failed to load platforms");
+    spinner6.stop("Failed to load platforms");
     p4.cancel(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
     process.exit(1);
   }
 }
 
+// src/commands/actions.ts
+import * as p5 from "@clack/prompts";
+import pc6 from "picocolors";
+function getConfig() {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    p5.cancel("Not configured. Run `pica init` first.");
+    process.exit(1);
+  }
+  const ac = getAccessControl();
+  const permissions = ac.permissions || "admin";
+  const connectionKeys = ac.connectionKeys || ["*"];
+  const actionIds = ac.actionIds || ["*"];
+  const knowledgeAgent = ac.knowledgeAgent || false;
+  return { apiKey, permissions, connectionKeys, actionIds, knowledgeAgent };
+}
+async function actionsSearchCommand(platform, query, options) {
+  p5.intro(pc6.bgCyan(pc6.black(" Pica ")));
+  const { apiKey, permissions, actionIds, knowledgeAgent } = getConfig();
+  const api = new PicaApi(apiKey);
+  const spinner6 = p5.spinner();
+  spinner6.start(`Searching actions on ${pc6.cyan(platform)} for "${query}"...`);
+  try {
+    const agentType = knowledgeAgent ? "knowledge" : options.type;
+    let actions2 = await api.searchActions(platform, query, agentType);
+    actions2 = filterByPermissions(actions2, permissions);
+    actions2 = actions2.filter((a) => isActionAllowed(a.systemId, actionIds));
+    const cleanedActions = actions2.map((action) => ({
+      actionId: action.systemId,
+      title: action.title,
+      method: action.method,
+      path: action.path
+    }));
+    if (cleanedActions.length === 0) {
+      spinner6.stop("No actions found");
+      p5.note(
+        `No actions found for platform '${platform}' matching query '${query}'.
+
+Suggestions:
+  - Try a more general query (e.g., 'list', 'get', 'search', 'create')
+  - Verify the platform name is correct
+  - Check available platforms with ${pc6.cyan("pica platforms")}
+
+Examples of good queries:
+  - "search contacts"
+  - "send email"
+  - "create customer"
+  - "list orders"`,
+        "No Results"
+      );
+      return;
+    }
+    spinner6.stop(
+      `Found ${cleanedActions.length} action(s) for '${platform}' matching '${query}'`
+    );
+    console.log();
+    const rows = cleanedActions.map((a) => ({
+      method: colorMethod(a.method),
+      title: a.title,
+      actionId: a.actionId,
+      path: a.path
+    }));
+    printTable(
+      [
+        { key: "method", label: "Method" },
+        { key: "title", label: "Title" },
+        { key: "actionId", label: "Action ID", color: pc6.dim },
+        { key: "path", label: "Path", color: pc6.dim }
+      ],
+      rows
+    );
+    console.log();
+    p5.note(
+      `Get details: ${pc6.cyan(`pica actions knowledge ${platform} <actionId>`)}
+Execute:     ${pc6.cyan(`pica actions execute ${platform} <actionId> <connectionKey>`)}`,
+      "Next Steps"
+    );
+  } catch (error) {
+    spinner6.stop("Search failed");
+    p5.cancel(
+      `Error: ${error instanceof Error ? error.message : "Unknown error"}`
+    );
+    process.exit(1);
+  }
+}
+async function actionsKnowledgeCommand(platform, actionId) {
+  p5.intro(pc6.bgCyan(pc6.black(" Pica ")));
+  const { apiKey, actionIds, connectionKeys } = getConfig();
+  const api = new PicaApi(apiKey);
+  if (!isActionAllowed(actionId, actionIds)) {
+    p5.cancel(`Action "${actionId}" is not in the allowed action list.`);
+    process.exit(1);
+  }
+  if (!connectionKeys.includes("*")) {
+    const spinner7 = p5.spinner();
+    spinner7.start("Checking connections...");
+    try {
+      const connections = await api.listConnections();
+      const connectedPlatforms = connections.map((c) => c.platform);
+      if (!connectedPlatforms.includes(platform)) {
+        spinner7.stop("Platform not connected");
+        p5.cancel(`Platform "${platform}" has no allowed connections.`);
+        process.exit(1);
+      }
+      spinner7.stop("Connection verified");
+    } catch (error) {
+      spinner7.stop("Failed to check connections");
+      p5.cancel(
+        `Error: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+      process.exit(1);
+    }
+  }
+  const spinner6 = p5.spinner();
+  spinner6.start(`Loading knowledge for action ${pc6.dim(actionId)}...`);
+  try {
+    const { knowledge, method } = await api.getActionKnowledge(actionId);
+    const knowledgeWithGuidance = buildActionKnowledgeWithGuidance(
+      knowledge,
+      method,
+      platform,
+      actionId
+    );
+    spinner6.stop("Knowledge loaded");
+    console.log();
+    console.log(knowledgeWithGuidance);
+    console.log();
+    p5.note(
+      `Execute: ${pc6.cyan(`pica actions execute ${platform} ${actionId} <connectionKey>`)}`,
+      "Next Step"
+    );
+  } catch (error) {
+    spinner6.stop("Failed to load knowledge");
+    p5.cancel(
+      `Error: ${error instanceof Error ? error.message : "Unknown error"}`
+    );
+    process.exit(1);
+  }
+}
+async function actionsExecuteCommand(platform, actionId, connectionKey, options) {
+  p5.intro(pc6.bgCyan(pc6.black(" Pica ")));
+  const { apiKey, permissions, actionIds, connectionKeys, knowledgeAgent } = getConfig();
+  if (knowledgeAgent) {
+    p5.cancel(
+      `Action execution is disabled (knowledge-only mode).
+Configure with: ${pc6.cyan("pica config")}`
+    );
+    process.exit(1);
+  }
+  if (!isActionAllowed(actionId, actionIds)) {
+    p5.cancel(`Action "${actionId}" is not in the allowed action list.`);
+    process.exit(1);
+  }
+  if (!connectionKeys.includes("*") && !connectionKeys.includes(connectionKey)) {
+    p5.cancel(`Connection key "${connectionKey}" is not allowed.`);
+    process.exit(1);
+  }
+  const api = new PicaApi(apiKey);
+  const spinner6 = p5.spinner();
+  spinner6.start("Loading action details...");
+  try {
+    const actionDetails = await api.getActionDetails(actionId);
+    if (!isMethodAllowed(actionDetails.method, permissions)) {
+      spinner6.stop("Permission denied");
+      p5.cancel(
+        `Method "${actionDetails.method}" is not allowed under "${permissions}" permission level.`
+      );
+      process.exit(1);
+    }
+    spinner6.stop(`Action: ${actionDetails.title} [${actionDetails.method}]`);
+    const data = options.data ? parseJsonArg(options.data, "--data") : void 0;
+    const pathVariables = options.pathVars ? parseJsonArg(options.pathVars, "--path-vars") : void 0;
+    const queryParams = options.queryParams ? parseJsonArg(options.queryParams, "--query-params") : void 0;
+    const headers = options.headers ? parseJsonArg(options.headers, "--headers") : void 0;
+    const execSpinner = p5.spinner();
+    execSpinner.start("Executing action...");
+    const result = await api.executePassthroughRequest(
+      {
+        platform,
+        actionId,
+        connectionKey,
+        data,
+        pathVariables,
+        queryParams,
+        headers,
+        isFormData: options.formData,
+        isFormUrlEncoded: options.formUrlEncoded
+      },
+      actionDetails
+    );
+    execSpinner.stop("Action executed successfully");
+    console.log();
+    console.log(pc6.dim("Request:"));
+    console.log(
+      pc6.dim(
+        `  ${result.requestConfig.method} ${result.requestConfig.url}`
+      )
+    );
+    console.log();
+    console.log(pc6.bold("Response:"));
+    console.log(JSON.stringify(result.responseData, null, 2));
+  } catch (error) {
+    spinner6.stop("Execution failed");
+    p5.cancel(
+      `Error: ${error instanceof Error ? error.message : "Unknown error"}`
+    );
+    process.exit(1);
+  }
+}
+function parseJsonArg(value, argName) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    p5.cancel(`Invalid JSON for ${argName}: ${value}`);
+    process.exit(1);
+  }
+}
+function colorMethod(method) {
+  switch (method.toUpperCase()) {
+    case "GET":
+      return pc6.green(method);
+    case "POST":
+      return pc6.yellow(method);
+    case "PUT":
+      return pc6.blue(method);
+    case "PATCH":
+      return pc6.magenta(method);
+    case "DELETE":
+      return pc6.red(method);
+    default:
+      return method;
+  }
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -1380,6 +1814,23 @@ connection.command("list").alias("ls").description("List your connections").acti
 program.command("platforms").alias("p").description("List available platforms").option("-c, --category <category>", "Filter by category").option("--json", "Output as JSON").action(async (options) => {
   await platformsCommand(options);
 });
+var actions = program.command("actions").alias("a").description("Search, explore, and execute platform actions");
+actions.command("search <platform> <query>").description("Search for actions on a platform").option("-t, --type <type>", "Agent type: execute or knowledge (default: knowledge)").action(async (platform, query, options) => {
+  await actionsSearchCommand(platform, query, options);
+});
+actions.command("knowledge <platform> <actionId>").alias("k").description("Get detailed documentation for an action").action(async (platform, actionId) => {
+  await actionsKnowledgeCommand(platform, actionId);
+});
+actions.command("execute <platform> <actionId> <connectionKey>").alias("x").description("Execute an action on a connected platform").option("-d, --data <json>", "Request body as JSON").option("--path-vars <json>", "Path variables as JSON").option("--query-params <json>", "Query parameters as JSON").option("--headers <json>", "Additional headers as JSON").option("--form-data", "Send as multipart/form-data").option("--form-url-encoded", "Send as application/x-www-form-urlencoded").action(async (platform, actionId, connectionKey, options) => {
+  await actionsExecuteCommand(platform, actionId, connectionKey, {
+    data: options.data,
+    pathVars: options.pathVars,
+    queryParams: options.queryParams,
+    headers: options.headers,
+    formData: options.formData,
+    formUrlEncoded: options.formUrlEncoded
+  });
+});
 program.command("add [platform]").description("Shortcut for: connection add").action(async (platform) => {
   await connectionAddCommand(platform);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@picahq/cli",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "CLI for managing Pica",
   "type": "module",
   "files": [
@@ -31,4 +31,4 @@
   "engines": {
     "node": ">=18"
   }
-}
+}