Add direct user API key login to the CLI (#3132)

CryogenicPlanet · web-flow · commit d1ef6b25ecf9 · 2026-04-07T19:08:00.000-07:00
## Summary
- Adds a new `composio login --user-api-key` flow for direct login
without the browser/session-key path.
- Supports selecting a default organization with `--org` and validates
incompatible flag combinations.
- Updates login help, CLI docs, and command output so the direct login
path reports the selected org consistently.
- Expands login tests to cover help text and direct API key login
behavior.

## Testing
- `pnpm test -- login.cmd.test.ts` or equivalent CLI test run covering
the updated login command.
- Verified help output includes `--user-api-key` and `--org` and no
longer advertises legacy `--api-key`.
- Verified direct login stores the chosen org and writes the expected
user config values.
- Not run: full repository test suite.
diff --git a/ts/packages/cli/AGENTS.md b/ts/packages/cli/AGENTS.md
@@ -31,7 +31,7 @@ Each command is declared with `@effect/cli`'s `Command.make()` pattern:
 | -------------------------------------------------------- | ------------------------------------------------------------------------------------- |
 | `composio version`                                       | Display CLI version                                                                   |
 | `composio whoami`                                        | Show logged-in user's API key                                                         |
-| `composio login [--no-browser] [--no-wait] [--key text]` | Login with browser redirect                                                           |
+| `composio login [--no-browser] [--no-wait] [--key text] [--user-api-key text] [--org text]` | Login with browser redirect or direct user API key                                    |
 | `composio logout`                                        | Clear stored API key                                                                  |
 | `composio upgrade`                                       | Self-update binary from GitHub releases                                               |
 | `composio generate`                                      | Auto-detect project language, delegate to `ts` or `py`                                |
diff --git a/ts/packages/cli/README.md b/ts/packages/cli/README.md
@@ -27,7 +27,7 @@ composio [--log-level all|trace|debug|info|warning|error|fatal|none]
 
 - `composio version`: Display the current CLI version.
 - `composio whoami`: Show the currently logged-in user/account.
-- `composio login [--no-browser] [--no-wait] [--key text] [-y, --yes] [--no-skill-install]`: Log in to the Composio CLI session.
+- `composio login [--no-browser] [--no-wait] [--key text] [--user-api-key text] [--org text] [-y, --yes] [--no-skill-install]`: Log in to the Composio CLI session.
 - `composio logout`: Log out from the Composio CLI session.
 - `composio orgs list|switch`: Inspect and switch your default organization context.
 - `composio search <query...> [--toolkits text] [--limit integer] [--human]`: Find tools by use case across toolkits/apps.
diff --git a/ts/packages/cli/src/commands/login.cmd.ts b/ts/packages/cli/src/commands/login.cmd.ts
@@ -5,6 +5,7 @@ import {
   ComposioSessionRepository,
   getSessionInfo,
   getSessionInfoByUserApiKey,
+  listOrganizations,
   type SessionInfoResponse,
 } from 'src/services/composio-clients';
 import { ComposioUserContext } from 'src/services/user-context';
@@ -32,6 +33,16 @@ const keyOpt = Options.text('key').pipe(
   Options.optional
 );
 
+const userApiKeyOpt = Options.text('user-api-key').pipe(
+  Options.withDescription('Log in directly with a Composio user API key'),
+  Options.optional
+);
+
+const orgOpt = Options.text('org').pipe(
+  Options.withDescription('Default organization ID or name to store for CLI commands'),
+  Options.optional
+);
+
 const yesOpt = Options.boolean('yes').pipe(
   Options.withAlias('y'),
   Options.withDefault(false),
@@ -57,10 +68,107 @@ const formatLoginSuccessMessage = (params: { email?: string; orgName?: string })
   return 'Logged in successfully';
 };
 
+const emitLoginComplete = (params: {
+  email?: string;
+  orgId: string;
+  orgName?: string;
+  skipHints?: boolean;
+}) =>
+  Effect.gen(function* () {
+    const ui = yield* TerminalUI;
+    const { email, orgId, orgName, skipHints = false } = params;
+
+    yield* ui.log.success(formatLoginSuccessMessage({ email, orgName }));
+    if (!skipHints) {
+      yield* ui.log.info(commandHintStep('Execute a tool directly', 'root.execute'));
+      yield* ui.log.info(commandHintStep('Switch your default org', 'root.orgs.switch'));
+    }
+
+    yield* ui.output(
+      JSON.stringify({
+        email,
+        org_id: orgId,
+        org_name: orgName ?? '',
+      })
+    );
+
+    if (!skipHints) {
+      yield* ui.outro("You're all set!");
+    }
+  });
+
+const resolveDirectLoginOrganization = (params: {
+  apiKey: string;
+  baseURL: string;
+  requestedOrg?: string;
+  fallbackOrgId: string;
+  fallbackOrgName?: string;
+}) =>
+  Effect.gen(function* () {
+    const ui = yield* TerminalUI;
+    const { apiKey, baseURL, requestedOrg, fallbackOrgId, fallbackOrgName } = params;
+
+    if (!requestedOrg) {
+      return {
+        id: fallbackOrgId,
+        name: fallbackOrgName ?? fallbackOrgId,
+      };
+    }
+
+    const organizations = yield* listOrganizations({
+      baseURL,
+      apiKey,
+    });
+    const match = organizations.data.find(
+      org => org.id === requestedOrg || org.name === requestedOrg
+    );
+
+    if (!match) {
+      yield* ui.log.error(`Organization "${requestedOrg}" was not found for this API key.`);
+      return yield* Effect.fail(
+        new Error('Invalid organization. Run `composio orgs list` to inspect available orgs.')
+      );
+    }
+
+    return match;
+  });
+
+const directLogin = (params: { userApiKey: string; org?: string }) =>
+  Effect.gen(function* () {
+    const ctx = yield* ComposioUserContext;
+    const sessionInfo = yield* getSessionInfoByUserApiKey({
+      baseURL: ctx.data.baseURL,
+      userApiKey: params.userApiKey,
+    });
+
+    const selectedOrg = yield* resolveDirectLoginOrganization({
+      apiKey: params.userApiKey,
+      baseURL: ctx.data.baseURL,
+      requestedOrg: params.org,
+      fallbackOrgId: sessionInfo.project.org.id,
+      fallbackOrgName: sessionInfo.project.org.name,
+    });
+
+    const sessionUserId = sessionInfo.org_member.user_id ?? sessionInfo.org_member.id;
+    const testUserId = sessionUserId
+      ? `pg-test-${sessionUserId}`
+      : Option.getOrUndefined(ctx.data.testUserId);
+
+    yield* ctx.login(params.userApiKey, selectedOrg.id, testUserId);
+    yield* primeConsumerConnectedToolkitsCacheInBackground({
+      orgId: selectedOrg.id,
+    });
+    yield* emitLoginComplete({
+      email: sessionInfo.org_member.email || undefined,
+      orgId: selectedOrg.id,
+      orgName: selectedOrg.name,
+    });
+  });
+
 /**
  * Verifies credentials via session/info and stores them.
  *
- * Resolves TerminalUI and ComposioUserContext from the Effect context rather
+ * Resolves ComposioUserContext from the Effect context rather
  * than accepting them as parameters -- this keeps the signature focused on
  * data and avoids hand-rolled structural types.
  */
@@ -76,7 +184,6 @@ const storeCredentials = (params: {
   skipOutput?: boolean;
 }) =>
   Effect.gen(function* () {
-    const ui = yield* TerminalUI;
     const ctx = yield* ComposioUserContext;
 
     const {
@@ -131,27 +238,13 @@ const storeCredentials = (params: {
       orgId,
     });
 
-    const email = sessionInfo?.org_member.email || fallbackEmail || undefined;
-    const orgName = sessionInfo?.project.org.name || undefined;
-    yield* ui.log.success(formatLoginSuccessMessage({ email, orgName }));
-    if (!skipHints) {
-      yield* ui.log.info(commandHintStep('Execute a tool directly', 'root.execute'));
-      yield* ui.log.info(commandHintStep('Switch your default org', 'root.orgs.switch'));
-    }
-
-    // Emit structured JSON for piped/scripted consumption (agent-native)
     if (!skipOutput) {
-      yield* ui.output(
-        JSON.stringify({
-          email,
-          org_id: orgId,
-          org_name: sessionInfo?.project.org.name ?? '',
-        })
-      );
-    }
-
-    if (!skipHints) {
-      yield* ui.outro("You're all set!");
+      yield* emitLoginComplete({
+        email: sessionInfo?.org_member.email || fallbackEmail || undefined,
+        orgId,
+        orgName: sessionInfo?.project.org.name || undefined,
+        skipHints,
+      });
     }
   });
 
@@ -256,25 +349,14 @@ const loginWithKey = (params: { key: string; noWait: boolean; skipOrgProjectPick
         yield* primeConsumerConnectedToolkitsCacheInBackground({
           orgId: result.id,
         });
-        yield* ui.log.success(
-          formatLoginSuccessMessage({
-            email: uakSessionInfo.org_member.email || linkedSession.account.email || undefined,
-            orgName: result.name,
-          })
-        );
       }
       const finalOrgId = result?.id ?? xOrgId;
       const finalOrgName = result?.name ?? uakSessionInfo.project.org.name ?? '';
-      yield* ui.output(
-        JSON.stringify({
-          email: linkedSession.account.email ?? undefined,
-          org_id: finalOrgId,
-          org_name: finalOrgName,
-        })
-      );
-      yield* ui.log.info(commandHintStep('Execute a tool directly', 'root.execute'));
-      yield* ui.log.info(commandHintStep('Switch your default org', 'root.orgs.switch'));
-      yield* ui.outro("You're all set!");
+      yield* emitLoginComplete({
+        email: linkedSession.account.email ?? undefined,
+        orgId: finalOrgId,
+        orgName: finalOrgName,
+      });
     }
   });
 
@@ -421,25 +503,14 @@ export const browserLogin = (params: {
         yield* primeConsumerConnectedToolkitsCacheInBackground({
           orgId: result.id,
         });
-        yield* ui.log.success(
-          formatLoginSuccessMessage({
-            email: uakSessionInfo.org_member.email || linkedSession.account.email || undefined,
-            orgName: result.name,
-          })
-        );
       }
       const finalOrgId = result?.id ?? xOrgId;
       const finalOrgName = result?.name ?? uakSessionInfo.project.org.name ?? '';
-      yield* ui.output(
-        JSON.stringify({
-          email: linkedSession.account.email ?? undefined,
-          org_id: finalOrgId,
-          org_name: finalOrgName,
-        })
-      );
-      yield* ui.log.info(commandHintStep('Execute a tool directly', 'root.execute'));
-      yield* ui.log.info(commandHintStep('Switch your default org', 'root.orgs.switch'));
-      yield* ui.outro("You're all set!");
+      yield* emitLoginComplete({
+        email: linkedSession.account.email ?? undefined,
+        orgId: finalOrgId,
+        orgName: finalOrgName,
+      });
     }
   });
 
@@ -451,6 +522,7 @@ export const browserLogin = (params: {
  * Use --no-wait to print login URL and session info (JSON) then exit without opening browser or waiting.
  * Use --key to complete login with a session key from --no-wait. Without --no-wait, polls until linked;
  * with --no-wait, checks once and fails if not linked.
+ * Use --user-api-key to log in directly without a browser flow, and --org to override the default org.
  * Use -y to skip org picker and use session default org.
  *
  * @example
@@ -460,19 +532,45 @@ export const browserLogin = (params: {
  * composio login --no-wait
  * composio login --key <key>
  * composio login --key <key> --no-wait
+ * composio login --user-api-key <uak>
+ * composio login --user-api-key <uak> --org <org>
  * composio login -y
  * ```
  */
 export const loginCmd = Command.make(
   'login',
-  { noBrowser, noWait, key: keyOpt, yes: yesOpt, noSkillInstall },
-  ({ noBrowser, noWait, key, yes, noSkillInstall }) =>
+  {
+    noBrowser,
+    noWait,
+    key: keyOpt,
+    userApiKey: userApiKeyOpt,
+    org: orgOpt,
+    yes: yesOpt,
+    noSkillInstall,
+  },
+  ({ noBrowser, noWait, key, userApiKey, org, yes, noSkillInstall }) =>
     Effect.gen(function* () {
       const ui = yield* TerminalUI;
       const ctx = yield* ComposioUserContext;
 
       yield* ui.intro('composio login');
 
+      if (Option.isSome(key) && Option.isSome(userApiKey)) {
+        return yield* Effect.fail(new Error('Use either `--key` or `--user-api-key`, not both.'));
+      }
+
+      if (Option.isSome(org) && Option.isNone(userApiKey)) {
+        return yield* Effect.fail(new Error('`--org` requires `--user-api-key`.'));
+      }
+
+      if (Option.isSome(userApiKey) && (noBrowser || noWait || Option.isSome(key))) {
+        return yield* Effect.fail(
+          new Error(
+            '`--user-api-key` is a direct login path and cannot be combined with browser or session flags.'
+          )
+        );
+      }
+
       if (Option.isSome(key)) {
         yield* loginWithKey({
           key: key.value,
@@ -485,6 +583,17 @@ export const loginCmd = Command.make(
         return;
       }
 
+      if (Option.isSome(userApiKey)) {
+        yield* directLogin({
+          userApiKey: userApiKey.value,
+          org: Option.getOrUndefined(org),
+        });
+        if (!noSkillInstall) {
+          yield* installSkillSafe({ channel: inferSkillReleaseChannel(APP_VERSION) });
+        }
+        return;
+      }
+
       if (ctx.isLoggedIn()) {
         if (Option.isSome(ctx.data.orgId)) {
           yield* ui.log.warn(`You're already logged in!`);
diff --git a/ts/packages/cli/src/commands/root-help.ts b/ts/packages/cli/src/commands/root-help.ts
@@ -516,14 +516,22 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
 
   login: {
     usage:
-      'composio login [--no-browser] [--no-wait] [--key text] [-y, --yes] [--no-skill-install]',
+      'composio login [--no-browser] [--no-wait] [--key text] [--user-api-key text] [--org text] [-y, --yes] [--no-skill-install]',
     description:
       'Log in to the Composio CLI session. By default, also installs the composio-cli skill for Claude Code.',
     options: [
       {
         name: '--key <text>',
         description: 'Complete login using session key from composio login --no-wait',
       },
+      {
+        name: '--user-api-key <text>',
+        description: 'Log in directly with a Composio user API key',
+      },
+      {
+        name: '--org <text>',
+        description: 'Default organization ID or name to store for CLI commands',
+      },
     ],
     flags: [
       { name: '--no-browser', description: 'Login without browser interaction' },
diff --git a/ts/packages/cli/test/src/commands/login.cmd.test.ts b/ts/packages/cli/test/src/commands/login.cmd.test.ts
