@picahq/cli 1.7.0 → 1.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +166 -95
- package/dist/index.js +871 -195
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,163 +1,234 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Pica CLI
|
|
2
2
|
|
|
3
|
-
CLI
|
|
3
|
+
One CLI to connect AI agents to every API on the internet.
|
|
4
|
+
|
|
5
|
+
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.
|
|
4
6
|
|
|
5
7
|
## Install
|
|
6
8
|
|
|
7
9
|
```bash
|
|
8
|
-
|
|
9
|
-
npm run build
|
|
10
|
-
npm link
|
|
10
|
+
npx @picahq/cli@latest init
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
## Setup
|
|
13
|
+
Or install globally:
|
|
16
14
|
|
|
17
15
|
```bash
|
|
16
|
+
npm install -g @picahq/cli
|
|
18
17
|
pica init
|
|
19
18
|
```
|
|
20
19
|
|
|
21
|
-
|
|
22
|
-
1. Entering your Pica API key (validates it)
|
|
23
|
-
2. Choosing which AI agents to install the MCP server into
|
|
24
|
-
3. Choosing global vs project-level installation
|
|
20
|
+
`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.
|
|
25
21
|
|
|
26
|
-
|
|
22
|
+
Requires Node.js 18+.
|
|
23
|
+
|
|
24
|
+
## Quick start
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
# Connect a platform
|
|
28
|
+
pica add gmail
|
|
27
29
|
|
|
28
|
-
|
|
30
|
+
# See what you're connected to
|
|
31
|
+
pica list
|
|
29
32
|
|
|
30
|
-
|
|
33
|
+
# Search for actions you can take
|
|
34
|
+
pica actions search gmail "send email" -t execute
|
|
31
35
|
|
|
32
|
-
|
|
36
|
+
# Read the docs for an action
|
|
37
|
+
pica actions knowledge gmail <actionId>
|
|
33
38
|
|
|
39
|
+
# Execute it
|
|
40
|
+
pica actions execute gmail <actionId> <connectionKey> \
|
|
41
|
+
-d '{"to": "jane@example.com", "subject": "Hello", "body": "Sent from my AI agent"}'
|
|
34
42
|
```
|
|
35
|
-
Pica
|
|
36
43
|
|
|
37
|
-
|
|
38
|
-
──────────────────────────────────────────
|
|
39
|
-
API Key: sk_test_...9j-Y
|
|
40
|
-
Config: ~/.pica/config.json
|
|
44
|
+
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.
|
|
41
45
|
|
|
42
|
-
|
|
43
|
-
────────────── ────── ───────
|
|
44
|
-
Claude Code ● yes ● yes
|
|
45
|
-
Claude Desktop ● yes -
|
|
46
|
-
Cursor ○ no ○ no
|
|
47
|
-
Windsurf - -
|
|
48
|
-
Codex ● yes ○ no
|
|
49
|
-
Kiro ○ no ○ no
|
|
46
|
+
## How it works
|
|
50
47
|
|
|
51
|
-
|
|
48
|
+
```
|
|
49
|
+
Your AI Agent
|
|
50
|
+
↓
|
|
51
|
+
Pica CLI
|
|
52
|
+
↓
|
|
53
|
+
Pica API (api.picaos.com/v1/passthrough)
|
|
54
|
+
↓
|
|
55
|
+
Gmail / Slack / Shopify / HubSpot / Stripe / ...
|
|
52
56
|
```
|
|
53
57
|
|
|
54
|
-
|
|
58
|
+
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.
|
|
55
59
|
|
|
56
|
-
|
|
57
|
-
- **Install MCP to more agents** -- only shows detected agents missing the MCP
|
|
58
|
-
- **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
|
|
59
|
-
- **Start fresh** -- full setup flow from scratch
|
|
60
|
+
## Commands
|
|
60
61
|
|
|
61
|
-
|
|
62
|
+
### `pica init`
|
|
62
63
|
|
|
63
|
-
|
|
64
|
+
Set up your API key and install the MCP server into your AI agents.
|
|
64
65
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
66
|
+
```bash
|
|
67
|
+
pica init
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
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).
|
|
71
|
+
|
|
72
|
+
If you've already set up, `pica init` shows your current status and lets you update your key, install to more agents, or reconfigure.
|
|
73
|
+
|
|
74
|
+
| Flag | What it does |
|
|
75
|
+
|------|-------------|
|
|
76
|
+
| `-y` | Skip confirmations |
|
|
77
|
+
| `-g` | Install globally (default) |
|
|
78
|
+
| `-p` | Install for current project only |
|
|
70
79
|
|
|
71
|
-
|
|
80
|
+
### `pica add <platform>`
|
|
72
81
|
|
|
73
|
-
|
|
82
|
+
Connect a new platform via OAuth.
|
|
74
83
|
|
|
75
84
|
```bash
|
|
85
|
+
pica add shopify
|
|
86
|
+
pica add hub-spot
|
|
76
87
|
pica add gmail
|
|
77
88
|
```
|
|
78
89
|
|
|
79
|
-
Opens
|
|
90
|
+
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.
|
|
80
91
|
|
|
81
|
-
###
|
|
92
|
+
### `pica list`
|
|
93
|
+
|
|
94
|
+
List your active connections with their status and connection keys.
|
|
82
95
|
|
|
83
96
|
```bash
|
|
84
97
|
pica list
|
|
85
98
|
```
|
|
86
99
|
|
|
87
100
|
```
|
|
88
|
-
● gmail
|
|
89
|
-
|
|
90
|
-
●
|
|
91
|
-
live::slack::default::def456
|
|
101
|
+
● gmail operational live::gmail::default::abc123
|
|
102
|
+
● slack operational live::slack::default::def456
|
|
103
|
+
● shopify operational live::shopify::default::ghi789
|
|
92
104
|
```
|
|
93
105
|
|
|
94
|
-
|
|
106
|
+
You need the connection key (rightmost column) when executing actions.
|
|
107
|
+
|
|
108
|
+
### `pica platforms`
|
|
109
|
+
|
|
110
|
+
Browse all 200+ available platforms.
|
|
95
111
|
|
|
96
112
|
```bash
|
|
97
|
-
pica platforms
|
|
98
|
-
pica platforms -c "CRM"
|
|
113
|
+
pica platforms # all platforms
|
|
114
|
+
pica platforms -c "CRM" # filter by category
|
|
115
|
+
pica platforms --json # machine-readable output
|
|
99
116
|
```
|
|
100
117
|
|
|
101
|
-
|
|
118
|
+
### `pica actions search <platform> <query>`
|
|
119
|
+
|
|
120
|
+
Search for API actions on a connected platform using natural language.
|
|
102
121
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
| `pica platforms` | Browse available platforms |
|
|
122
|
+
```bash
|
|
123
|
+
pica actions search shopify "list products"
|
|
124
|
+
pica actions search hub-spot "create contact" -t execute
|
|
125
|
+
pica actions search gmail "send email"
|
|
126
|
+
```
|
|
109
127
|
|
|
110
|
-
|
|
128
|
+
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.
|
|
111
129
|
|
|
112
|
-
###
|
|
130
|
+
### `pica actions knowledge <platform> <actionId>`
|
|
113
131
|
|
|
114
|
-
|
|
115
|
-
|-------|------|
|
|
116
|
-
| `pica ls` | `pica list` |
|
|
117
|
-
| `pica p` | `pica platforms` |
|
|
132
|
+
Get the full documentation for an action — parameters, validation rules, request/response structure, examples, and the exact API request format.
|
|
118
133
|
|
|
119
|
-
|
|
134
|
+
```bash
|
|
135
|
+
pica actions knowledge shopify 67890abcdef
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Always read the knowledge before executing. It tells you exactly what parameters are required, what format they need, and any platform-specific quirks.
|
|
139
|
+
|
|
140
|
+
### `pica actions execute <platform> <actionId> <connectionKey>`
|
|
141
|
+
|
|
142
|
+
Execute an API action on a connected platform.
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
# Simple GET
|
|
146
|
+
pica actions execute shopify <actionId> <connectionKey>
|
|
147
|
+
|
|
148
|
+
# POST with data
|
|
149
|
+
pica actions execute hub-spot <actionId> <connectionKey> \
|
|
150
|
+
-d '{"properties": {"email": "jane@example.com", "firstname": "Jane"}}'
|
|
151
|
+
|
|
152
|
+
# With path variables
|
|
153
|
+
pica actions execute shopify <actionId> <connectionKey> \
|
|
154
|
+
--path-vars '{"order_id": "12345"}'
|
|
155
|
+
|
|
156
|
+
# With query params
|
|
157
|
+
pica actions execute stripe <actionId> <connectionKey> \
|
|
158
|
+
--query-params '{"limit": "10"}'
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
| Option | What it does |
|
|
162
|
+
|--------|-------------|
|
|
163
|
+
| `-d, --data <json>` | Request body (POST, PUT, PATCH) |
|
|
164
|
+
| `--path-vars <json>` | Replace `{variables}` in the URL path |
|
|
165
|
+
| `--query-params <json>` | Query string parameters |
|
|
166
|
+
| `--headers <json>` | Additional request headers |
|
|
167
|
+
| `--form-data` | Send as multipart/form-data |
|
|
168
|
+
| `--form-url-encoded` | Send as application/x-www-form-urlencoded |
|
|
169
|
+
|
|
170
|
+
### `pica config`
|
|
171
|
+
|
|
172
|
+
Configure access control for the MCP server. Optional — full access is the default.
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
pica config
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
| Setting | Options | Default |
|
|
179
|
+
|---------|---------|---------|
|
|
180
|
+
| Permission level | `admin` / `write` / `read` | `admin` |
|
|
181
|
+
| Connection scope | All or specific connections | All |
|
|
182
|
+
| Action scope | All or specific action IDs | All |
|
|
183
|
+
| Knowledge-only mode | Enable/disable execution | Off |
|
|
184
|
+
|
|
185
|
+
Settings propagate automatically to all installed agent configs.
|
|
186
|
+
|
|
187
|
+
## The workflow
|
|
188
|
+
|
|
189
|
+
The power of Pica is in the workflow. Every interaction follows the same pattern:
|
|
190
|
+
|
|
191
|
+
```
|
|
192
|
+
pica list → What am I connected to?
|
|
193
|
+
pica actions search → What can I do?
|
|
194
|
+
pica actions knowledge → How do I do it?
|
|
195
|
+
pica actions execute → Do it.
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
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.
|
|
199
|
+
|
|
200
|
+
## For AI agents
|
|
201
|
+
|
|
202
|
+
If you're an AI agent using the Pica MCP server, the tools map directly:
|
|
203
|
+
|
|
204
|
+
| MCP Tool | CLI Command |
|
|
205
|
+
|----------|------------|
|
|
206
|
+
| `list_pica_integrations` | `pica list` + `pica platforms` |
|
|
207
|
+
| `search_pica_platform_actions` | `pica actions search` |
|
|
208
|
+
| `get_pica_action_knowledge` | `pica actions knowledge` |
|
|
209
|
+
| `execute_pica_action` | `pica actions execute` |
|
|
120
210
|
|
|
121
|
-
|
|
211
|
+
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.
|
|
122
212
|
|
|
123
|
-
## MCP installation
|
|
213
|
+
## MCP server installation
|
|
124
214
|
|
|
125
|
-
`pica init`
|
|
215
|
+
`pica init` handles this automatically. Here's where configs go:
|
|
126
216
|
|
|
127
|
-
| Agent | Global
|
|
128
|
-
|
|
217
|
+
| Agent | Global | Project |
|
|
218
|
+
|-------|--------|---------|
|
|
129
219
|
| Claude Code | `~/.claude.json` | `.mcp.json` |
|
|
130
|
-
| Claude Desktop |
|
|
220
|
+
| Claude Desktop | Platform-specific app support dir | — |
|
|
131
221
|
| Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` |
|
|
132
|
-
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
|
|
222
|
+
| Windsurf | `~/.codeium/windsurf/mcp_config.json` | — |
|
|
133
223
|
| Codex | `~/.codex/config.toml` | `.codex/config.toml` |
|
|
134
224
|
| Kiro | `~/.kiro/settings/mcp.json` | `.kiro/settings/mcp.json` |
|
|
135
225
|
|
|
136
|
-
|
|
226
|
+
Project configs can be committed to your repo. Each team member runs `pica init` with their own API key.
|
|
137
227
|
|
|
138
228
|
## Development
|
|
139
229
|
|
|
140
230
|
```bash
|
|
141
231
|
npm run dev # watch mode
|
|
142
232
|
npm run build # production build
|
|
143
|
-
npm run typecheck # type check
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
## Project structure
|
|
147
|
-
|
|
148
|
-
```
|
|
149
|
-
src/
|
|
150
|
-
index.ts # Commander setup and command registration
|
|
151
|
-
commands/
|
|
152
|
-
init.ts # pica init (setup, status display, targeted actions)
|
|
153
|
-
connection.ts # pica add, pica list
|
|
154
|
-
platforms.ts # pica platforms
|
|
155
|
-
lib/
|
|
156
|
-
api.ts # HTTP client for Pica API
|
|
157
|
-
types.ts # TypeScript interfaces
|
|
158
|
-
config.ts # ~/.pica/config.json read/write
|
|
159
|
-
agents.ts # Agent detection, MCP config, status reporting
|
|
160
|
-
platforms.ts # Platform search and fuzzy matching
|
|
161
|
-
browser.ts # Open browser for OAuth and API key pages
|
|
162
|
-
table.ts # Formatted table output
|
|
233
|
+
npm run typecheck # type check
|
|
163
234
|
```
|