@devries-cameron20 / composio-1 / commits / cd46a7258
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: add agent signup resource (#3327)

## Summary - Add a new Resources page for signing up as an agent through agents.composio.dev - Document the agent signup, whoami, CLI, claim, and inbox endpoints with cURL examples - Link the agent signup resource from the Quickstart for agents bootstrapping themselves - Refresh the CLI docs page from current `composio --help full` output, covering current auth, agent signup, search/execute/link/connections, listen, run, proxy, generate, files/artifacts/config, dev, and skill-install workflows - Add the agent signup page to the docs Resources navigation ## Tests - `cd docs && bun run lint:links` - `cd docs && bun test tests/static/content.test.ts` - `cd docs && bun run build` ## Notes - Build emits existing warnings when `COMPOSIO_API_KEY` is not set for detailed toolkit/trigger fetches, but completed successfully. - `cd docs && bun run lint:links` initially failed before dependencies were installed because `fumadocs-mdx` resolved from Bun cache without matching `fumadocs-core`; reran successfully after `bun install --frozen-lockfile`.

Rahul Tarak committed May 2, 2026 at 00:49 UTC cd46a72584b30d84b63ea3af45c6e1db5698be4d
4 files changed +575 -156
docs/content/docs/cli.mdx
+377 -156
@@ -1,18 +1,18 @@
1 ---
2 title: CLI
3 -description: Install the Composio CLI to search for tools, inspect schemas, execute them, connect accounts, script workflows, and generate type-safe code from the terminal.
4 -keywords: [cli, command line, terminal, toolkits, tools, authentication, generate types]
3 +description: Install and use the Composio CLI to search tools, execute actions, connect accounts, listen to triggers, run scripts, proxy API calls, and manage local CLI state.
4 +keywords: [cli, command line, terminal, toolkits, tools, authentication, triggers, generate types]
5 ---
6
7 -The Composio CLI is best understood as a workflow tool, not just a list of commands.
7 +The Composio CLI connects AI agents to 1000+ external apps from the terminal. Use it to discover tools, execute known tool slugs, connect accounts, stream trigger events, call raw APIs through connected accounts, and script multi-step workflows.
8
9 -The default flow is:
9 +The default workflow is:
10
11 -1. If you already know the tool slug, start with `composio execute`.
11 +1. If you know the tool slug, start with `composio execute`.
12 2. If you do not know the slug, use `composio search`.
13 3. If the inputs are unclear, use `composio execute --get-schema` or `--dry-run`.
14 -4. If `execute` reports that the toolkit is not connected, run `composio link` and retry.
15 -5. Use `composio run` for multi-step workflows and `composio proxy` for raw API calls.
14 +4. If execution says the toolkit is not connected, run `composio link <toolkit>` and retry.
15 +5. Use `composio run` for scripts, `composio listen` for temporary trigger subscriptions, and `composio proxy` for raw authenticated API requests.
16
17 ## Installation
18
@@ -20,258 +20,479 @@ The default flow is:
20 curl -fsSL https://composio.dev/install | bash
21 ```
22
23 -## Getting started
23 +Check the installed version and upgrade when needed:
24
25 ```bash
26 -# Authenticate with Composio
27 -composio login
26 +composio --version
27 +composio upgrade
28 +```
29 +
30 +Set up shell integration after installing or moving the binary:
31
29 -# Inspect your current session
32 +```bash
33 +composio install --completions
34 +```
35 +
36 +## Help modes
37 +
38 +Use `--help` on the root command or any subcommand. The root help supports `simple`, `default`, and `full` modes.
39 +
40 +```bash
41 +composio --help
42 +composio --help full
43 +composio execute --help full
44 +composio dev --help full
45 +```
46 +
47 +<Callout type="info">
48 +`composio help` is not a subcommand. Use `composio --help` or `composio <command> --help`.
49 +</Callout>
50 +
51 +## Login and workspace context
52 +
53 +For a normal human-owned account, start with browser login:
54 +
55 +```bash
56 +composio login
57 composio whoami
58 ```
59
33 -`composio login` opens a browser-based flow, then prompts you to choose your default organization and project. Use `composio login -y` to skip the picker and use session defaults for non-interactive runs.
60 +Useful login options:
61 +
62 +```bash
63 +# Print a login URL/session and exit without waiting
64 +composio login --no-wait
65
35 -`composio whoami` shows account and workspace context and does not include API keys in display or JSON output.
66 +# Complete login with the key from a no-wait session
67 +composio login --key "session_key"
68
37 -## Execute a tool
69 +# Login non-interactively with a user API key and organization
70 +composio login --user-api-key "uak_..." --org "org_or_name"
71 +
72 +# Skip the organization picker and use the session default
73 +composio login -y
74 +```
75
39 -`composio execute` is the main command for actually running tools.
76 +Manage your default organization context:
77
78 ```bash
42 -# Execute a tool directly
43 -composio execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER -d '{"owner":"composiohq","repo":"composio"}'
79 +composio orgs list
80 +composio orgs switch --org-id "org_xxx"
81 +```
82
45 -# Validate without executing
46 -composio execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER --dry-run -d '{"owner":"composiohq","repo":"composio"}'
83 +Log out when you want to clear local auth state:
84
48 -# Read arguments from a file
49 -composio execute GITHUB_CREATE_ISSUE -d @issue.json
85 +```bash
86 +composio logout
87 +```
88
51 -# Read arguments from stdin
52 -cat issue.json | composio execute GITHUB_CREATE_ISSUE -d -
89 +## Sign up as an agent
90 +
91 +Agents can create and reuse a Composio identity without a human signing up first. The CLI wraps the agent signup APIs documented in [Signing up as an agent](/docs/signing-up-as-an-agent).
92 +
93 +```bash
94 +# Sign up as an agent and log the CLI in when credentials are ready
95 +composio signup
96 +
97 +# Start signup and exit without waiting for credentials
98 +composio signup --no-wait
99 +
100 +# Create or verify the agent identity without logging the CLI in
101 +composio signup --no-login
102 +
103 +# Force a new agent identity even if one already exists locally
104 +composio signup --force
105 +```
106 +
107 +You can also manage agent identity through the `agent` namespace:
108 +
109 +```bash
110 +composio agent signup
111 +composio agent login "composio_agent_key_..."
112 +composio agent whoami
113 +composio agent inbox --limit 20
114 +composio agent claim human@example.com
115 ```
116
55 -The `-d` / `--data` flag accepts:
117 +Agent identity is stored separately from the normal CLI login flow, so a background agent can bootstrap itself and later hand the organization to a human admin.
118
57 -- JSON
58 -- JS-style object literals
59 -- `@file`
60 -- `-` for stdin
119 +## Search for tools
120
62 -By default, `execute` does two useful checks for you:
121 +Use `composio search` when you do not know the tool slug. It accepts one or more semantic queries and returns JSON by default.
122
64 -- validates arguments against the cached tool schema
65 -- checks whether the required toolkit account is connected
123 +```bash
124 +composio search "send an email"
125 +composio search "send an email" "create github issue"
126 +composio search "my emails" "my github issues" --toolkits gmail,github
127 +composio search "list calendar events" --toolkits google_calendar --limit 5
128 +```
129
67 -If you just need a schema or a safe preview, stay inside `execute`:
130 +Use `--human` for readable terminal output:
131
132 ```bash
70 -composio execute GITHUB_CREATE_ISSUE --get-schema
71 -composio execute GITHUB_CREATE_ISSUE --skip-connection-check --dry-run -d '{ owner: "acme", repo: "app", title: "Bug report", body: "Steps to reproduce..." }'
133 +composio search "create a github issue" --human
134 ```
135
74 -If the command output is very large, the CLI may store it in the session artifacts directory instead of printing everything inline. Use `composio artifacts cwd` to find that directory for the current working tree.
136 +Once you have a slug, switch back to `composio execute`.
137
76 -If you need several independent tool calls and do not need script logic, use top-level parallel execute instead of jumping straight to `run`:
138 +## Execute tools
139 +
140 +`composio execute` runs a tool by slug. It validates inputs against the cached schema and checks the required connected account before running the remote action.
141
142 ```bash
79 -composio execute --parallel \
80 - GMAIL_FETCH_EMAILS -d '{ max_results: 2 }' \
81 - GITHUB_GET_THE_AUTHENTICATED_USER -d '{}'
143 +composio execute GITHUB_CREATE_ISSUE \
144 + -d '{ owner: "acme", repo: "app", title: "Bug report", body: "Steps to reproduce..." }'
145 ```
146
84 -## Search for the right slug
147 +The `-d` / `--data` flag accepts JSON, JS-style object literals, files, or stdin:
148
86 -Use `composio search` only when the slug is unknown.
149 +```bash
150 +composio execute GITHUB_CREATE_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'
151 +composio execute GITHUB_CREATE_ISSUE -d @issue.json
152 +cat issue.json | composio execute GITHUB_CREATE_ISSUE -d -
153 +```
154 +
155 +Inspect the schema or preview a call without executing it:
156
157 ```bash
89 -composio search "create a github issue"
90 -composio search "send an email" --toolkits gmail
91 -composio search "send an email" "create a github issue"
92 -composio search "my emails" "my github issues" --toolkits gmail,github
158 +composio execute GITHUB_CREATE_ISSUE --get-schema
159 +composio execute GITHUB_CREATE_ISSUE --dry-run \
160 + -d '{ owner: "acme", repo: "app", title: "Bug" }'
161 ```
162
95 -Use multiple quoted queries when you are exploring several related tasks at once. Read the returned slugs, choose the best match, then move back to `execute`.
163 +Use the validation escape hatches only when you know what you are doing:
164 +
165 +```bash
166 +composio execute GITHUB_CREATE_ISSUE --skip-connection-check -d @issue.json
167 +composio execute GITHUB_CREATE_ISSUE --skip-tool-params-check -d @issue.json
168 +composio execute GITHUB_CREATE_ISSUE --skip-checks -d @issue.json
169 +```
170
97 -Use `--human` when you want a readable summary in the terminal. Leave it off when you want JSON output for scripting.
171 +Upload a local file when the tool exposes exactly one uploadable file input:
172
99 -## Inspect a known slug
173 +```bash
174 +composio execute SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK \
175 + --file ./image.png \
176 + -d '{ channels: "C123" }'
177 +```
178
101 -Use `composio tools info` as a compact fallback when you already know the slug and want a quick summary:
179 +Run independent tool calls concurrently with `-p` / `--parallel`:
180
181 ```bash
104 -composio tools info GITHUB_CREATE_ISSUE
105 -composio tools list gmail
182 +composio execute -p \
183 + GMAIL_SEND_EMAIL -d '{ recipient_email: "a@b.com", subject: "Hi", body: "Hello" }' \
184 + GITHUB_CREATE_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'
185 ```
186
108 -For most execution questions, `composio execute --get-schema` or `--dry-run` is a better first step than `tools info`.
187 +If output is too large for the terminal, the CLI stores it in the session artifact directory. Use `composio artifacts cwd` to find that directory.
188
110 -## Connect accounts with link
189 +## Connect and manage accounts
190
112 -`composio link` connects an external account for a toolkit such as GitHub, Gmail, or Slack.
191 +`composio link` connects an external account for a toolkit such as GitHub, Gmail, Slack, or Google Calendar.
192
193 ```bash
194 composio link github
195 +composio link gmail --alias work
196 +```
197
117 -# Print the auth URL and exit immediately
198 +Useful link options:
199 +
200 +```bash
201 +# Print link info and exit without waiting for browser authorization
202 composio link github --no-wait
203 +
204 +# List existing connected accounts for a toolkit
205 +composio link github --list
206 ```
207
121 -You usually do not start with `link`. The normal flow is to try `execute` first. If the CLI tells you there is no active connection for the toolkit, run `link` and retry the exact same command.
208 +The normal flow is to try `execute` first. If the CLI reports that no account is connected, run `link` and retry the same `execute` command.
209
123 -## End-to-end flow
210 +Inspect or remove connected accounts with `connections`:
211
212 ```bash
126 -composio search "star a github repo" --human
127 -composio tools info GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER
128 -composio execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER --dry-run -d '{"owner":"composiohq","repo":"composio"}'
129 -composio link github
130 -composio execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER -d '{"owner":"composiohq","repo":"composio"}'
213 +composio connections list
214 +composio connections list --toolkit github
215 +composio connections remove github
216 +composio connections remove work
217 ```
218
133 -## Script multi-step workflows with run
219 +Aliases for duplicate toolkit accounts require the `multi_account` experimental feature:
220
135 -Use `composio run` when one tool call is not enough and you want to stay inside the CLI.
221 +```bash
222 +composio config experimental multi_account on
223 +```
224 +
225 +## Inspect tools and triggers
226 +
227 +Use `tools` and `triggers` when you already know the toolkit or slug and want a compact summary.
228
137 -The runtime injects helpers that mirror the CLI:
229 +```bash
230 +# Tools
231 +composio tools list gmail
232 +composio tools list gmail --query "send" --tags important --limit 20
233 +composio tools info GMAIL_SEND_EMAIL
234 +
235 +# Trigger types
236 +composio triggers list gmail
237 +composio triggers list gmail --limit 20
238 +composio triggers info GMAIL_NEW_GMAIL_MESSAGE
239 +```
240
139 -- `execute(slug, data?)`
140 -- `search(query, opts?)`
141 -- `proxy(toolkit)`
142 -- `experimental_subAgent(prompt, opts?)`
143 -- `z`
241 +For execution arguments, `composio execute <slug> --get-schema` is usually the most direct schema view.
242 +
243 +## Listen to trigger events
244 +
245 +`composio listen` creates a temporary subscription for consumer-project trigger events and writes each payload into the session artifact folder. Use it when an agent needs to consume new emails, Slack messages, or other events during a run.
246 +
247 +```bash
248 +composio listen GMAIL_NEW_GMAIL_MESSAGE
249 +composio listen GMAIL_NEW_GMAIL_MESSAGE --timeout 5m
250 +composio listen GMAIL_NEW_GMAIL_MESSAGE --max-events 5
251 +```
252 +
253 +Pass trigger creation params as JSON, JS-style object literals, `@file`, or stdin:
254 +
255 +```bash
256 +composio listen SLACK_RECEIVE_MESSAGE \
257 + -p '{ trigger_config: { channel: "C123" } }' \
258 + --max-events 10
259 +
260 +composio listen GMAIL_NEW_GMAIL_MESSAGE -p @trigger.json --stream
261 +```
262 +
263 +Use `--stream` to also print each payload inline. You can pass a jq-like path to stream one field:
264 +
265 +```bash
266 +composio listen GMAIL_NEW_GMAIL_MESSAGE --timeout 1hr --stream '.data.threadId'
267 +```
268 +
269 +See where payload artifacts are stored:
270 +
271 +```bash
272 +composio artifacts cwd
273 +```
274 +
275 +## Script workflows with run
276 +
277 +Use `composio run` for multi-step workflows, loops, conditionals, parallel fan-out, or LLM-assisted summarization. It runs inline TS/JS or a file with injected helpers.
278 +
279 +Injected helpers:
280 +
281 +| Helper | Description |
282 +| --- | --- |
283 +| `execute(slug, data?)` | Run a tool, like `composio execute`, and return parsed JSON |
284 +| `search(query, opts?)` | Find tools, like `composio search` |
285 +| `proxy(toolkit)` | Return a `fetch()` bound to a connected account for that toolkit |
286 +| `experimental_subAgent(prompt, opts?)` | Ask a Claude/Codex sub-agent, optionally with structured output |
287 +| `result.prompt()` | Serialize any helper result into an LLM-friendly string |
288 +| `z` | Global Zod instance for structured output schemas |
289
290 Examples:
291
292 ```bash
293 # Inline workflow
294 +composio run '
295 + const me = await execute("GITHUB_GET_THE_AUTHENTICATED_USER");
296 + console.log(me);
297 +'
298 +
299 +# Sequential actions across services
300 composio run '
301 const issue = await execute("GITHUB_CREATE_ISSUE", {
302 owner: "acme",
303 repo: "app",
153 - title: "Bug report",
154 - body: "Steps to reproduce..."
304 + title: "Deploy v2"
305 + });
306 + await execute("SLACK_SEND_A_MESSAGE_TO_A_SLACK_CHANNEL", {
307 + channel: "eng",
308 + text: "Created: " + issue.data.html_url
309 });
156 - console.log(issue);
310 '
311
159 -# Run a workflow from a file
160 -composio run --file ./workflow.ts -- --repo composiohq/composio
312 +# Run a file and pass script args after --
313 +composio run --file ./workflow.ts -- --repo acme/app
314 ```
315
163 -Use `run` when you want loops, conditionals, `Promise.all`, `search()` inside a script, `proxy()`, `experimental_subAgent()`, or a reusable workflow file.
316 +Debug or preview scripts:
317 +
318 +```bash
319 +composio run --dry-run 'await execute("GMAIL_SEND_EMAIL", { recipient_email: "a@b.com" })'
320 +composio run --debug --file ./workflow.ts
321 +composio run --logs-off '/* hide experimental_subAgent streaming logs */'
322 +```
323 +
324 +Use top-level `composio execute -p` instead when you only need a few independent tool calls and no script logic.
325
326 ## Call raw APIs with proxy
327
167 -Use `composio proxy` when you want authenticated access to a toolkit API endpoint directly rather than going through a dedicated Composio tool. The command uses your linked account for the toolkit you pass with `--toolkit`.
328 +Use `composio proxy` when you already know the API endpoint and want Composio to inject auth from a connected account. Pass the full API URL and the toolkit slug.
329
330 ```bash
170 -composio proxy /gmail/v1/users/me/profile --toolkit gmail
171 -composio proxy /gmail/v1/users/me/drafts --toolkit gmail -X POST -H 'content-type: application/json' -d '{"message":{"raw":"..."}}'
331 +composio proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit gmail
332 +
333 +composio proxy https://gmail.googleapis.com/gmail/v1/users/me/drafts \
334 + --toolkit gmail \
335 + -X POST \
336 + -H 'content-type: application/json' \
337 + -d '{"message":{"raw":"..."}}'
338 ```
339
174 -<Callout type="warn">
175 -Prefer relative endpoints. If you pass an absolute URL, it must stay on the same scheme and registrable domain as the toolkit account's base URL.
176 -</Callout>
340 +`-d` accepts raw text, JSON, `@file`, or `-` for stdin. Use `--skip-connection-check` only when you need to bypass the connected-account preflight.
341
178 -Use `proxy` when:
342 +You can also use `proxy()` inside `composio run`:
343
180 -- there is no dedicated tool for the endpoint you need
181 -- you already know the exact API endpoint to call
182 -- you want Composio to handle auth while you keep full control over the request
344 +```bash
345 +composio run '
346 + const gmail = await proxy("gmail");
347 + const profile = await gmail("https://gmail.googleapis.com/gmail/v1/users/me/profile");
348 + console.log(profile);
349 +'
350 +```
351
184 -## Developer project commands
352 +## Generate type definitions
353
186 -Use the `dev` namespace only for developer-project setup and inspection commands, not for the normal consumer-style search and execute flow.
354 +Generate TypeScript or Python type stubs for selected toolkits, tools, and triggers. The current CLI requires at least one `--toolkits` value.
355
356 ```bash
189 -# Initialize local developer project context
190 -composio dev init
357 +# Auto-detect TypeScript or Python from the project
358 +composio generate --toolkits github gmail
359 +
360 +# TypeScript
361 +composio generate ts --toolkits github gmail
362 +composio generate ts --toolkits github --output-dir ./src/composio-types
363 +composio generate ts --toolkits github --compact
364 +composio generate ts --toolkits github --transpiled
365 +composio generate ts --toolkits github --type-tools
366 +
367 +# Python
368 +composio generate py --toolkits github gmail
369 +composio generate py --toolkits github --output-dir ./composio_types
370 +```
371
192 -# Execute a tool against a playground user
193 -composio dev playground-execute GITHUB_CREATE_ISSUE --user-id demo-user -d '{"owner":"acme","repo":"app","title":"Bug"}'
372 +<Callout type="info">
373 +Type generation is most useful when you are using [direct tool execution](/docs/tools-direct/executing-tools). If you use sessions with meta tools, you usually do not need generated stubs.
374 +</Callout>
375
195 -# Inspect triggers and logs
196 -composio dev listen --toolkits github --table
197 -composio dev logs tools
198 -composio dev logs triggers
199 -```
376 +## Local files, artifacts, and config
377
201 -## Command summary
378 +Show where the CLI stores local data:
379
203 -Run `composio <command> --help` for detailed usage and flags.
380 +```bash
381 +composio files
382 +composio artifacts cwd
383 +```
384
205 -- `composio execute`: First choice when the slug is known.
206 -- `composio search`: Discovery step when the slug is unknown.
207 -- `composio link`: Recovery step when a toolkit account is missing.
208 -- `composio run`: Programmatic workflows and LLM-driven scripting.
209 -- `composio proxy`: Raw authenticated API access.
210 -- `composio dev`: Developer-project commands only.
385 +Important locations:
386
212 -## Global flags
387 +| Path | Purpose |
388 +| --- | --- |
389 +| `~/.composio/` | CLI auth, config, cached tool/toolkit definitions, trigger types, analytics ID, and per-org consumer caches |
390 +| `$TMPDIR/composio/` | Session artifacts, large outputs, downloaded files, and run/execute history |
391 +| `.composio/` | Optional per-project config such as `.env` and `project.json` |
392
214 -| Flag | Description |
215 -| --------------------- | ----------------------------------------------------------------------------------- |
216 -| `--log-level <level>` | Set log level: `all`, `trace`, `debug`, `info`, `warning`, `error`, `fatal`, `none` |
217 -| `--help` | Show help for any command |
393 +Useful path environment variables:
394
219 -## Environment variables
395 +| Variable | Description |
396 +| --- | --- |
397 +| `COMPOSIO_SESSION_DIR` | Override the session artifacts root |
398 +| `COMPOSIO_CACHE_DIR` | Override the cache directory and artifact fallback location |
399
221 -| Variable | Description |
222 -| ------------------------------------ | ---------------------------------------------------------------------------- |
223 -| `COMPOSIO_API_KEY` | Your Composio API key |
224 -| `COMPOSIO_BASE_URL` | Custom API base URL |
225 -| `COMPOSIO_WEB_URL` | Custom Composio dashboard URL |
226 -| `COMPOSIO_CACHE_DIR` | Override the CLI cache directory |
227 -| `COMPOSIO_SESSION_DIR` | Override the session artifacts root directory |
228 -| `COMPOSIO_LOG_LEVEL` | Default logging level |
229 -| `COMPOSIO_DISABLE_TELEMETRY` | Set to `"true"` to disable telemetry |
230 -| `COMPOSIO_TOOLKIT_VERSION_{TOOLKIT}` | Override toolkit version (e.g. `COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00`) |
231 -| `COMPOSIO_WEBHOOK_SECRET` | Signing secret for trigger webhook forwarding |
232 -| `FORCE_USE_CACHE` | Force cache-first reads for generated toolkit and tool metadata |
233 -| `DEBUG_OVERRIDE_VERSION` | Override the target CLI version during upgrade debugging |
400 +View or toggle experimental CLI features:
401
235 -## Generate type definitions
402 +```bash
403 +composio config experimental
404 +composio config experimental listen
405 +composio config experimental multi_account on
406 +composio config experimental multi_account off
407 +```
408
237 -<Callout type="info">
238 - Type generation is only useful if you're using [direct tool
239 - execution](/docs/tools-direct/executing-tools). If you're using sessions with meta tools, you
240 - don't need this.
241 -</Callout>
409 +## Developer project commands
410
243 -Generate TypeScript or Python type definitions for Composio tools. These types provide autocomplete and type safety when using direct tool execution (`composio.tools.execute()`).
411 +Use the `dev` namespace when you are building an app or agent with Composio's SDK and need developer-scoped project setup, playground execution, logs, toolkits, auth configs, connected accounts, triggers, and projects.
412
413 ```bash
246 -composio generate
414 +# Initialize this directory with a developer project
415 +composio dev init
416 +
417 +# Turn developer mode on or off
418 +composio dev --mode on
419 +composio dev --mode off
420 +
421 +# Execute a tool against a developer playground user
422 +composio dev playground-execute GMAIL_SEND_EMAIL \
423 + --user-id demo-user \
424 + -d '{ recipient_email: "a@b.com", subject: "Hello" }'
425 +
426 +# Inspect logs
427 +composio dev logs tools --toolkit gmail --limit 20
428 +composio dev logs tools log_xxx
429 +composio dev logs triggers --limit 20
430 +
431 +# Stream developer-project trigger events
432 +composio dev listen --toolkits gmail --table
433 +composio dev listen --trigger-slug GMAIL_NEW_GMAIL_MESSAGE --json --max-events 5
434 +composio dev listen --toolkits github --forward https://example.com/webhook
435 ```
436
249 -The CLI auto-detects your project language. When no `--output-dir` is provided, TypeScript generation writes to the project default location and emits transpiled JavaScript alongside TypeScript. For explicit control, use `composio generate ts` or `composio generate py`.
437 +Common `dev` groups:
438 +
439 +| Group | Examples |
440 +| --- | --- |
441 +| Project | `dev init`, `dev projects list`, `dev projects switch` |
442 +| Execution | `dev playground-execute`, `dev listen`, `dev logs tools`, `dev logs triggers` |
443 +| Toolkits | `dev toolkits list`, `dev toolkits info`, `dev toolkits search`, `dev toolkits version` |
444 +| Auth configs | `dev auth-configs list`, `dev auth-configs info`, `dev auth-configs create` |
445 +| Connected accounts | `dev connected-accounts link`, `list`, `info`, `whoami` |
446 +| Triggers | `dev triggers list`, `info`, `status`, `create`, `enable`, `disable` |
447
251 -<Tabs items={['TypeScript', 'Python']}>
252 - <Tab value="TypeScript">
253 - ```bash
254 - composio generate ts
255 - ```
448 +Disabling trigger instances is guarded. It requires `developer.destructive_actions: true` in `~/.composio/config.json` and `--dangerously-allow` on the command line.
449
257 - | Flag | Description |
258 - | --- | --- |
259 - | `-o`, `--output-dir <dir>` | Output directory |
260 - | `--compact` | Emit a single TypeScript file |
261 - | `--transpiled` | Emit transpiled JavaScript alongside TypeScript |
262 - | `--type-tools` | Generate typed schemas for each tool (slower) |
263 - | `--toolkits <names>` | Only generate for specific toolkits (repeatable) |
450 +## Agent skill installation
451
265 - </Tab>
266 - <Tab value="Python">
267 - ```bash
268 - composio generate py
269 - ```
452 +The CLI can install Composio skills into supported coding agents when auto-installation fails or you want to install manually.
453
271 - | Flag | Description |
272 - | --- | --- |
273 - | `-o`, `--output-dir <dir>` | Output directory |
274 - | `--toolkits <names>` | Only generate for specific toolkits (repeatable) |
454 +```bash
455 +composio --install-skill claude
456 +composio --install-skill composio-cli codex
457 +composio --install-skill composio-cli openclaw
458 +```
459 +
460 +`composio login` installs the `composio-cli` skill for Claude Code by default. Pass `--no-skill-install` to skip it.
461 +
462 +## Command summary
463 +
464 +| Command | Use it for |
465 +| --- | --- |
466 +| `composio search` | Find tool slugs by use case |
467 +| `composio execute` | Run a known tool slug, inspect schemas, dry-run, or parallelize tool calls |
468 +| `composio link` | Connect an account for a toolkit |
469 +| `composio connections` | List or remove connected accounts |
470 +| `composio tools` | List tools for a toolkit or inspect a known tool |
471 +| `composio triggers` | List or inspect trigger types |
472 +| `composio listen` | Create temporary consumer-project trigger subscriptions |
473 +| `composio run` | Script multi-step workflows with injected helpers |
474 +| `composio proxy` | Call raw toolkit APIs with Composio-managed auth |
475 +| `composio signup` / `composio agent` | Bootstrap and manage an agent-owned Composio identity |
476 +| `composio generate` | Generate TypeScript or Python stubs for selected toolkits |
477 +| `composio dev` | Manage developer-project workflows |
478 +| `composio artifacts` / `composio files` | Inspect local artifact and config/cache paths |
479 +| `composio orgs` / `composio config` | Manage organization context and CLI config |
480 +| `composio version` / `composio upgrade` | Check and update the CLI |
481 +
482 +## Environment variables
483
276 - </Tab>
277 -</Tabs>
484 +| Variable | Description |
485 +| --- | --- |
486 +| `COMPOSIO_API_KEY` | Composio project API key for API and SDK usage |
487 +| `COMPOSIO_BASE_URL` | Custom Composio API base URL |
488 +| `COMPOSIO_WEB_URL` | Custom Composio dashboard URL |
489 +| `COMPOSIO_SESSION_DIR` | Override the CLI session artifact root |
490 +| `COMPOSIO_CACHE_DIR` | Override the CLI cache directory |
491 +| `COMPOSIO_LOG_LEVEL` | Default logging level |
492 +| `COMPOSIO_DISABLE_TELEMETRY` | Set to `"true"` to disable telemetry |
493 +| `COMPOSIO_TOOLKIT_VERSION_{TOOLKIT}` | Override a toolkit version, for example `COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00` |
494 +| `COMPOSIO_WEBHOOK_SECRET` | Signing secret for trigger webhook forwarding |
495 +| `COMPOSIO_ORG_ID` | Per-project or environment organization override |
496 +| `COMPOSIO_PROJECT_ID` | Per-project or environment project override |
497 +| `FORCE_USE_CACHE` | Force cache-first reads for generated toolkit and tool metadata |
498 +| `DEBUG_OVERRIDE_VERSION` | Override target CLI version during upgrade debugging |
docs/content/docs/meta.json
+1
@@ -36,6 +36,7 @@
36 "tools-direct",
37 "auth-configuration",
38 "---Resources---",
39 + "signing-up-as-an-agent",
40 "common-faq",
41 "glossary",
42 "debugging-info",
docs/content/docs/quickstart.mdx
+4
@@ -6,6 +6,10 @@ keywords: [tutorial, setup, first agent]
6
7 Build your first AI agent with Composio Tools. You'll create a [session](/docs/users-and-sessions) for a user, give your agent access to [tools](/docs/tools-and-toolkits), and let it take action across 1000+ apps.
8
9 +<Callout type="info">
10 +If you are an AI agent setting up Composio for yourself, you can [sign up as an agent](/docs/signing-up-as-an-agent) without a human-created account first.
11 +</Callout>
12 +
13 <QuickstartFlow>
14
15 <FrameworkOption id="openai-agents" name="OpenAI Agents" logo="/images/providers/openai-logo.svg" logoDark="/images/providers/openai-logo-dark.svg">
docs/content/docs/signing-up-as-an-agent.mdx new
+193
@@ -0,0 +1,193 @@
1 +---
2 +title: Signing Up as an Agent
3 +description: Create and reuse a Composio account programmatically from an AI agent
4 +keywords: [agent signup, agents, cli, api key, anonymous signup]
5 +---
6 +
7 +Agents can sign up for Composio directly through [`agents.composio.dev`](https://agents.composio.dev) without a human creating an account first. The flow creates an agent identity, returns Composio credentials, and gives the agent a ready-to-run CLI install/login command.
8 +
9 +The base URL for all endpoints on this page is:
10 +
11 +```text
12 +https://agents.composio.dev
13 +```
14 +
15 +## Flow
16 +
17 +1. **Check for an existing identity.** Before signing up, look for `~/.composio/anonymous_user_data.json`. If it exists, read the saved `agent_key` and call `GET /api/whoami` with `Authorization: Bearer <agent_key>`. If it returns `200` with `status: "READY"`, reuse the saved credentials.
18 +2. **Sign up.** Call `POST /api/signup`. By default, the endpoint waits until the account is ready and returns a `201` response containing the `agent_key` plus Composio credentials (`member_id`, `org_id`, `project_id`, `api_key`, and `user_api_key`). Save the full response to `~/.composio/anonymous_user_data.json` immediately so future runs do not create a new identity.
19 +3. **Install and log in to the CLI.** Call `GET /api/cli` with the `agent_key`. It returns paste-ready install and login commands.
20 +4. **Optionally claim the org.** Call `POST /api/claim` with a human email only when you want to hand the organization over to a human admin.
21 +
22 +## Sign up
23 +
24 +`POST /api/signup` creates an agent email inbox, starts the Composio signup flow, and long-polls for up to 120 seconds. Most calls complete in about 5–10 seconds.
25 +
26 +```bash
27 +mkdir -p ~/.composio
28 +
29 +curl -sS -X POST 'https://agents.composio.dev/api/signup' \
30 + -H 'content-type: application/json' \
31 + -d '{}' \
32 + -o ~/.composio/anonymous_user_data.json
33 +
34 +cat ~/.composio/anonymous_user_data.json
35 +```
36 +
37 +Successful response:
38 +
39 +```json
40 +{
41 + "status": "ready",
42 + "request_id": "req_xxx",
43 + "slug": "amber-cedar-otter",
44 + "email": "amber-cedar-otter@agent.composio.ai",
45 + "agent_key": "composio_agent_key_xxx",
46 + "composio": {
47 + "member_id": "uuid",
48 + "org_id": "org_xxx",
49 + "project_id": "proj_xxx",
50 + "api_key": "ak_xxx",
51 + "user_api_key": "uak_xxx"
52 + }
53 +}
54 +```
55 +
56 +If the 120-second wait expires, the endpoint returns `202` with `status: "pending"`. Poll `GET /api/whoami` until the status is `READY`.
57 +
58 +```json
59 +{
60 + "status": "pending",
61 + "request_id": "req_xxx",
62 + "slug": "amber-cedar-otter",
63 + "email": "amber-cedar-otter@agent.composio.ai",
64 + "agent_key": "composio_agent_key_xxx",
65 + "poll": "/api/whoami"
66 +}
67 +```
68 +
69 +To skip waiting and poll yourself, pass `?wait=0`:
70 +
71 +```bash
72 +curl -sS -X POST 'https://agents.composio.dev/api/signup?wait=0' \
73 + -H 'content-type: application/json' \
74 + -d '{}'
75 +```
76 +
77 +## Verify a saved identity
78 +
79 +Use `GET /api/whoami` to verify a saved `agent_key` and fetch the current Composio credentials. The `agent_key` authenticates only against the agent signup surface; it is not your Composio API key.
80 +
81 +```bash
82 +AGENT_KEY="$(jq -r '.agent_key' ~/.composio/anonymous_user_data.json)"
83 +
84 +curl -sS 'https://agents.composio.dev/api/whoami' \
85 + -H "Authorization: Bearer ${AGENT_KEY}"
86 +```
87 +
88 +Response:
89 +
90 +```json
91 +{
92 + "slug": "amber-cedar-otter",
93 + "email": "amber-cedar-otter@agent.composio.ai",
94 + "status": "READY",
95 + "claimed_by": null,
96 + "claimed_at": null,
97 + "composio": {
98 + "member_id": "uuid",
99 + "org_id": "org_xxx",
100 + "project_id": "proj_xxx",
101 + "api_key": "ak_xxx",
102 + "user_api_key": "uak_xxx"
103 + }
104 +}
105 +```
106 +
107 +## Install the CLI
108 +
109 +`GET /api/cli` returns install and login commands with the agent's `user_api_key` and `org_id` already filled in.
110 +
111 +```bash
112 +AGENT_KEY="$(jq -r '.agent_key' ~/.composio/anonymous_user_data.json)"
113 +
114 +curl -sS 'https://agents.composio.dev/api/cli' \
115 + -H "Authorization: Bearer ${AGENT_KEY}"
116 +```
117 +
118 +Example response:
119 +
120 +```text
121 +Install Composio CLI using this command:
122 +curl -fsSL https://composio.dev/install | bash
123 +
124 +Then log in using this command:
125 +composio login --user-api-key "uak_..." --org "ok_..."
126 +```
127 +
128 +Run the returned commands to install and authenticate the CLI.
129 +
130 +## Claim the organization
131 +
132 +Claiming is optional. Use it only when the agent wants to invite a human admin to take over the Composio organization. The endpoint issues a single-use admin invite that expires after 24 hours.
133 +
134 +```bash
135 +AGENT_KEY="$(jq -r '.agent_key' ~/.composio/anonymous_user_data.json)"
136 +
137 +curl -sS -X POST 'https://agents.composio.dev/api/claim' \
138 + -H "Authorization: Bearer ${AGENT_KEY}" \
139 + -H 'content-type: application/json' \
140 + -d '{"email":"human@example.com"}'
141 +```
142 +
143 +Response:
144 +
145 +```json
146 +{
147 + "status": "invited",
148 + "email": "human@example.com",
149 + "org_id": "org_xxx",
150 + "invite_code": "inv_xxx"
151 +}
152 +```
153 +
154 +## Read the agent inbox
155 +
156 +Each agent gets an email address at `<slug>@agent.composio.ai`. Use `GET /api/mail` to list messages for the agent inbox.
157 +
158 +```bash
159 +AGENT_KEY="$(jq -r '.agent_key' ~/.composio/anonymous_user_data.json)"
160 +
161 +curl -sS 'https://agents.composio.dev/api/mail?limit=50' \
162 + -H "Authorization: Bearer ${AGENT_KEY}"
163 +```
164 +
165 +Response:
166 +
167 +```json
168 +{
169 + "count": 1,
170 + "messages": [
171 + {
172 + "id": "msg_xxx",
173 + "thread_id": "thr_xxx",
174 + "from": "no-reply@composio.dev",
175 + "to": "amber-cedar-otter@agent.composio.ai",
176 + "subject": "Sign in to Composio",
177 + "preview": "Click the link below to sign in...",
178 + "received_at": "2026-04-13T22:00:00.000Z"
179 + }
180 + ]
181 +}
182 +```
183 +
184 +## Agent keys
185 +
186 +Agent keys are prefixed with `composio_agent_key_` and are only valid for these endpoints:
187 +
188 +- `GET /api/whoami`
189 +- `GET /api/mail`
190 +- `GET /api/cli`
191 +- `POST /api/claim`
192 +
193 +Use the real Composio API key from the `composio.api_key` field when calling Composio APIs and SDKs.