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: update CLI and reference navigation (#3462)
Rahul Tarak3411c39adc7e
diff --git a/docs/app/(home)/docs/layout.tsx b/docs/app/(home)/docs/layout.tsxindex 13b488700..d7f97acb9 100644--- a/docs/app/(home)/docs/layout.tsx+++ b/docs/app/(home)/docs/layout.tsx@@ -1,30 +1,10 @@import { source } from '@/lib/source';import { DocsLayout } from 'fumadocs-ui/layouts/docs';-// Insert changelog into page tree after Get Started section-const changelogPage = { type: 'page' as const, name: 'Changelog', url: '/docs/changelog' };-const children = source.pageTree.children;-const getStartedIdx = children.findIndex(- (c) => c.type === 'separator' && c.name === 'Get Started'-);-// Find next separator after Get Started, or use end of array if not found-const nextSeparatorIdx = getStartedIdx === -1- ? -1- : children.findIndex((c, i) => i > getStartedIdx && c.type === 'separator');-// If we can't find proper insertion point, append at the end-const insertIdx = nextSeparatorIdx === -1 ? children.length : nextSeparatorIdx;-const pageTree = {- ...source.pageTree,- children: [- ...children.slice(0, insertIdx),- changelogPage,- ...children.slice(insertIdx),- ] as typeof children,-};export default function Layout({ children }: LayoutProps<'/docs'>) {return (<DocsLayout- tree={pageTree}+ tree={source.pageTree}nav={{ enabled: true, title: null }}sidebar={{ collapsible: false, footer: null, tabs: false }}themeSwitch={{ enabled: false }}diff --git a/docs/app/(home)/reference/(v31)/changelog/page.tsx b/docs/app/(home)/reference/(v31)/changelog/page.tsxnew file mode 100644index 000000000..0f78d0384--- /dev/null+++ b/docs/app/(home)/reference/(v31)/changelog/page.tsx@@ -0,0 +1,111 @@+import { changelogEntries, formatDate, getOgImageUrl } from '@/lib/source';+import type { Metadata } from 'next';++const description = 'Latest updates and announcements for Composio';++export const metadata: Metadata = {+ title: 'Changelog | Composio',+ description,+ alternates: { canonical: '/reference/changelog' },+ openGraph: {+ title: 'Changelog | Composio',+ description,+ images: [getOgImageUrl('reference', ['changelog'], 'Changelog', description)],+ },+ twitter: {+ card: 'summary_large_image',+ title: 'Changelog | Composio',+ description,+ images: [getOgImageUrl('reference', ['changelog'], 'Changelog', description)],+ },+};+import { getMDXComponents } from '@/mdx-components';+import {+ DocsBody,+ DocsPage,+ DocsTitle,+} from 'fumadocs-ui/layouts/docs/page';+import { CopyLink } from '@/components/copy-link';+import { PageActions } from '@/components/page-actions';+import { EditOnGitHub } from '@/components/edit-on-github';++const mdxComponents = getMDXComponents();++function dateToChangelogAnchor(date: string) {+ return `#${date}`;+}++export default function ChangelogPage() {+ const entries = [...changelogEntries].sort(+ (a, b) => new Date(b.date).getTime() - new Date(a.date).getTime()+ );+ const entriesByDate = new Map<string, typeof entries>();+ for (const entry of entries) {+ const group = entriesByDate.get(entry.date) ?? [];+ group.push(entry);+ entriesByDate.set(entry.date, group);+ }+ const groupedEntries = [...entriesByDate.entries()];+ const toc = [+ { title: 'Changelog', url: '#changelog', depth: 2 },+ { title: 'Latest', url: '#latest', depth: 3 },+ ...groupedEntries.slice(0, 20).map(([date]) => ({+ title: formatDate(date),+ url: dateToChangelogAnchor(date),+ depth: 3,+ })),+ ];++ return (+ <DocsPage toc={toc} footer={{ enabled: false }}>+ <DocsTitle id="changelog">Changelog</DocsTitle>+ <PageActions path="/reference/changelog" />+ <DocsBody>+ <p className="text-fd-muted-foreground">+ Latest updates and announcements for Composio.+ </p>+ <h2 id="latest">Latest</h2>+ <div className="relative">+ <div className="absolute left-0 top-2 bottom-0 w-px bg-border hidden md:block md:left-[7.5rem]" />++ <div className="space-y-12">+ {groupedEntries.map(([date, dateEntries]) => (+ <article key={date} className="relative">+ <div className="mb-3 md:absolute md:left-0 md:w-28 md:text-right md:pr-6">+ <h3 id={date} className="m-0 scroll-mt-24 text-sm font-medium">+ <CopyLink+ href={dateToChangelogAnchor(date)}+ className="text-blue-500 hover:text-blue-600 transition-colors"+ >+ {formatDate(date)}+ </CopyLink>+ </h3>+ </div>++ <div className="hidden md:block absolute left-[7.5rem] top-1.5 -translate-x-1/2">+ <div className="w-2.5 h-2.5 rounded-full bg-primary ring-4 ring-background" />+ </div>++ <div className="space-y-10 md:pl-36">+ {dateEntries.map((entry) => {+ const Content = entry.body;++ return (+ <section key={`${entry.date}-${entry.title}`}>+ <h2 className="text-2xl font-semibold mb-4">{entry.title}</h2>+ <div className="prose prose-neutral dark:prose-invert max-w-none">+ <Content components={mdxComponents} />+ </div>+ </section>+ );+ })}+ </div>+ </article>+ ))}+ </div>+ </div>+ <EditOnGitHub path="docs/app/(home)/reference/(v31)/changelog/page.tsx" />+ </DocsBody>+ </DocsPage>+ );+}diff --git a/docs/app/(home)/reference/(v31)/layout.tsx b/docs/app/(home)/reference/(v31)/layout.tsxindex 14aee9fa8..53b15d2f6 100644--- a/docs/app/(home)/reference/(v31)/layout.tsx+++ b/docs/app/(home)/reference/(v31)/layout.tsx@@ -6,10 +6,23 @@ import { prepareTree } from '@/lib/filter-api-version';export default async function Layout({ children }: { children: ReactNode }) {const source = await getReferenceSource();const tree = prepareTree(source.pageTree, '3.1');+ const changelogPage = { type: 'page' as const, name: 'Changelog', url: '/reference/changelog' };+ const errorsIdx = tree.children.findIndex(+ (child: { type: string; name?: string }) => child.type === 'page' && child.name === 'Errors'+ );+ const insertIdx = errorsIdx === -1 ? Math.min(4, tree.children.length) : errorsIdx + 1;+ const pageTree = {+ ...tree,+ children: [+ ...tree.children.slice(0, insertIdx),+ changelogPage,+ ...tree.children.slice(insertIdx),+ ] as typeof tree.children,+ };return (<DocsLayout- tree={tree}+ tree={pageTree}nav={{ enabled: true, title: null }}searchToggle={{ enabled: false }}sidebar={{ collapsible: false, footer: null, tabs: false }}diff --git a/docs/components/claude-mock-ui.tsx b/docs/components/claude-mock-ui.tsxindex 0f0e9731c..c004806bf 100644--- a/docs/components/claude-mock-ui.tsx+++ b/docs/components/claude-mock-ui.tsx@@ -5,7 +5,23 @@ type ClaudeMockUIProps = {title?: string;};-export function ClaudeMockUI({ children, title = 'user — ✻ Claude Code — claude' }: ClaudeMockUIProps) {+function ClaudeLogo() {+ return (+ <svg+ aria-hidden="true"+ className="size-3.5 shrink-0"+ preserveAspectRatio="xMidYMid"+ viewBox="0 0 256 257"+ >+ <path+ fill="#D97757"+ d="m50.228 170.321 50.357-28.257.843-2.463-.843-1.361h-2.462l-8.426-.518-28.775-.778-24.952-1.037-24.175-1.296-6.092-1.297L0 125.796l.583-3.759 5.12-3.434 7.324.648 16.202 1.101 24.304 1.685 17.629 1.037 26.118 2.722h4.148l.583-1.685-1.426-1.037-1.101-1.037-25.147-17.045-27.22-18.017-14.258-10.37-7.713-5.25-3.888-4.925-1.685-10.758 7-7.713 9.397.649 2.398.648 9.527 7.323 20.35 15.75L94.817 91.9l3.889 3.24 1.555-1.102.195-.777-1.75-2.917-14.453-26.118-15.425-26.572-6.87-11.018-1.814-6.61c-.648-2.723-1.102-4.991-1.102-7.778l7.972-10.823L71.42 0 82.05 1.426l4.472 3.888 6.61 15.101 10.694 23.786 16.591 32.34 4.861 9.592 2.592 8.879.973 2.722h1.685v-1.556l1.36-18.211 2.528-22.36 2.463-28.776.843-8.1 4.018-9.722 7.971-5.25 6.222 2.981 5.12 7.324-.713 4.73-3.046 19.768-5.962 30.98-3.889 20.739h2.268l2.593-2.593 10.499-13.934 17.628-22.036 7.778-8.749 9.073-9.657 5.833-4.601h11.018l8.1 12.055-3.628 12.443-11.342 14.388-9.398 12.184-13.48 18.147-8.426 14.518.778 1.166 2.01-.194 30.46-6.481 16.462-2.982 19.637-3.37 8.88 4.148.971 4.213-3.5 8.62-20.998 5.184-24.628 4.926-36.682 8.685-.454.324.519.648 16.526 1.555 7.065.389h17.304l32.21 2.398 8.426 5.574 5.055 6.805-.843 5.184-12.962 6.611-17.498-4.148-40.83-9.721-14-3.5h-1.944v1.167l11.666 11.406 21.387 19.314 26.767 24.887 1.36 6.157-3.434 4.86-3.63-.518-23.526-17.693-9.073-7.972-20.545-17.304h-1.36v1.814l4.73 6.935 25.017 37.59 1.296 11.536-1.814 3.76-6.481 2.268-7.13-1.297-14.647-20.544-15.1-23.138-12.185-20.739-1.49.843-7.194 77.448-3.37 3.953-7.778 2.981-6.48-4.925-3.436-7.972 3.435-15.749 4.148-20.544 3.37-16.333 3.046-20.285 1.815-6.74-.13-.454-1.49.194-15.295 20.999-23.267 31.433-18.406 19.702-4.407 1.75-7.648-3.954.713-7.064 4.277-6.286 25.47-32.405 15.36-20.092 9.917-11.6-.065-1.686h-.583L44.07 198.125l-12.055 1.555-5.185-4.86.648-7.972 2.463-2.593 20.35-13.999-.064.065Z"+ />+ </svg>+ );+}++export function ClaudeMockUI({ children, title = 'Claude Code' }: ClaudeMockUIProps) {return (<div className="not-prose my-6 overflow-hidden rounded-xl border border-[#dedede] bg-[#f6f6f6] shadow-sm"><div className="flex items-center gap-2 border-[#d8d8d8] border-b bg-[#e8e8e8] px-3 py-2">@@ -14,9 +30,11 @@ export function ClaudeMockUI({ children, title = 'user — ✻ Claude Code — c<span className="h-[11px] w-[11px] rounded-full bg-[#febc2e]" /><span className="h-[11px] w-[11px] rounded-full bg-[#28c840]" /></div>- <span className="flex-1 truncate text-left font-mono text-[#888] text-[11px]">- {title}- </span>+ <div className="flex min-w-0 flex-1 items-center gap-1.5 text-left font-mono text-[#888] text-[11px]">+ <span className="truncate">user —</span>+ <ClaudeLogo />+ <span className="truncate">{title}</span>+ </div></div><div className="space-y-4 bg-[#f6f6f6] p-5 font-mono text-[13px] text-[#2d2d2d] leading-7 md:text-sm [&_a]:text-[#0000ee] [&_a]:underline [&_a]:underline-offset-2 [&_p]:m-0 [&_strong]:font-semibold [&_strong]:text-[#111]">{children}diff --git a/docs/components/page-actions.tsx b/docs/components/page-actions.tsxindex 18df6dab1..a17cdc42d 100644--- a/docs/components/page-actions.tsx+++ b/docs/components/page-actions.tsx@@ -212,17 +212,20 @@ function ChatGPTMark({ className }: { className?: string }) {);}-/** Tiny inline Anthropic Claude mark (asterisk/burst), monochrome currentColor. */+function ClaudeMark({ className }: { className?: string }) {return (<svgclassName={className}- viewBox="0 0 24 24"- fill="currentColor"+ preserveAspectRatio="xMidYMid"+ viewBox="0 0 256 257"aria-hidden="true"xmlns="http://www.w3.org/2000/svg">- <path d="M4.709 15.955l4.72-2.647.079-.23-.079-.128h-.23l-.787-.048-2.687-.073-2.331-.097L1.078 12.6l-.582-.74.058-.385.49-.327.701.063 1.55.105 2.327.16 3.376.198 4.802.205-.018-.07L17.16 7.31l.215.06.21.124.214.214.06.21-.124.214-2.31 2.31-.214.215-.06.21-.124.214.124.214.06.21.214.214 2.31 2.31.124.214.06.21-.21.124-.214.06-.215-.06-3.06-2.06-.31-.16-1.06-.06-.124.06-.06.21.124.214 1.95 2.954.214.214.06.21-.06.21-.214.214.214.214.06.21-.06.21.214.214.214.214-.06.21-.21.124-.214.06-3.06-2.06z" />+ <path+ fill="#D97757"+ d="m50.228 170.321 50.357-28.257.843-2.463-.843-1.361h-2.462l-8.426-.518-28.775-.778-24.952-1.037-24.175-1.296-6.092-1.297L0 125.796l.583-3.759 5.12-3.434 7.324.648 16.202 1.101 24.304 1.685 17.629 1.037 26.118 2.722h4.148l.583-1.685-1.426-1.037-1.101-1.037-25.147-17.045-27.22-18.017-14.258-10.37-7.713-5.25-3.888-4.925-1.685-10.758 7-7.713 9.397.649 2.398.648 9.527 7.323 20.35 15.75L94.817 91.9l3.889 3.24 1.555-1.102.195-.777-1.75-2.917-14.453-26.118-15.425-26.572-6.87-11.018-1.814-6.61c-.648-2.723-1.102-4.991-1.102-7.778l7.972-10.823L71.42 0 82.05 1.426l4.472 3.888 6.61 15.101 10.694 23.786 16.591 32.34 4.861 9.592 2.592 8.879.973 2.722h1.685v-1.556l1.36-18.211 2.528-22.36 2.463-28.776.843-8.1 4.018-9.722 7.971-5.25 6.222 2.981 5.12 7.324-.713 4.73-3.046 19.768-5.962 30.98-3.889 20.739h2.268l2.593-2.593 10.499-13.934 17.628-22.036 7.778-8.749 9.073-9.657 5.833-4.601h11.018l8.1 12.055-3.628 12.443-11.342 14.388-9.398 12.184-13.48 18.147-8.426 14.518.778 1.166 2.01-.194 30.46-6.481 16.462-2.982 19.637-3.37 8.88 4.148.971 4.213-3.5 8.62-20.998 5.184-24.628 4.926-36.682 8.685-.454.324.519.648 16.526 1.555 7.065.389h17.304l32.21 2.398 8.426 5.574 5.055 6.805-.843 5.184-12.962 6.611-17.498-4.148-40.83-9.721-14-3.5h-1.944v1.167l11.666 11.406 21.387 19.314 26.767 24.887 1.36 6.157-3.434 4.86-3.63-.518-23.526-17.693-9.073-7.972-20.545-17.304h-1.36v1.814l4.73 6.935 25.017 37.59 1.296 11.536-1.814 3.76-6.481 2.268-7.13-1.297-14.647-20.544-15.1-23.138-12.185-20.739-1.49.843-7.194 77.448-3.37 3.953-7.778 2.981-6.48-4.925-3.436-7.972 3.435-15.749 4.148-20.544 3.37-16.333 3.046-20.285 1.815-6.74-.13-.454-1.49.194-15.295 20.999-23.267 31.433-18.406 19.702-4.407 1.75-7.648-3.954.713-7.064 4.277-6.286 25.47-32.405 15.36-20.092 9.917-11.6-.065-1.686h-.583L44.07 198.125l-12.055 1.555-5.185-4.86.648-7.972 2.463-2.593 20.35-13.999-.064.065Z"+ /></svg>);}diff --git a/docs/content/docs/cli.mdx b/docs/content/docs/cli.mdxindex bde7aea96..6d79280ae 100644--- a/docs/content/docs/cli.mdx+++ b/docs/content/docs/cli.mdx@@ -1,498 +1,266 @@----title: CLI-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]+title: Composio CLI+description: Use the Composio CLI inside Claude Code for knowledge work, debugging, and developer workflows.+keywords: [cli, claude code, command line, terminal, composio for you, knowledge work, dev 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 Composio CLI is primarily the command-line surface for [Composio for You](https://composio.dev/for-you). It is meant to be installed in your terminal and used from inside **Claude Code**, so Claude can connect apps, execute tools, inspect schemas, call authenticated APIs, and debug Composio projects while it works with you.-The default workflow is:+Use the CLI directly when you want to give Claude Code a reliable local tool surface instead of copying API keys, schemas, and one-off scripts into chat.-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 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+## Install```bashcurl -fsSL https://composio.dev/install | bash-```--Check the installed version and upgrade when needed:--```bash-composio --version-composio upgrade-```--Set up shell integration after installing or moving the binary:--```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:--```bashcomposio login-composio whoami```-Useful login options:+Then open Claude Code in the project where you want to work. `composio login` installs the `composio-cli` skill for Claude Code by default. To install the skill manually:```bash-# Print a login URL/session and exit without waiting-composio login --no-wait--# Complete login with the key from a no-wait session-composio login --key "session_key"--# 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 --install-skill composio-cli claude```-Manage your default organization context:+Check your local state:```bash-composio orgs list-composio orgs switch --org-id "org_xxx"-```--Log out when you want to clear local auth state:--```bash-composio logout+composio whoami+composio --version+composio upgrade```-## 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).+## 1. Using Composio CLI for knowledge work-```bash-# Sign up as an agent and log the CLI in when credentials are ready-composio signup+This is the recommended way to use Composio from inside Claude Code. The CLI can execute tools for you, connect accounts, script workflows, call authenticated APIs, and inspect trigger events without you wiring a custom integration first.-# Start signup and exit without waiting for credentials-composio signup --no-wait+### 1.1 Search, connect, and execute tools-# 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:+Use this flow when Claude needs to act in one of your connected apps:```bash-composio agent signup-composio agent login "composio_agent_key_..."-composio agent whoami-composio agent inbox --limit 20-composio agent claim [email protected]-```--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.--## Search for tools+# Find the right tool+composio search "summarize my unread gmail"-Use `composio search` when you do not know the tool slug. It accepts one or more semantic queries and returns JSON by default.+# Inspect the required input schema+composio execute GMAIL_FETCH_EMAILS --get-schema-```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-```--Use `--human` for readable terminal output:+# Connect the app if needed+composio link gmail-```bash-composio search "create a github issue" --human+# Execute the tool+composio execute GMAIL_FETCH_EMAILS \+ -d '{ query: "is:unread newer_than:1d", max_results: 10 }'```-Once you have a slug, switch back to `composio execute`.--## Execute tools+Useful commands:-`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 GITHUB_CREATE_ISSUE \- -d '{ owner: "acme", repo: "app", title: "Bug report", body: "Steps to reproduce..." }'-```+| Command | Use it for |+|---------|------------|+| `composio search` | Find relevant tools by natural language |+| `composio execute` | Execute a known tool slug |+| `composio link` | Connect an app account |+| `composio proxy` | Call provider APIs with Composio-managed auth |-The `-d` / `--data` flag accepts JSON, JS-style object literals, files, or stdin:+Use `composio proxy` when Claude already knows the provider API endpoint and wants Composio to inject auth from your connected account:```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 -+composio proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit gmail```-Inspect the schema or preview a call without executing it:+### 1.2 Run scripts and sub-agents-```bash-composio execute GITHUB_CREATE_ISSUE --get-schema-composio execute GITHUB_CREATE_ISSUE --dry-run \- -d '{ owner: "acme", repo: "app", title: "Bug" }'-```+Use `composio run` when Claude needs a multi-step workflow, loops, parallel fan-out, data transformation, or LLM-assisted summarization. It runs inline TS/JS or a file with `execute()`, `search()`, `proxy()`, `experimental_subAgent()`, `result.prompt()`, and `z` injected.-Use the validation escape hatches only when you know what you are doing:+Run a single scripted workflow:```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+composio run '+const messages = await execute("GMAIL_FETCH_EMAILS", {+ query: "is:unread newer_than:1d",+ max_results: 10,+});+console.log(messages);+'```-Upload a local file when the tool exposes exactly one uploadable file input:+Fan out across multiple tools:```bash-composio execute SLACK_UPLOAD_OR_CREATE_A_FILE_IN_SLACK \- --file ./image.png \- -d '{ channels: "C123" }'+composio run '+const [emails, issues, events] = await Promise.all([+ execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),+ execute("GITHUB_LIST_REPOSITORY_ISSUES", { owner: "composiohq", repo: "composio", state: "open" }),+ execute("GOOGLECALENDAR_FIND_EVENT", { calendar_id: "primary" }),+]);+console.log({ emails: emails.data, issues: issues.data, events: events.data });+'```-Run independent tool calls concurrently with `-p` / `--parallel`:+Ask a sub-agent to summarize tool output and return structured data:```bash-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" }'-```--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.+composio run --logs-off '+const [emails, issues] = await Promise.all([+ execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),+ execute("GITHUB_LIST_REPOSITORY_ISSUES", { owner: "composiohq", repo: "composio", state: "open" }),+]);-## Connect and manage accounts+const brief = await experimental_subAgent(+ `Create a morning brief from these emails and issues.\n\n${emails.prompt()}\n\n${issues.prompt()}`,+ {+ schema: z.object({+ brief: z.string(),+ urgentEmails: z.array(z.string()),+ urgentIssues: z.array(z.string()),+ }),+ }+);-`composio link` connects an external account for a toolkit such as GitHub, Gmail, Slack, or Google Calendar.--```bash-composio link github-composio link gmail --alias work+console.log(brief.structuredOutput);+'```-Useful link options:+Run a checked-in script:```bash-# Print link info and exit without waiting for browser authorization-composio link github --no-wait--# List existing connected accounts for a toolkit-composio link github --list+composio run --file ./workflow.ts -- --repo composiohq/composio```-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.--Inspect or remove connected accounts with `connections`:--```bash-composio connections list-composio connections list --toolkit github-composio connections remove github-composio connections remove work-```+### 1.3 Listen to trigger events-Aliases for duplicate toolkit accounts require the `multi_account` experimental feature:+Use trigger listening when Claude needs to wait for new events, inspect incoming payloads, or forward events while debugging. In the current CLI, trigger event streaming is exposed through the developer namespace:```bash-composio config experimental multi_account on-```+# Compact table view for matching events+composio dev listen --toolkits gmail --table-## Inspect tools and triggers+# Raw JSON payloads, then stop after five events+composio dev listen --trigger-slug GMAIL_NEW_GMAIL_MESSAGE --json --max-events 5-Use `tools` and `triggers` when you already know the toolkit or slug and want a compact summary.+# Forward each matching event to a local or hosted webhook+composio dev listen --toolkits github --forward https://example.com/webhook-```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+# Append matching events to a local file for Claude to inspect+composio dev listen --toolkits slack --out ./events.jsonl```-For execution arguments, `composio execute <slug> --get-schema` is usually the most direct schema view.+Filter by toolkit, trigger slug, trigger ID, connected account ID, or user ID when you want Claude to focus on one event source.-## Listen to trigger events+## 2. Using Composio CLI to build on Composio-`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.+Use the CLI while building on the Composio developer platform. These commands help initialize local project context, create auth configs, manage connected accounts, test tool execution, inspect logs, and debug trigger flows.-```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:+### Initialize project context```bash-composio listen SLACK_RECEIVE_MESSAGE \- -p '{ trigger_config: { channel: "C123" } }' \- --max-events 10--composio listen GMAIL_NEW_GMAIL_MESSAGE -p @trigger.json --stream-```+# Initialize local project context+composio dev init-Use `--stream` to also print each payload inline. You can pass a jq-like path to stream one field:+# Toggle developer mode+composio dev --mode on+composio dev --mode off-```bash-composio listen GMAIL_NEW_GMAIL_MESSAGE --timeout 1hr --stream '.data.threadId'+# Switch or inspect project scope+composio dev projects list+composio dev projects switch```-See where payload artifacts are stored:+### Inspect toolkits and versions```bash-composio artifacts cwd+composio dev toolkits list+composio dev toolkits search "email"+composio dev toolkits info github+composio dev toolkits version github```-## 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:+### Create and inspect auth configs```bash-# Inline workflow-composio run '- const me = await execute("GITHUB_GET_THE_AUTHENTICATED_USER");- console.log(me);-'--# Sequential actions across services-composio run '- const issue = await execute("GITHUB_CREATE_ISSUE", {- owner: "acme",- repo: "app",- title: "Deploy v2"- });- await execute("SLACK_SEND_A_MESSAGE_TO_A_SLACK_CHANNEL", {- channel: "eng",- text: "Created: " + issue.data.html_url- });-'+# List existing auth configs+composio dev auth-configs list+composio dev auth-configs list --toolkits github,gmail+composio dev auth-configs info ac_xxx-# Run a file and pass script args after ---composio run --file ./workflow.ts -- --repo acme/app-```--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 */'+# Create an auth config from provider credentials+composio dev auth-configs create "GitHub OAuth" \+ --toolkit github \+ --auth-scheme OAUTH2 \+ --scopes "repo,user" \+ --custom-credentials '{ "client_id": "...", "client_secret": "..." }'```-Use top-level `composio execute -p` instead when you only need a few independent tool calls and no script logic.+### Manage connected accounts-## Call raw APIs with proxy--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.+Top-level `composio link` is the fastest path for personal knowledge work. Use developer connected-account commands when you are building against project users, auth configs, and playground flows.```bash-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":"..."}}'+composio dev connected-accounts list+composio dev connected-accounts list --toolkits github --user-id user_123+composio dev connected-accounts list --status ACTIVE --limit 20+composio dev connected-accounts info ca_xxx+composio dev connected-accounts whoami ca_xxx+composio dev connected-accounts link```-`-d` accepts raw text, JSON, `@file`, or `-` for stdin. Use `--skip-connection-check` only when you need to bypass the connected-account preflight.--You can also use `proxy()` inside `composio run`:+### Execute and inspect logs```bash-composio run '- const gmail = await proxy("gmail");- const profile = await gmail("https://gmail.googleapis.com/gmail/v1/users/me/profile");- console.log(profile);-'-```--## Generate type definitions--Generate TypeScript or Python type stubs for selected toolkits, tools, and triggers. The current CLI requires at least one `--toolkits` value.+# Execute a tool through the developer playground path+composio dev playground-execute GMAIL_SEND_EMAIL \+ -d '{ recipient_email: "[email protected]", subject: "Test", body: "Hello" }'-```bash-# 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+# Inspect tool and trigger logs+composio dev logs tools --toolkit gmail --limit 20+composio dev logs tools log_xxx+composio dev logs triggers --limit 20```-<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>--## Local files, artifacts, and config--Show where the CLI stores local data:+### Work with triggers```bash-composio files-composio artifacts cwd+composio dev triggers list gmail+composio dev triggers info GMAIL_NEW_GMAIL_MESSAGE+composio dev triggers status+composio dev triggers create+composio dev triggers enable ti_xxx+composio dev listen --trigger-slug GMAIL_NEW_GMAIL_MESSAGE --json --max-events 5```-Important locations:+### Generate type definitions-| 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` |--Useful path environment variables:--| Variable | Description |-| --- | --- |-| `COMPOSIO_SESSION_DIR` | Override the session artifacts root |-| `COMPOSIO_CACHE_DIR` | Override the cache directory and artifact fallback location |--View or toggle experimental CLI features:+For legacy direct tool execution projects, generate local TypeScript or Python types from tool schemas:```bash-composio config experimental-composio config experimental listen-composio config experimental multi_account on-composio config experimental multi_account off+composio generate+composio generate ts --toolkits github,gmail+composio generate py --toolkits github,gmail```-## Developer project commands+Use this section when you are debugging auth configs, connected accounts, trigger delivery, or tool execution in a Composio project. For general user-facing app development, prefer the SDK/session docs first and use the CLI as a local debugging companion.-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.+## 3. Building directly on top of the CLI-```bash-# Initialize this directory with a developer project-composio dev init+Building products directly on top of the CLI is **not recommended**. The CLI is in constant development and Composio does not provide CLI-level SLAs as an application runtime contract.-# Turn developer mode on or off-composio dev --mode on-composio dev --mode off+If you need a stable production integration, build on top of the Composio SDKs and APIs instead.-# 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" }'+That said, the CLI can be useful as a bootstrap or helper layer for agent-native products:-# 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-```--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` |+- Use [Signing up as an agent](/docs/signing-up-as-an-agent) when an agent needs to programmatically create or reuse a Composio identity.+- Use `composio connections list` to inspect which connected accounts are available locally.+- Use `composio run` or `composio proxy` for internal automations where CLI churn is acceptable.-Disabling trigger instances is guarded. It requires `developer.destructive_actions: true` in `~/.composio/config.json` and `--dangerously-allow` on the command line.+For an example of a product built around CLI-driven agent workflows, see [Houston](https://github.com/gethouston/houston).-## Agent skill installation+## Help-The CLI can install Composio skills into supported coding agents when auto-installation fails or you want to install manually.+Use `--help` on the root command or any subcommand:```bash-composio --install-skill claude-composio --install-skill composio-cli codex-composio --install-skill composio-cli openclaw+composio --help+composio --help full+composio execute --help full+composio run --help full+composio dev --help full```--`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--| 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 57cbdf73f..57f4b8b03 100644--- a/docs/content/docs/meta.json+++ b/docs/content/docs/meta.json@@ -4,7 +4,6 @@"index","quickstart","providers",- "cli","---Customizing sessions---","how-composio-works","configuring-sessions",@@ -28,11 +27,11 @@"tools-direct","auth-configuration","---Other topics---",+ "cli","native-tools-vs-mcp","proxy-execute","projects","observability",- "single-toolkit-mcp","signing-up-as-an-agent","common-faq","glossary",diff --git a/docs/next.config.mjs b/docs/next.config.mjsindex 2221d8f8b..3a54a342e 100644--- a/docs/next.config.mjs+++ b/docs/next.config.mjs@@ -58,6 +58,26 @@ const config = {destination: '/docs',permanent: true,},+ {+ source: '/docs/changelog',+ destination: '/reference/changelog',+ permanent: true,+ },+ {+ source: '/docs/changelog/:year/:month/:day',+ destination: '/reference/changelog#:year-:month-:day',+ permanent: true,+ },+ {+ source: '/reference/changelog/:year/:month/:day',+ destination: '/reference/changelog#:year-:month-:day',+ permanent: true,+ },+ {+ source: '/docs/changelog/:path*',+ destination: '/reference/changelog',+ permanent: true,+ },{source: '/getting-started/welcome',destination: '/docs',