Pica Actions CLI Workflow

You have access to the Pica CLI which lets you interact with 200+ third-party platforms through their APIs. The CLI handles authentication, request building, and execution through Pica's passthrough proxy.

The Workflow

Always follow this sequence — each step builds on the previous one:

1. List connections to see what platforms the user has connected
2. Search actions to find the right API action for what the user wants to do
3. Get knowledge to understand the action's parameters, requirements, and structure
4. Execute the action with the correct parameters

Never skip the knowledge step before executing — it contains critical information about required parameters, validation rules, and request structure that you need to build a correct request.

Commands

1. List Connections

pica connection list

Shows all connected platforms with their status and connection keys. You need the connection key for executing actions, and the platform name (kebab-case) for searching actions.

2. Search Actions

pica actions search <platform> <query>

Search for actions on a specific platform using natural language. Returns up to 5 matching actions with their action IDs, HTTP methods, and paths.

• <platform> — Platform name in kebab-case exactly as shown in the connections list (e.g., gmail, shopify, hub-spot)
• <query> — Natural language description of what you want to do (e.g., "send email", "list contacts", "create order")

Options:

• -t, --type <execute|knowledge> — Use execute when the user wants to perform an action, knowledge when they want documentation or want to write code. Defaults to knowledge.

Example:

pica actions search gmail "send email" -t execute

3. Get Action Knowledge

pica actions knowledge <platform> <actionId>

Get comprehensive documentation for an action including parameters, requirements, validation rules, request/response structure, and examples. The output includes the full API request structure guidance.

Always call this before executing — it tells you exactly what parameters are required and how to structure the request.

Example:

pica actions knowledge gmail 67890abcdef

4. Execute Action

pica actions execute <platform> <actionId> <connectionKey> [options]

Execute an action on a connected platform. You must have retrieved the knowledge for this action first.

• <platform> — Platform name in kebab-case
• <actionId> — Action ID from the search results
• <connectionKey> — Connection key from pica connection list

Options:

• -d, --data <json> — Request body as JSON string (for POST, PUT, PATCH)
• --path-vars <json> — Path variables as JSON (for URLs with {id} placeholders)
• --query-params <json> — Query parameters as JSON
• --headers <json> — Additional headers as JSON
• --form-data — Send as multipart/form-data instead of JSON
• --form-url-encoded — Send as application/x-www-form-urlencoded

Examples:

# Simple GET request
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 and query params
pica actions execute shopify <actionId> <connectionKey> \
  --path-vars '{"order_id": "12345"}' \
  --query-params '{"limit": "10"}'

Important Notes

• Platform names are always kebab-case (e.g., hub-spot not HubSpot, ship-station not ShipStation)
• Always use the exact action ID from search results — don't guess or construct them
• Always read the knowledge output carefully — it tells you which parameters are required vs optional, what format they need to be in, and any caveats specific to that API
• JSON values passed to -d, --path-vars, --query-params, and --headers must be valid JSON strings (use single quotes around the JSON to avoid shell escaping issues)
• If search returns no results, try broader queries (e.g., "list" instead of "list active premium customers")
• The execute command respects access control settings configured via pica config — if execution is blocked, the user may need to adjust their permissions