@picahq/cli 1.9.0 → 1.9.2

package/dist/index.js

@@ -37,9 +37,49 @@ function writeConfig(config) {
   }
   fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 384 });
 }
+function readPicaRc() {
+  const rcPath = path.join(process.cwd(), ".picarc");
+  if (!fs.existsSync(rcPath)) return {};
+  try {
+    const content = fs.readFileSync(rcPath, "utf-8");
+    const result = {};
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const eqIndex = trimmed.indexOf("=");
+      if (eqIndex === -1) continue;
+      const key = trimmed.slice(0, eqIndex).trim();
+      const value = trimmed.slice(eqIndex + 1).trim();
+      result[key] = value;
+    }
+    return result;
+  } catch {
+    return {};
+  }
+}
 function getApiKey() {
-  const config = readConfig();
-  return config?.apiKey ?? null;
+  if (process.env.PICA_SECRET) return process.env.PICA_SECRET;
+  const rc = readPicaRc();
+  if (rc.PICA_SECRET) return rc.PICA_SECRET;
+  return readConfig()?.apiKey ?? null;
+}
+function getAccessControlFromAllSources() {
+  const rc = readPicaRc();
+  const fileAc = getAccessControl();
+  const merged = { ...fileAc };
+  if (rc.PICA_PERMISSIONS) {
+    merged.permissions = rc.PICA_PERMISSIONS;
+  }
+  if (rc.PICA_CONNECTION_KEYS) {
+    merged.connectionKeys = rc.PICA_CONNECTION_KEYS.split(",").map((s) => s.trim()).filter(Boolean);
+  }
+  if (rc.PICA_ACTION_IDS) {
+    merged.actionIds = rc.PICA_ACTION_IDS.split(",").map((s) => s.trim()).filter(Boolean);
+  }
+  if (rc.PICA_KNOWLEDGE_AGENT) {
+    merged.knowledgeAgent = rc.PICA_KNOWLEDGE_AGENT === "true";
+  }
+  return merged;
 }
 function getAccessControl() {
   return readConfig()?.accessControl ?? {};
@@ -1568,7 +1608,7 @@ function getConfig() {
     p5.cancel("Not configured. Run `pica init` first.");
     process.exit(1);
   }
-  const ac = getAccessControl();
+  const ac = getAccessControlFromAllSources();
   const permissions = ac.permissions || "admin";
   const connectionKeys = ac.connectionKeys || ["*"];
   const actionIds = ac.actionIds || ["*"];
@@ -1797,7 +1837,34 @@ function colorMethod(method) {
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
 var program = new Command();
-program.name("pica").description("CLI for managing Pica").version(version);
+program.name("pica").description(`Pica CLI \u2014 Connect AI agents to 200+ platforms through one interface.
+
+  Setup:
+    pica init                              Set up API key and install MCP server
+    pica add <platform>                    Connect a platform via OAuth (e.g. gmail, slack, shopify)
+    pica config                            Configure access control (permissions, scoping)
+
+  Workflow (use these in order):
+    1. pica list                           List your connected platforms and connection keys
+    2. pica actions search <platform> <q>  Search for actions using natural language
+    3. pica actions knowledge <plat> <id>  Get full docs for an action (ALWAYS do this before execute)
+    4. pica actions execute <p> <id> <key> Execute the action
+
+  Example \u2014 send an email through Gmail:
+    $ pica list
+    # Find: gmail  operational  live::gmail::default::abc123
+
+    $ pica actions search gmail "send email" -t execute
+    # Find: POST  Send Email  conn_mod_def::xxx::yyy
+
+    $ pica actions knowledge gmail conn_mod_def::xxx::yyy
+    # Read the docs: required fields are to, subject, body, connectionKey
+
+    $ pica actions execute gmail conn_mod_def::xxx::yyy live::gmail::default::abc123 \\
+        -d '{"to":"j@example.com","subject":"Hello","body":"Hi!","connectionKey":"live::gmail::default::abc123"}'
+
+  Platform names are always kebab-case (e.g. hub-spot, ship-station, google-calendar).
+  Run 'pica platforms' to browse all 200+ available platforms.`).version(version);
 program.command("init").description("Set up Pica and install MCP to your AI agents").option("-y, --yes", "Skip confirmations").option("-g, --global", "Install MCP globally (available in all projects)").option("-p, --project", "Install MCP for this project only (creates .mcp.json)").action(async (options) => {
   await initCommand(options);
 });
@@ -1814,14 +1881,14 @@ 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) => {
+var actions = program.command("actions").alias("a").description("Search, explore, and execute platform actions (workflow: search \u2192 knowledge \u2192 execute)");
+actions.command("search <platform> <query>").description('Search for actions on a platform (e.g. pica actions search gmail "send email")').option("-t, --type <type>", "execute (to run it) or knowledge (to learn about it). 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) => {
+actions.command("knowledge <platform> <actionId>").alias("k").description("Get full docs for an action \u2014 MUST call before execute to know required params").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) => {
+actions.command("execute <platform> <actionId> <connectionKey>").alias("x").description('Execute an action \u2014 pass connectionKey from "pica list", actionId from "actions search"').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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@picahq/cli",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "description": "CLI for managing Pica",
   "type": "module",
   "files": [