1
---
2
title: CLI
3
-description: Generate type definitions and manage authentication
4
-keywords: [command line, generate types]
3
+description: Install the Composio CLI to manage toolkits, execute tools, handle authentication, and generate type-safe code from the terminal.
4
+keywords: [cli, command line, terminal, toolkits, tools, authentication, generate types]
5
---
6
7
-The Composio CLI helps you generate type-safe code and manage your Composio workspace.
7
+The Composio CLI gives you full control over your Composio workspace from the terminal — discover toolkits, execute tools, manage authentication, subscribe to triggers, inspect logs, and generate type-safe code.
8
9
## Installation
10
11
-Install the Composio CLI using the installation script:
12
-
11
```bash
12
curl -fsSL https://composio.dev/install | bash
13
```
14
15
Or using wget:
16
+
17
```bash
18
wget -qO- https://composio.dev/install | bash
19
```
20
22
-## Authentication
21
+## Getting started
22
+
23
+Log in, initialize a project, and verify your setup:
24
+
25
+```bash
26
+# Authenticate with Composio
27
+composio login
28
+
29
+# Initialize a project in the current directory
30
+composio init
31
+
32
+# Verify your identity
33
+composio whoami
34
+
35
+# Check CLI version
36
+composio version
37
+```
38
+
39
+## Command reference
40
+
41
+| Command | Description |
42
+| --- | --- |
43
+| [`login`](#login) | Authenticate with your Composio account |
44
+| [`logout`](#logout) | Remove stored authentication |
45
+| [`whoami`](#whoami) | Display your account information |
46
+| [`init`](#init) | Initialize a Composio project |
47
+| [`toolkits`](#toolkits) | Discover and inspect toolkits |
48
+| [`tools`](#tools) | Discover, inspect, and execute tools |
49
+| [`connected-accounts`](#connected-accounts) | Manage connected accounts |
50
+| [`auth-configs`](#auth-configs) | Manage auth configurations |
51
+| [`triggers`](#triggers) | Inspect and subscribe to trigger events |
52
+| [`logs`](#logs) | Inspect tool and trigger execution logs |
53
+| [`generate`](#generate) | Generate type stubs (auto-detects language) |
54
+| [`ts generate`](#ts-generate) | Generate TypeScript type stubs |
55
+| [`py generate`](#py-generate) | Generate Python type stubs |
56
+| [`upgrade`](#upgrade) | Upgrade CLI to the latest version |
57
+| [`version`](#version) | Display the current CLI version |
58
24
-Manage your Composio authentication directly from the terminal.
59
+---
60
26
-### Login
61
+## Authentication & setup
62
28
-Authenticate with your Composio account:
63
+### login
64
+
65
+Authenticate with your Composio account.
66
67
```bash
68
composio login
70
71
This opens your browser to complete authentication and stores your API key locally.
72
36
-To authenticate without opening a browser (useful for SSH/remote sessions):
73
+| Flag | Description |
74
+| --- | --- |
75
+| `--no-browser` | Login without opening a browser (displays a URL to open manually) |
76
+| `--api-key <key>` | API key for non-interactive login (CI/agents) |
77
+| `--org-id <id>` | Organization ID (required with `--api-key`) |
78
+| `--project-id <id>` | Project ID (required with `--api-key`) |
79
80
```bash
81
+# Remote/SSH sessions
82
composio login --no-browser
83
+
84
+# Non-interactive (CI/agents)
85
+composio login --api-key "sk_..." --org-id "org_..." --project-id "proj_..."
86
```
87
42
-This displays a URL to manually open in your browser.
88
+### logout
89
+
90
+Remove stored authentication.
91
+
92
+```bash
93
+composio logout
94
+```
95
44
-### Check authentication status
96
+### whoami
97
46
-Verify your current authentication:
98
+Display your account information and API key.
99
100
```bash
101
composio whoami
102
```
103
52
-This displays your current API key or indicates if you're not authenticated.
104
+### init
105
54
-### Logout
106
+Initialize a Composio project in the current directory. Creates `.composio/project.json` with your org and project IDs.
107
56
-Remove stored authentication:
108
+```bash
109
+composio init
110
+```
111
+
112
+| Flag | Description |
113
+| --- | --- |
114
+| `--org-id <id>` | Organization ID (skip interactive picker) |
115
+| `--project-id <id>` | Project ID (skip interactive picker) |
116
+| `-y`, `--yes` | Auto-select default org and project |
117
+| `--no-browser` | Skip auto-opening the browser |
118
119
```bash
59
-composio logout
120
+# Auto-select defaults
121
+composio init --yes
122
+
123
+# Specify org and project directly
124
+composio init --org-id "org_..." --project-id "proj_..."
125
+```
126
+
127
+---
128
+
129
+## Toolkits
130
+
131
+Discover and inspect Composio toolkits.
132
+
133
+### toolkits list
134
+
135
+List available toolkits with connection status.
136
+
137
+```bash
138
+composio toolkits list
139
+```
140
+
141
+| Flag | Description |
142
+| --- | --- |
143
+| `--query <text>` | Search by name, slug, or description |
144
+| `--connected` | Show only connected toolkits |
145
+| `--user-id <id>` | User ID for connection status |
146
+| `--limit <n>` | Results per page (default: 30) |
147
+
148
+```bash
149
+composio toolkits list --query "email" --connected
150
+```
151
+
152
+### toolkits info
153
+
154
+View details of a specific toolkit.
155
+
156
+```bash
157
+composio toolkits info <slug>
158
+```
159
+
160
+| Flag | Description |
161
+| --- | --- |
162
+| `--user-id <id>` | User ID for connection status |
163
+| `-a`, `--all` | Show all details including auth config fields |
164
+
165
+```bash
166
+composio toolkits info github --all
167
+```
168
+
169
+### toolkits search
170
+
171
+Search toolkits by use case.
172
+
173
+```bash
174
+composio toolkits search <query>
175
+```
176
+
177
+| Flag | Description |
178
+| --- | --- |
179
+| `--limit <n>` | Results per page (default: 10) |
180
+
181
+```bash
182
+composio toolkits search "send emails"
183
+```
184
+
185
+### toolkits version
186
+
187
+Show latest and recent versions for a toolkit.
188
+
189
+```bash
190
+composio toolkits version <slug>
191
+```
192
+
193
+```bash
194
+composio toolkits version gmail
195
+```
196
+
197
+---
198
+
199
+## Tools
200
+
201
+Discover, inspect, and execute Composio tools.
202
+
203
+### tools list
204
+
205
+List available tools.
206
+
207
+```bash
208
+composio tools list --toolkits "gmail"
209
+```
210
+
211
+| Flag | Description |
212
+| --- | --- |
213
+| `--query <text>` | Search by name, slug, or description |
214
+| `--toolkits <slugs>` | Filter by toolkit slugs (comma-separated) |
215
+| `--tags <tags>` | Filter by tags |
216
+| `--limit <n>` | Results per page (default: 30) |
217
+
218
+```bash
219
+composio tools list --toolkits "gmail,slack" --query "send"
220
+```
221
+
222
+### tools info
223
+
224
+View details of a specific tool, including its input schema.
225
+
226
+```bash
227
+composio tools info <slug>
228
+```
229
+
230
+```bash
231
+composio tools info GMAIL_SEND_EMAIL
232
+```
233
+
234
+### tools search
235
+
236
+Semantically search tools by use case. Returns the most relevant tools plus recommended usage guidance.
237
+
238
+```bash
239
+composio tools search <query>
240
+```
241
+
242
+| Flag | Description |
243
+| --- | --- |
244
+| `--toolkits <slugs>` | Filter by toolkit slugs (comma-separated) |
245
+| `--limit <n>` | Results per page (default: 10) |
246
+
247
+```bash
248
+composio tools search "onboard a new GitHub repo and notify Slack"
249
+```
250
+
251
+### tools execute
252
+
253
+Execute a tool with JSON arguments.
254
+
255
+```bash
256
+composio tools execute <slug> --data '<json>'
257
+```
258
+
259
+| Flag | Description |
260
+| --- | --- |
261
+| `-d`, `--data <json>` | JSON arguments, `@file`, or `-` for stdin |
262
+| `--user-id <id>` | User ID to execute as |
263
+
264
+```bash
265
+# Inline JSON
266
+composio tools execute GITHUB_GET_REPOS -d '{"owner":"composio"}'
267
+
268
+# From file
269
+composio tools execute GMAIL_SEND_EMAIL -d @payload.json
270
+
271
+# From stdin
272
+echo '{"owner":"composio"}' | composio tools execute GITHUB_GET_REPOS
273
+```
274
+
275
+---
276
+
277
+## Connected accounts
278
+
279
+Manage authenticated connections to external services.
280
+
281
+### connected-accounts list
282
+
283
+List connected accounts.
284
+
285
+```bash
286
+composio connected-accounts list
287
+```
288
+
289
+| Flag | Description |
290
+| --- | --- |
291
+| `--toolkits <slugs>` | Filter by toolkit slugs (comma-separated) |
292
+| `--user-id <id>` | Filter by user ID |
293
+| `--status <status>` | Filter by status: `ACTIVE`, `FAILED`, `EXPIRED`, `INITIALIZING`, `INITIATED`, `INACTIVE` |
294
+| `--limit <n>` | Results per page (default: 30) |
295
+
296
+```bash
297
+composio connected-accounts list --toolkits "gmail" --status ACTIVE
298
+```
299
+
300
+### connected-accounts info
301
+
302
+View details of a specific connected account.
303
+
304
+```bash
305
+composio connected-accounts info <id>
306
+```
307
+
308
+```bash
309
+composio connected-accounts info con_1a2b3c4d5e6f
310
+```
311
+
312
+### connected-accounts whoami
313
+
314
+Show the external account profile for a connected account.
315
+
316
+```bash
317
+composio connected-accounts whoami <id>
318
+```
319
+
320
+```bash
321
+composio connected-accounts whoami con_1a2b3c4d5e6f
322
+```
323
+
324
+### connected-accounts link
325
+
326
+Link an external account via OAuth redirect.
327
+
328
+```bash
329
+composio connected-accounts link <toolkit>
330
+```
331
+
332
+| Flag | Description |
333
+| --- | --- |
334
+| `--auth-config <id>` | Auth config ID (uses legacy flow, mutually exclusive with `<toolkit>`) |
335
+| `--user-id <id>` | User ID for the connection |
336
+| `--no-browser` | Skip auto-opening the browser |
337
+
338
+```bash
339
+# Link using Tool Router (default)
340
+composio connected-accounts link github
341
+
342
+# Link with specific auth config
343
+composio connected-accounts link --auth-config "ac_..." --user-id "alice"
344
+```
345
+
346
+### connected-accounts delete
347
+
348
+Delete a connected account.
349
+
350
+```bash
351
+composio connected-accounts delete <id>
352
+```
353
+
354
+| Flag | Description |
355
+| --- | --- |
356
+| `-y`, `--yes` | Skip confirmation prompt |
357
+
358
+---
359
+
360
+## Auth configs
361
+
362
+Manage auth configurations for toolkits.
363
+
364
+### auth-configs list
365
+
366
+List auth configs.
367
+
368
+```bash
369
+composio auth-configs list
370
+```
371
+
372
+| Flag | Description |
373
+| --- | --- |
374
+| `--toolkits <slugs>` | Filter by toolkit slugs (comma-separated) |
375
+| `--query <text>` | Search by auth config name |
376
+| `--limit <n>` | Results per page (default: 30) |
377
+
378
+```bash
379
+composio auth-configs list --toolkits "gmail"
380
+```
381
+
382
+### auth-configs info
383
+
384
+View details of a specific auth config.
385
+
386
+```bash
387
+composio auth-configs info <id>
388
+```
389
+
390
+```bash
391
+composio auth-configs info ac_1232323
392
+```
393
+
394
+### auth-configs create
395
+
396
+Create a new auth config.
397
+
398
+```bash
399
+composio auth-configs create <name> --toolkit <toolkit>
400
+```
401
+
402
+| Flag | Description |
403
+| --- | --- |
404
+| `--toolkit <slug>` | Toolkit slug (required) |
405
+| `--auth-scheme <scheme>` | Auth scheme: `OAUTH2`, `API_KEY`, `BEARER_TOKEN`, etc. |
406
+| `--scopes <scopes>` | Comma-separated OAuth scopes |
407
+| `--custom-credentials <json>` | Custom credentials JSON (for white-labeling) |
408
+
409
+```bash
410
+# Composio-managed defaults
411
+composio auth-configs create "my-gmail-config" --toolkit "gmail"
412
+
413
+# Custom OAuth with scopes
414
+composio auth-configs create "custom-gmail" --toolkit "gmail" --auth-scheme "OAUTH2" --scopes "send_email,read_email"
415
+
416
+# White-labeled with custom credentials
417
+composio auth-configs create "custom-gmail" --toolkit "gmail" --auth-scheme "OAUTH2" \
418
+ --custom-credentials '{"client_id":"...","client_secret":"..."}'
419
+```
420
+
421
+### auth-configs delete
422
+
423
+Delete an auth config.
424
+
425
+```bash
426
+composio auth-configs delete <id>
427
+```
428
+
429
+| Flag | Description |
430
+| --- | --- |
431
+| `-y`, `--yes` | Skip confirmation prompt |
432
+
433
+---
434
+
435
+## Triggers
436
+
437
+Subscribe to external events and manage trigger instances.
438
+
439
+### triggers list
440
+
441
+List available trigger types.
442
+
443
+```bash
444
+composio triggers list
445
+```
446
+
447
+| Flag | Description |
448
+| --- | --- |
449
+| `--toolkits <slugs>` | Filter by toolkit slugs (comma-separated) |
450
+| `--limit <n>` | Max results (default: 30) |
451
+
452
+```bash
453
+composio triggers list --toolkits "gmail,slack"
454
+```
455
+
456
+### triggers info
457
+
458
+View details of a specific trigger type.
459
+
460
+```bash
461
+composio triggers info <slug>
462
+```
463
+
464
+```bash
465
+composio triggers info GMAIL_NEW_GMAIL_MESSAGE
466
+```
467
+
468
+### triggers create
469
+
470
+Create a new trigger instance.
471
+
472
+```bash
473
+composio triggers create <trigger-name>
474
+```
475
+
476
+| Flag | Description |
477
+| --- | --- |
478
+| `--connected-account-id <id>` | Connected account ID |
479
+| `--trigger-config <json>` | Trigger config as JSON |
480
+
481
+```bash
482
+composio triggers create GMAIL_NEW_GMAIL_MESSAGE --connected-account-id "con_123"
483
+
484
+composio triggers create SLACK_NEW_MESSAGE --connected-account-id "con_456" \
485
+ --trigger-config '{"channel":"#general"}'
486
+```
487
+
488
+### triggers status
489
+
490
+Show active trigger instances with optional filters.
491
+
492
+```bash
493
+composio triggers status
494
+```
495
+
496
+| Flag | Description |
497
+| --- | --- |
498
+| `--user-ids <ids>` | Filter by user IDs (comma-separated) |
499
+| `--connected-account-ids <ids>` | Filter by connected account IDs (comma-separated) |
500
+| `--toolkits <slugs>` | Filter by toolkit slugs (comma-separated) |
501
+| `--trigger-ids <ids>` | Filter by trigger instance IDs (comma-separated) |
502
+| `--trigger-names <names>` | Filter by trigger names (comma-separated) |
503
+| `--show-disabled` | Include disabled triggers |
504
+| `--limit <n>` | Results per page (default: 30) |
505
+
506
+```bash
507
+composio triggers status --user-ids "alice,bob" --show-disabled
508
+```
509
+
510
+### triggers listen
511
+
512
+Listen to realtime trigger events.
513
+
514
+```bash
515
+composio triggers listen
516
+```
517
+
518
+| Flag | Description |
519
+| --- | --- |
520
+| `--toolkits <slugs>` | Filter by toolkit slugs (comma-separated) |
521
+| `--trigger-id <id>` | Filter by trigger ID |
522
+| `--trigger-slug <slugs>` | Filter by trigger slug (comma-separated) |
523
+| `--connected-account-id <id>` | Filter by connected account ID |
524
+| `--user-id <id>` | Filter by user ID |
525
+| `--json` | Show raw event payload as JSON |
526
+| `--table` | Show compact table rows |
527
+| `--max-events <n>` | Stop after N matching events |
528
+| `--forward <url>` | Forward each event to a URL |
529
+| `--out <file>` | Append each event to a file |
530
+
531
+```bash
532
+# Stream Gmail events as a table
533
+composio triggers listen --toolkits gmail --table
534
+
535
+# Forward events to a local server
536
+composio triggers listen --forward "http://localhost:8080/webhook"
537
+
538
+# Capture events to a file
539
+composio triggers listen --trigger-slug GMAIL_NEW_GMAIL_MESSAGE --out events.jsonl --max-events 10
540
+```
541
+
542
+### triggers enable
543
+
544
+Enable a trigger instance.
545
+
546
+```bash
547
+composio triggers enable <id>
548
+```
549
+
550
+### triggers disable
551
+
552
+Disable a trigger instance.
553
+
554
+```bash
555
+composio triggers disable <id>
556
+```
557
+
558
+### triggers delete
559
+
560
+Delete a trigger instance.
561
+
562
+```bash
563
+composio triggers delete <id>
564
+```
565
+
566
+| Flag | Description |
567
+| --- | --- |
568
+| `-y`, `--yes` | Skip confirmation prompt |
569
+
570
+---
571
+
572
+## Logs
573
+
574
+Inspect tool and trigger execution logs.
575
+
576
+### logs tools
577
+
578
+List tool execution logs.
579
+
580
+```bash
581
+composio logs tools
582
+```
583
+
584
+Pass a log ID to fetch a specific log:
585
+
586
+```bash
587
+composio logs tools <log_id>
588
+```
589
+
590
+| Flag | Description |
591
+| --- | --- |
592
+| `--toolkit <slugs>` | Filter by toolkit (comma-separated) |
593
+| `--tool <slugs>` | Filter by tool (comma-separated) |
594
+| `--user-id <ids>` | Filter by user ID (comma-separated) |
595
+| `--connected-account-id <ids>` | Filter by connected account ID (comma-separated) |
596
+| `--auth-config-id <ids>` | Filter by auth config ID (comma-separated) |
597
+| `--status <values>` | Filter by execution status (comma-separated) |
598
+| `--from <ms>` | Start timestamp (epoch milliseconds) |
599
+| `--to <ms>` | End timestamp (epoch milliseconds) |
600
+| `--limit <n>` | Number of logs (default: 30) |
601
+| `--cursor <cursor>` | Cursor for pagination |
602
+
603
+```bash
604
+composio logs tools --toolkit gmail --status success --limit 50
605
+```
606
+
607
+### logs triggers
608
+
609
+List trigger logs.
610
+
611
+```bash
612
+composio logs triggers
613
+```
614
+
615
+Pass a log ID to fetch a specific log:
616
+
617
+```bash
618
+composio logs triggers <log_id>
619
+```
620
+
621
+| Flag | Description |
622
+| --- | --- |
623
+| `--trigger <name>` | Filter by trigger name |
624
+| `--trigger-id <id>` | Filter by trigger ID |
625
+| `--user-id <id>` | Filter by user ID |
626
+| `--connected-account-id <id>` | Filter by connected account ID |
627
+| `--from <ms>` | Start timestamp (epoch milliseconds) |
628
+| `--to <ms>` | End timestamp (epoch milliseconds) |
629
+| `--time <window>` | Relative time window: `5m`, `30m`, `6h`, `1d`, `1w`, `1month`, `1y` |
630
+| `--search <query>` | Full-text search |
631
+| `--include-payload` | Include payload fields |
632
+| `--limit <n>` | Number of logs (default: 30) |
633
+| `--cursor <cursor>` | Cursor for pagination |
634
+
635
+```bash
636
+composio logs triggers --trigger GMAIL_NEW_GMAIL_MESSAGE --time 1d
637
```
638
62
-## Generate type definitions
639
+---
640
64
-Generate TypeScript or Python type definitions for all Composio tools. These types provide type safety when using direct tool execution (`composio.tools.execute()`), helping you pass the correct parameters and catch errors early.
641
+## Type generation
642
66
-### Auto-detect and generate
643
+Generate type-safe definitions for toolkits, tools, and triggers. These types provide autocomplete and type safety when using direct tool execution (`composio.tools.execute()`).
644
68
-The CLI auto-detects your project language.
69
-In your project directory:
645
+### generate
646
+
647
+Auto-detect project language and generate types.
648
649
```bash
650
composio generate
651
```
652
75
-For TypeScript projects only, include individual tool types:
653
+| Flag | Description |
654
+| --- | --- |
655
+| `-o`, `--output-dir <dir>` | Output directory |
656
+| `--type-tools` | Generate typed schemas for each tool (TypeScript only, slower) |
657
+| `--toolkits <names>` | Only generate for specific toolkits (repeatable) |
658
+
659
```bash
77
-composio generate --type-tools
660
+composio generate --toolkits gmail --toolkits slack
661
```
662
80
-The CLI automatically:
81
-- Detects your project type (Python or TypeScript)
82
-- Generates appropriate type definitions
663
+### ts generate
664
84
-### Specify output directory
665
+Generate TypeScript type stubs.
666
667
```bash
87
-composio generate --output-dir ./my-types
668
+composio ts generate
669
```
670
90
-### Language-specific commands
671
+| Flag | Description |
672
+| --- | --- |
673
+| `-o`, `--output-dir <dir>` | Output directory |
674
+| `--compact` | Emit a single TypeScript file |
675
+| `--transpiled` | Emit transpiled JavaScript alongside TypeScript |
676
+| `--type-tools` | Generate typed schemas for each tool (slower) |
677
+| `--toolkits <names>` | Only generate for specific toolkits (repeatable) |
678
92
-For explicit control, use language-specific commands:
679
+```bash
680
+composio ts generate --compact --type-tools
681
+```
682
+
683
+### py generate
684
94
-<Tabs items={['TypeScript', 'Python']}>
95
- <Tab value="TypeScript">
96
- Basic generation:
97
- ```bash
98
- composio ts generate
99
- ```
685
+Generate Python type stubs.
686
101
- Generate as single file:
102
- ```bash
103
- composio ts generate --compact
104
- ```
687
+```bash
688
+composio py generate
689
+```
690
+
691
+| Flag | Description |
692
+| --- | --- |
693
+| `-o`, `--output-dir <dir>` | Output directory |
694
+| `--toolkits <names>` | Only generate for specific toolkits (repeatable) |
695
+
696
+```bash
697
+composio py generate --output-dir ./my_types
698
+```
699
+
700
+---
701
+
702
+## Maintenance
703
+
704
+### upgrade
705
+
706
+Upgrade the CLI to the latest version.
707
+
708
+```bash
709
+composio upgrade
710
+```
711
+
712
+### version
713
+
714
+Display the current CLI version.
715
+
716
+```bash
717
+composio version
718
+```
719
+
720
+---
721
106
- Include individual tool types:
107
- ```bash
108
- composio ts generate --type-tools
109
- ```
722
+## Global options
723
111
- Generate both .ts and .js files:
112
- ```bash
113
- composio ts generate --transpiled
114
- ```
724
+| Flag | Description |
725
+| --- | --- |
726
+| `--log-level <level>` | Set log level: `silent`, `error`, `warn`, `info`, `debug` |
727
116
- Custom output directory:
117
- ```bash
118
- composio ts generate --output-dir ./my-types
119
- ```
120
- </Tab>
121
- <Tab value="Python">
122
- Basic generation:
123
- ```bash
124
- composio py generate
125
- ```
728
+## Environment variables
729
127
- Custom output directory:
128
- ```bash
129
- composio py generate --output-dir ./my_types
130
- ```
131
- </Tab>
132
-</Tabs>
730
+| Variable | Description |
731
+| --- | --- |
732
+| `COMPOSIO_API_KEY` | Your Composio API key (required for most commands) |
733
+| `COMPOSIO_BASE_URL` | Custom API base URL |
734
+| `COMPOSIO_LOG_LEVEL` | Logging level: `silent`, `error`, `warn`, `info`, `debug` |
735
+| `COMPOSIO_DISABLE_TELEMETRY` | Set to `"true"` to disable telemetry |
736
+| `COMPOSIO_TOOLKIT_VERSION_<TOOLKIT>` | Override toolkit version (e.g., `COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_00`) |
737
+| `COMPOSIO_WEBHOOK_SECRET` | Signing secret for trigger webhook forwarding |