Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: add agent signup resource (#3327)
Rahul Tarakcd46a72584b3
diff --git a/docs/content/docs/cli.mdx b/docs/content/docs/cli.mdxindex f61953305..bde7aea96 100644--- a/docs/content/docs/cli.mdx+++ b/docs/content/docs/cli.mdx@@ -1,18 +1,18 @@---title: CLI-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.-keywords: [cli, command line, terminal, toolkits, tools, authentication, generate types]+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.+keywords: [cli, command line, terminal, toolkits, tools, authentication, triggers, generate types]----The Composio CLI is best understood as a workflow tool, not just a list of commands.+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.-The default flow is:+The default workflow is:-1. If you already know the tool slug, start with `composio execute`.+1. If you know the tool slug, start with `composio execute`.2. If you do not know the slug, use `composio search`.3. If the inputs are unclear, use `composio execute --get-schema` or `--dry-run`.-4. If `execute` reports that the toolkit is not connected, run `composio link` and retry.-5. Use `composio run` for multi-step workflows and `composio proxy` for raw API calls.+4. If execution says the toolkit is not connected, run `composio link <toolkit>` and retry.+5. Use `composio run` for scripts, `composio listen` for temporary trigger subscriptions, and `composio proxy` for raw authenticated API requests.## Installation@@ -20,258 +20,479 @@ The default flow is:curl -fsSL https://composio.dev/install | bash```-## Getting started+Check the installed version and upgrade when needed:```bash-# Authenticate with Composio-composio login+composio --version+composio upgrade+```++Set up shell integration after installing or moving the binary:-# Inspect your current session+```bash+composio install --completions+```++## Help modes++Use `--help` on the root command or any subcommand. The root help supports `simple`, `default`, and `full` modes.++```bash+composio --help+composio --help full+composio execute --help full+composio dev --help full+```++<Callout type="info">+`composio help` is not a subcommand. Use `composio --help` or `composio <command> --help`.+</Callout>++## Login and workspace context++For a normal human-owned account, start with browser login:++```bash+composio logincomposio whoami```-`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.+Useful login options:++```bash+# Print a login URL/session and exit without waiting+composio login --no-wait-`composio whoami` shows account and workspace context and does not include API keys in display or JSON output.+# Complete login with the key from a no-wait session+composio login --key "session_key"-## Execute a tool+# Login non-interactively with a user API key and organization+composio login --user-api-key "uak_..." --org "org_or_name"++# Skip the organization picker and use the session default+composio login -y+```-`composio execute` is the main command for actually running tools.+Manage your default organization context:```bash-# Execute a tool directly-composio execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER -d '{"owner":"composiohq","repo":"composio"}'+composio orgs list+composio orgs switch --org-id "org_xxx"+```-# Validate without executing-composio execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER --dry-run -d '{"owner":"composiohq","repo":"composio"}'+Log out when you want to clear local auth state:-# Read arguments from a file-composio execute GITHUB_CREATE_ISSUE -d @issue.json+```bash+composio logout+```-# Read arguments from stdin-cat issue.json | composio execute GITHUB_CREATE_ISSUE -d -+## Sign up as an agent++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).++```bash+# Sign up as an agent and log the CLI in when credentials are ready+composio signup++# Start signup and exit without waiting for credentials+composio signup --no-wait++# Create or verify the agent identity without logging the CLI in+composio signup --no-login++# Force a new agent identity even if one already exists locally+composio signup --force+```++You can also manage agent identity through the `agent` namespace:++```bash+composio agent signup+composio agent login "composio_agent_key_..."+composio agent whoami+composio agent inbox --limit 20+composio agent claim [email protected]```-The `-d` / `--data` flag accepts:+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.-- JSON-- JS-style object literals-- `@file`-- `-` for stdin+## Search for tools-By default, `execute` does two useful checks for you:+Use `composio search` when you do not know the tool slug. It accepts one or more semantic queries and returns JSON by default.-- validates arguments against the cached tool schema-- checks whether the required toolkit account is connected+```bash+composio search "send an email"+composio search "send an email" "create github issue"+composio search "my emails" "my github issues" --toolkits gmail,github+composio search "list calendar events" --toolkits google_calendar --limit 5+```-If you just need a schema or a safe preview, stay inside `execute`:+Use `--human` for readable terminal output:```bash-composio execute GITHUB_CREATE_ISSUE --get-schema-composio execute GITHUB_CREATE_ISSUE --skip-connection-check --dry-run -d '{ owner: "acme", repo: "app", title: "Bug report", body: "Steps to reproduce..." }'+composio search "create a github issue" --human```-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.+Once you have a slug, switch back to `composio execute`.-If you need several independent tool calls and do not need script logic, use top-level parallel execute instead of jumping straight to `run`:+## Execute tools++`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.```bash-composio execute --parallel \- GMAIL_FETCH_EMAILS -d '{ max_results: 2 }' \- GITHUB_GET_THE_AUTHENTICATED_USER -d '{}'+composio execute GITHUB_CREATE_ISSUE \+ -d '{ owner: "acme", repo: "app", title: "Bug report", body: "Steps to reproduce..." }'```-## Search for the right slug+The `-d` / `--data` flag accepts JSON, JS-style object literals, files, or stdin:-Use `composio search` only when the slug is unknown.+```bash+composio execute GITHUB_CREATE_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'+composio execute GITHUB_CREATE_ISSUE -d @issue.json+cat issue.json | composio execute GITHUB_CREATE_ISSUE -d -+```++Inspect the schema or preview a call without executing it:```bash-composio search "create a github issue"-composio search "send an email" --toolkits gmail-composio search "send an email" "create a github issue"-composio search "my emails" "my github issues" --toolkits gmail,github+composio execute GITHUB_CREATE_ISSUE --get-schema+composio execute GITHUB_CREATE_ISSUE --dry-run \+ -d '{ owner: "acme", repo: "app", title: "Bug" }'```-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`.+Use the validation escape hatches only when you know what you are doing:++```bash+composio execute GITHUB_CREATE_ISSUE --skip-connection-check -d @issue.json+composio execute GITHUB_CREATE_ISSUE --skip-tool-params-check -d @issue.json+composio execute GITHUB_CREATE_ISSUE --skip-checks -d @issue.json+```-Use `--human` when you want a readable summary in the terminal. Leave it off when you want JSON output for scripting.+Upload a local file when the tool exposes exactly one uploadable file input:-## Inspect a known slug+```bash+composio execute SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK \+ --file ./image.png \+ -d '{ channels: "C123" }'+```-Use `composio tools info` as a compact fallback when you already know the slug and want a quick summary:+Run independent tool calls concurrently with `-p` / `--parallel`:```bash-composio tools info GITHUB_CREATE_ISSUE-composio tools list gmail+composio execute -p \+ GMAIL_SEND_EMAIL -d '{ recipient_email: "[email protected]", subject: "Hi", body: "Hello" }' \+ GITHUB_CREATE_ISSUE -d '{ owner: "acme", repo: "app", title: "Bug" }'```-For most execution questions, `composio execute --get-schema` or `--dry-run` is a better first step than `tools info`.+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.-## Connect accounts with link+## Connect and manage accounts-`composio link` connects an external account for a toolkit such as GitHub, Gmail, or Slack.+`composio link` connects an external account for a toolkit such as GitHub, Gmail, Slack, or Google Calendar.```bashcomposio link github+composio link gmail --alias work+```-# Print the auth URL and exit immediately+Useful link options:++```bash+# Print link info and exit without waiting for browser authorizationcomposio link github --no-wait++# List existing connected accounts for a toolkit+composio link github --list```-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.+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.-## End-to-end flow+Inspect or remove connected accounts with `connections`:```bash-composio search "star a github repo" --human-composio tools info GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER-composio execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER --dry-run -d '{"owner":"composiohq","repo":"composio"}'-composio link github-composio execute GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER -d '{"owner":"composiohq","repo":"composio"}'+composio connections list+composio connections list --toolkit github+composio connections remove github+composio connections remove work```-## Script multi-step workflows with run+Aliases for duplicate toolkit accounts require the `multi_account` experimental feature:-Use `composio run` when one tool call is not enough and you want to stay inside the CLI.+```bash+composio config experimental multi_account on+```++## Inspect tools and triggers++Use `tools` and `triggers` when you already know the toolkit or slug and want a compact summary.-The runtime injects helpers that mirror the CLI:+```bash+# Tools+composio tools list gmail+composio tools list gmail --query "send" --tags important --limit 20+composio tools info GMAIL_SEND_EMAIL++# Trigger types+composio triggers list gmail+composio triggers list gmail --limit 20+composio triggers info GMAIL_NEW_GMAIL_MESSAGE+```-- `execute(slug, data?)`-- `search(query, opts?)`-- `proxy(toolkit)`-- `experimental_subAgent(prompt, opts?)`-- `z`+For execution arguments, `composio execute <slug> --get-schema` is usually the most direct schema view.++## Listen to trigger events++`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.++```bash+composio listen GMAIL_NEW_GMAIL_MESSAGE+composio listen GMAIL_NEW_GMAIL_MESSAGE --timeout 5m+composio listen GMAIL_NEW_GMAIL_MESSAGE --max-events 5+```++Pass trigger creation params as JSON, JS-style object literals, `@file`, or stdin:++```bash+composio listen SLACK_RECEIVE_MESSAGE \+ -p '{ trigger_config: { channel: "C123" } }' \+ --max-events 10++composio listen GMAIL_NEW_GMAIL_MESSAGE -p @trigger.json --stream+```++Use `--stream` to also print each payload inline. You can pass a jq-like path to stream one field:++```bash+composio listen GMAIL_NEW_GMAIL_MESSAGE --timeout 1hr --stream '.data.threadId'+```++See where payload artifacts are stored:++```bash+composio artifacts cwd+```++## Script workflows with run++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.++Injected helpers:++| Helper | Description |+| --- | --- |+| `execute(slug, data?)` | Run a tool, like `composio execute`, and return parsed JSON |+| `search(query, opts?)` | Find tools, like `composio search` |+| `proxy(toolkit)` | Return a `fetch()` bound to a connected account for that toolkit |+| `experimental_subAgent(prompt, opts?)` | Ask a Claude/Codex sub-agent, optionally with structured output |+| `result.prompt()` | Serialize any helper result into an LLM-friendly string |+| `z` | Global Zod instance for structured output schemas |Examples:```bash# Inline workflow+composio run '+ const me = await execute("GITHUB_GET_THE_AUTHENTICATED_USER");+ console.log(me);+'++# Sequential actions across servicescomposio run 'const issue = await execute("GITHUB_CREATE_ISSUE", {owner: "acme",repo: "app",- title: "Bug report",- body: "Steps to reproduce..."+ title: "Deploy v2"+ });+ await execute("SLACK_SEND_A_MESSAGE_TO_A_SLACK_CHANNEL", {+ channel: "eng",+ text: "Created: " + issue.data.html_url});- console.log(issue);'-# Run a workflow from a file-composio run --file ./workflow.ts -- --repo composiohq/composio+# Run a file and pass script args after --+composio run --file ./workflow.ts -- --repo acme/app```-Use `run` when you want loops, conditionals, `Promise.all`, `search()` inside a script, `proxy()`, `experimental_subAgent()`, or a reusable workflow file.+Debug or preview scripts:++```bash+composio run --dry-run 'await execute("GMAIL_SEND_EMAIL", { recipient_email: "[email protected]" })'+composio run --debug --file ./workflow.ts+composio run --logs-off '/* hide experimental_subAgent streaming logs */'+```++Use top-level `composio execute -p` instead when you only need a few independent tool calls and no script logic.## Call raw APIs with proxy-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`.+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.```bash-composio proxy /gmail/v1/users/me/profile --toolkit gmail-composio proxy /gmail/v1/users/me/drafts --toolkit gmail -X POST -H 'content-type: application/json' -d '{"message":{"raw":"..."}}'+composio proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit gmail++composio proxy https://gmail.googleapis.com/gmail/v1/users/me/drafts \+ --toolkit gmail \+ -X POST \+ -H 'content-type: application/json' \+ -d '{"message":{"raw":"..."}}'```-<Callout type="warn">-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.-</Callout>+`-d` accepts raw text, JSON, `@file`, or `-` for stdin. Use `--skip-connection-check` only when you need to bypass the connected-account preflight.-Use `proxy` when:+You can also use `proxy()` inside `composio run`:-- there is no dedicated tool for the endpoint you need-- you already know the exact API endpoint to call-- you want Composio to handle auth while you keep full control over the request+```bash+composio run '+ const gmail = await proxy("gmail");+ const profile = await gmail("https://gmail.googleapis.com/gmail/v1/users/me/profile");+ console.log(profile);+'+```-## Developer project commands+## Generate type definitions-Use the `dev` namespace only for developer-project setup and inspection commands, not for the normal consumer-style search and execute flow.+Generate TypeScript or Python type stubs for selected toolkits, tools, and triggers. The current CLI requires at least one `--toolkits` value.```bash-# Initialize local developer project context-composio dev init+# Auto-detect TypeScript or Python from the project+composio generate --toolkits github gmail++# TypeScript+composio generate ts --toolkits github gmail+composio generate ts --toolkits github --output-dir ./src/composio-types+composio generate ts --toolkits github --compact+composio generate ts --toolkits github --transpiled+composio generate ts --toolkits github --type-tools++# Python+composio generate py --toolkits github gmail+composio generate py --toolkits github --output-dir ./composio_types+```-# Execute a tool against a playground user-composio dev playground-execute GITHUB_CREATE_ISSUE --user-id demo-user -d '{"owner":"acme","repo":"app","title":"Bug"}'+<Callout type="info">+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.+</Callout>-# Inspect triggers and logs-composio dev listen --toolkits github --table-composio dev logs tools-composio dev logs triggers-```+## Local files, artifacts, and config-## Command summary+Show where the CLI stores local data:-Run `composio <command> --help` for detailed usage and flags.+```bash+composio files+composio artifacts cwd+```-- `composio execute`: First choice when the slug is known.-- `composio search`: Discovery step when the slug is unknown.-- `composio link`: Recovery step when a toolkit account is missing.-- `composio run`: Programmatic workflows and LLM-driven scripting.-- `composio proxy`: Raw authenticated API access.-- `composio dev`: Developer-project commands only.+Important locations:-## Global flags+| Path | Purpose |+| --- | --- |+| `~/.composio/` | CLI auth, config, cached tool/toolkit definitions, trigger types, analytics ID, and per-org consumer caches |+| `$TMPDIR/composio/` | Session artifacts, large outputs, downloaded files, and run/execute history |+| `.composio/` | Optional per-project config such as `.env` and `project.json` |-| Flag | Description |-| --------------------- | ----------------------------------------------------------------------------------- |-| `--log-level <level>` | Set log level: `all`, `trace`, `debug`, `info`, `warning`, `error`, `fatal`, `none` |-| `--help` | Show help for any command |+Useful path environment variables:-## Environment variables+| Variable | Description |+| --- | --- |+| `COMPOSIO_SESSION_DIR` | Override the session artifacts root |+| `COMPOSIO_CACHE_DIR` | Override the cache directory and artifact fallback location |-| Variable | Description |-| ------------------------------------ | ---------------------------------------------------------------------------- |-| `COMPOSIO_API_KEY` | Your Composio API key |-| `COMPOSIO_BASE_URL` | Custom API base URL |-| `COMPOSIO_WEB_URL` | Custom Composio dashboard URL |-| `COMPOSIO_CACHE_DIR` | Override the CLI cache directory |-| `COMPOSIO_SESSION_DIR` | Override the session artifacts root directory |-| `COMPOSIO_LOG_LEVEL` | Default logging level |-| `COMPOSIO_DISABLE_TELEMETRY` | Set to `"true"` to disable telemetry |-| `COMPOSIO_TOOLKIT_VERSION_{TOOLKIT}` | Override toolkit version (e.g. `COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00`) |-| `COMPOSIO_WEBHOOK_SECRET` | Signing secret for trigger webhook forwarding |-| `FORCE_USE_CACHE` | Force cache-first reads for generated toolkit and tool metadata |-| `DEBUG_OVERRIDE_VERSION` | Override the target CLI version during upgrade debugging |+View or toggle experimental CLI features:-## Generate type definitions+```bash+composio config experimental+composio config experimental listen+composio config experimental multi_account on+composio config experimental multi_account off+```-<Callout type="info">- Type generation is only useful if you're using [direct tool- execution](/docs/tools-direct/executing-tools). If you're using sessions with meta tools, you- don't need this.-</Callout>+## Developer project commands-Generate TypeScript or Python type definitions for Composio tools. These types provide autocomplete and type safety when using direct tool execution (`composio.tools.execute()`).+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.```bash-composio generate+# Initialize this directory with a developer project+composio dev init++# Turn developer mode on or off+composio dev --mode on+composio dev --mode off++# Execute a tool against a developer playground user+composio dev playground-execute GMAIL_SEND_EMAIL \+ --user-id demo-user \+ -d '{ recipient_email: "[email protected]", subject: "Hello" }'++# Inspect logs+composio dev logs tools --toolkit gmail --limit 20+composio dev logs tools log_xxx+composio dev logs triggers --limit 20++# Stream developer-project trigger events+composio dev listen --toolkits gmail --table+composio dev listen --trigger-slug GMAIL_NEW_GMAIL_MESSAGE --json --max-events 5+composio dev listen --toolkits github --forward https://example.com/webhook```-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`.+Common `dev` groups:++| Group | Examples |+| --- | --- |+| Project | `dev init`, `dev projects list`, `dev projects switch` |+| Execution | `dev playground-execute`, `dev listen`, `dev logs tools`, `dev logs triggers` |+| Toolkits | `dev toolkits list`, `dev toolkits info`, `dev toolkits search`, `dev toolkits version` |+| Auth configs | `dev auth-configs list`, `dev auth-configs info`, `dev auth-configs create` |+| Connected accounts | `dev connected-accounts link`, `list`, `info`, `whoami` |+| Triggers | `dev triggers list`, `info`, `status`, `create`, `enable`, `disable` |-<Tabs items={['TypeScript', 'Python']}>- <Tab value="TypeScript">- ```bash- composio generate ts- ```+Disabling trigger instances is guarded. It requires `developer.destructive_actions: true` in `~/.composio/config.json` and `--dangerously-allow` on the command line.- | Flag | Description |- | --- | --- |- | `-o`, `--output-dir <dir>` | Output directory |- | `--compact` | Emit a single TypeScript file |- | `--transpiled` | Emit transpiled JavaScript alongside TypeScript |- | `--type-tools` | Generate typed schemas for each tool (slower) |- | `--toolkits <names>` | Only generate for specific toolkits (repeatable) |+## Agent skill installation- </Tab>- <Tab value="Python">- ```bash- composio generate py- ```+The CLI can install Composio skills into supported coding agents when auto-installation fails or you want to install manually.- | Flag | Description |- | --- | --- |- | `-o`, `--output-dir <dir>` | Output directory |- | `--toolkits <names>` | Only generate for specific toolkits (repeatable) |+```bash+composio --install-skill claude+composio --install-skill composio-cli codex+composio --install-skill composio-cli openclaw+```++`composio login` installs the `composio-cli` skill for Claude Code by default. Pass `--no-skill-install` to skip it.++## Command summary++| Command | Use it for |+| --- | --- |+| `composio search` | Find tool slugs by use case |+| `composio execute` | Run a known tool slug, inspect schemas, dry-run, or parallelize tool calls |+| `composio link` | Connect an account for a toolkit |+| `composio connections` | List or remove connected accounts |+| `composio tools` | List tools for a toolkit or inspect a known tool |+| `composio triggers` | List or inspect trigger types |+| `composio listen` | Create temporary consumer-project trigger subscriptions |+| `composio run` | Script multi-step workflows with injected helpers |+| `composio proxy` | Call raw toolkit APIs with Composio-managed auth |+| `composio signup` / `composio agent` | Bootstrap and manage an agent-owned Composio identity |+| `composio generate` | Generate TypeScript or Python stubs for selected toolkits |+| `composio dev` | Manage developer-project workflows |+| `composio artifacts` / `composio files` | Inspect local artifact and config/cache paths |+| `composio orgs` / `composio config` | Manage organization context and CLI config |+| `composio version` / `composio upgrade` | Check and update the CLI |++## Environment variables- </Tab>-</Tabs>+| Variable | Description |+| --- | --- |+| `COMPOSIO_API_KEY` | Composio project API key for API and SDK usage |+| `COMPOSIO_BASE_URL` | Custom Composio API base URL |+| `COMPOSIO_WEB_URL` | Custom Composio dashboard URL |+| `COMPOSIO_SESSION_DIR` | Override the CLI session artifact root |+| `COMPOSIO_CACHE_DIR` | Override the CLI cache directory |+| `COMPOSIO_LOG_LEVEL` | Default logging level |+| `COMPOSIO_DISABLE_TELEMETRY` | Set to `"true"` to disable telemetry |+| `COMPOSIO_TOOLKIT_VERSION_{TOOLKIT}` | Override a toolkit version, for example `COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00` |+| `COMPOSIO_WEBHOOK_SECRET` | Signing secret for trigger webhook forwarding |+| `COMPOSIO_ORG_ID` | Per-project or environment organization override |+| `COMPOSIO_PROJECT_ID` | Per-project or environment project override |+| `FORCE_USE_CACHE` | Force cache-first reads for generated toolkit and tool metadata |+| `DEBUG_OVERRIDE_VERSION` | Override target CLI version during upgrade debugging |diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.jsonindex b7a2d5657..fb6ff75a9 100644--- a/docs/content/docs/meta.json+++ b/docs/content/docs/meta.json@@ -36,6 +36,7 @@"tools-direct","auth-configuration","---Resources---",+ "signing-up-as-an-agent","common-faq","glossary","debugging-info",diff --git a/docs/content/docs/quickstart.mdx b/docs/content/docs/quickstart.mdxindex f3a8489d7..265dd3713 100644--- a/docs/content/docs/quickstart.mdx+++ b/docs/content/docs/quickstart.mdx@@ -6,6 +6,10 @@ keywords: [tutorial, setup, first agent]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.+<Callout type="info">+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.+</Callout>+<QuickstartFlow><FrameworkOption id="openai-agents" name="OpenAI Agents" logo="/images/providers/openai-logo.svg" logoDark="/images/providers/openai-logo-dark.svg">diff --git a/docs/content/docs/signing-up-as-an-agent.mdx b/docs/content/docs/signing-up-as-an-agent.mdxnew file mode 100644index 000000000..8b55c5134--- /dev/null+++ b/docs/content/docs/signing-up-as-an-agent.mdx@@ -0,0 +1,193 @@+---+title: Signing Up as an Agent+description: Create and reuse a Composio account programmatically from an AI agent+keywords: [agent signup, agents, cli, api key, anonymous signup]+---++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.++The base URL for all endpoints on this page is:++```text+https://agents.composio.dev+```++## Flow++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.+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.+3. **Install and log in to the CLI.** Call `GET /api/cli` with the `agent_key`. It returns paste-ready install and login commands.+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.++## Sign up++`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.++```bash+mkdir -p ~/.composio++curl -sS -X POST 'https://agents.composio.dev/api/signup' \+ -H 'content-type: application/json' \+ -d '{}' \+ -o ~/.composio/anonymous_user_data.json++cat ~/.composio/anonymous_user_data.json+```++Successful response:++```json+{+ "status": "ready",+ "request_id": "req_xxx",+ "slug": "amber-cedar-otter",+ "email": "[email protected]",+ "agent_key": "composio_agent_key_xxx",+ "composio": {+ "member_id": "uuid",+ "org_id": "org_xxx",+ "project_id": "proj_xxx",+ "api_key": "ak_xxx",+ "user_api_key": "uak_xxx"+ }+}+```++If the 120-second wait expires, the endpoint returns `202` with `status: "pending"`. Poll `GET /api/whoami` until the status is `READY`.++```json+{+ "status": "pending",+ "request_id": "req_xxx",+ "slug": "amber-cedar-otter",+ "email": "[email protected]",+ "agent_key": "composio_agent_key_xxx",+ "poll": "/api/whoami"+}+```++To skip waiting and poll yourself, pass `?wait=0`:++```bash+curl -sS -X POST 'https://agents.composio.dev/api/signup?wait=0' \+ -H 'content-type: application/json' \+ -d '{}'+```++## Verify a saved identity++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.++```bash+AGENT_KEY="$(jq -r '.agent_key' ~/.composio/anonymous_user_data.json)"++curl -sS 'https://agents.composio.dev/api/whoami' \+ -H "Authorization: Bearer ${AGENT_KEY}"+```++Response:++```json+{+ "slug": "amber-cedar-otter",+ "email": "[email protected]",+ "status": "READY",+ "claimed_by": null,+ "claimed_at": null,+ "composio": {+ "member_id": "uuid",+ "org_id": "org_xxx",+ "project_id": "proj_xxx",+ "api_key": "ak_xxx",+ "user_api_key": "uak_xxx"+ }+}+```++## Install the CLI++`GET /api/cli` returns install and login commands with the agent's `user_api_key` and `org_id` already filled in.++```bash+AGENT_KEY="$(jq -r '.agent_key' ~/.composio/anonymous_user_data.json)"++curl -sS 'https://agents.composio.dev/api/cli' \+ -H "Authorization: Bearer ${AGENT_KEY}"+```++Example response:++```text+Install Composio CLI using this command:+curl -fsSL https://composio.dev/install | bash++Then log in using this command:+composio login --user-api-key "uak_..." --org "ok_..."+```++Run the returned commands to install and authenticate the CLI.++## Claim the organization++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.++```bash+AGENT_KEY="$(jq -r '.agent_key' ~/.composio/anonymous_user_data.json)"++curl -sS -X POST 'https://agents.composio.dev/api/claim' \+ -H "Authorization: Bearer ${AGENT_KEY}" \+ -H 'content-type: application/json' \+ -d '{"email":"[email protected]"}'+```++Response:++```json+{+ "status": "invited",+ "email": "[email protected]",+ "org_id": "org_xxx",+ "invite_code": "inv_xxx"+}+```++## Read the agent inbox++Each agent gets an email address at `<slug>@agent.composio.ai`. Use `GET /api/mail` to list messages for the agent inbox.++```bash+AGENT_KEY="$(jq -r '.agent_key' ~/.composio/anonymous_user_data.json)"++curl -sS 'https://agents.composio.dev/api/mail?limit=50' \+ -H "Authorization: Bearer ${AGENT_KEY}"+```++Response:++```json+{+ "count": 1,+ "messages": [+ {+ "id": "msg_xxx",+ "thread_id": "thr_xxx",+ "from": "[email protected]",+ "to": "[email protected]",+ "subject": "Sign in to Composio",+ "preview": "Click the link below to sign in...",+ "received_at": "2026-04-13T22:00:00.000Z"+ }+ ]+}+```++## Agent keys++Agent keys are prefixed with `composio_agent_key_` and are only valid for these endpoints:++- `GET /api/whoami`+- `GET /api/mail`+- `GET /api/cli`+- `POST /api/claim`++Use the real Composio API key from the `composio.api_key` field when calling Composio APIs and SDKs.