@cargo-ai/cli 1.0.45 → 1.0.46

package/README.md

@@ -23,17 +23,26 @@ npx @cargo-ai/cli orchestration workflow list
 
 ## Authentication
 
-A single `cargo-ai login` command supports two modes — pass exactly one of `--token` or `--oauth`:
+A single `cargo-ai login` command supports three channels — pass exactly one of `--email`, `--oauth` or `--token`:
 
 ```bash
-# 1. Sign in with an existing workspace-scoped API token
-cargo-ai login --token <your-api-token>
+# 1. Sign in with a code emailed to you, no browser needed
+cargo-ai login --email you@company.com
 
 # 2. Sign in via your browser using the OAuth 2.0 Device Authorization Flow
 cargo-ai login --oauth
+
+# 3. Sign in with an API token you already have
+cargo-ai login --token <your-api-token>
 ```
 
-Credentials are stored in `~/.config/cargo-ai/credentials.json` (file mode `0600`).
+`--email` and `--oauth` both create the account if it does not exist yet, so there is no separate sign-up command.
+
+`--email` and `--oauth` save the signed-in session — a short-lived access token plus the refresh token that renews it — to `~/.config/cargo-ai/credentials.json` (file mode `0600`). The CLI renews it in the background as it expires, so you stay signed in and no API token is created per machine. `--token` saves the API token you supplied instead. The same file backs `cargo-cdk`, so one login serves both.
+
+`cargo-ai logout` revokes the session at the identity provider, so signing out is final. A token you supplied yourself with `--token` is only forgotten locally, since it may be in use elsewhere; pass `--keep-token` to force that behaviour for a session too.
+
+Treat the file as you would a password. A saved session acts as you across **every** workspace you belong to — unlike an API token, which is limited to one workspace and to the permissions it was created with — and it stays valid until you run `cargo-ai logout` or the identity provider expires it. On a shared or long-lived machine (CI, a build box), prefer an API token created under **Settings → API** and passed via `CARGO_API_TOKEN`, which you can scope down and revoke from the dashboard.
 
 ```bash
 # Check current auth status
@@ -43,22 +52,53 @@ cargo-ai whoami
 cargo-ai logout
 ```
 
+### Sign-in without a browser (`--email`)
+
+`cargo-ai login --email you@company.com` emails you a one-time code, then creates your account (on first use) and a workspace — no browser and no dashboard visit at any point. On a terminal the code is read back from a prompt. Where there is no terminal (sandboxes, agent shells) the first call sends the code and exits, so you can finish with:
+
+```bash
+cargo-ai login --email you@company.com --code 123456 --workspace-name "Acme GTM"
+```
+
+Re-running with an address that already has an account resolves to its existing workspace rather than creating one, and `--workspace-name` reuses a workspace of that name when one already exists, so this is safe to repeat.
+
+To keep the code out of your shell history, pass it on stdin with `--code -`:
+
+```bash
+echo 123456 | cargo-ai login --email you@company.com --code -
+```
+
 ### Browser sign-in (`--oauth`)
 
-`cargo-ai login --oauth` runs the standard [OAuth 2.0 Device Authorization Flow](https://datatracker.ietf.org/doc/html/rfc8628) against the Cargo OAuth provider, prints a verification URL and user code, opens your default browser, and polls until you complete sign-in. On success the access token is written to `~/.config/cargo-ai/credentials.json`.
+`cargo-ai login --oauth` runs the standard [OAuth 2.0 Device Authorization Flow](https://datatracker.ietf.org/doc/html/rfc8628) against the Cargo OAuth provider, prints a verification URL and user code, opens your default browser, and polls until you complete sign-in. On success the CLI writes the resulting session to `~/.config/cargo-ai/credentials.json`.
 
-The CLI ships with a built-in OAuth client, so no setup is required. Advanced users can override the provider via `--client-id`, `--domain`, and `--audience`.
+The CLI ships with a built-in OAuth client, so no setup is required.
 
 ### Workspace selection
 
-API tokens (`--token`) are workspace-scoped, so the workspace is implicit and nothing is persisted alongside the token.
-
-OAuth sessions (`--oauth`) are user-scoped, so after authentication the CLI picks a default workspace and saves it next to the token:
+`--email` and `--oauth` authenticate you as a user, so the CLI picks a workspace to save alongside the session:
 
+- **No workspaces**: one is created (you are prompted for a name in a TTY, or pass `--workspace-name <name>`).
 - **One workspace**: it is selected automatically.
 - **Multiple workspaces**: you are prompted to pick one (in a TTY); in non-interactive shells the CLI prints the list and asks you to re-run with `--workspace-uuid <uuid>`.
 
-Pass `cargo-ai login --oauth --workspace-uuid <uuid>` to skip the prompt. `CARGO_WORKSPACE_UUID` (or per-command `--workspace-uuid` flags where supported) overrides the saved default at runtime.
+Pass `--workspace-uuid <uuid>` or `--workspace-name <name>` to skip the prompt.
+
+### Switching workspaces
+
+A signed-in session is not tied to one workspace, so `CARGO_WORKSPACE_UUID` switches workspace for a single command or a whole shell:
+
+```bash
+CARGO_WORKSPACE_UUID=<other-workspace-uuid> cargo-ai storage model list
+```
+
+To change the default your session uses, sign in again for that workspace:
+
+```bash
+cargo-ai login --email you@company.com --workspace-uuid <other-workspace-uuid>
+```
+
+An API token is different: it is scoped to a single workspace and the server takes the workspace from the token, not from anything sent alongside it. So if you signed in with `--token` and `CARGO_WORKSPACE_UUID` names a different workspace, the CLI refuses the command rather than silently running against the token's workspace. The override still applies when you supply the token yourself via `CARGO_API_TOKEN`, since only you know which workspace that token is for.
 
 ### Environment variables (override)
 

package/build/api.d.ts

@@ -1,8 +1,9 @@
 import { type Api } from "@cargo-ai/api";
+import type { AccessTokenProvider } from "@cargo-ai/cdk/cli";
 export type { Api };
 export declare function createApi(opts: {
     baseUrl: string;
-    accessToken: string;
+    getAccessToken: AccessTokenProvider;
     workspaceUuid: string | undefined;
 }): Api;
 //# sourceMappingURL=api.d.ts.map

package/build/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,GAAG,EAAY,MAAM,eAAe,CAAC;AAInD,YAAY,EAAE,GAAG,EAAE,CAAC;AAQpB,wBAAgB,SAAS,CAAC,IAAI,EAAE;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC,GAAG,GAAG,CAWN"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,GAAG,EAAY,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAI7D,YAAY,EAAE,GAAG,EAAE,CAAC;AAQpB,wBAAgB,SAAS,CAAC,IAAI,EAAE;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,mBAAmB,CAAC;IACpC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC,GAAG,GAAG,CAeN"}

package/build/api.js

@@ -8,8 +8,12 @@ export function createApi(opts) {
     return buildApi({
         baseUrl: opts.baseUrl,
         workspaceUuid: opts.workspaceUuid,
-        accessToken: opts.accessToken,
+        getAccessToken: opts.getAccessToken,
         origin: ORIGIN,
+        // A saved session outlives the workspace list baked into its token, so a
+        // workspace granted since signing in reads as a 401 until the token is
+        // reissued. Renew and retry rather than telling the user to sign in again.
+        retryOnUnauthorized: true,
         // The client is `fetch`-based; supply a proxy-tunneling `fetch` (undici
         // `ProxyAgent`) when proxy env vars are set, since Node's global `fetch`
         // does not honor them. `undefined` when no proxy applies.

package/build/commands/auth/auth0.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What both sign-in channels hand to `establishSession`. The refresh token is
+ * optional: the identity provider only issues one when the application has the
+ * refresh grant enabled.
+ */
+export type IdentityTokens = {
+    accessToken: string;
+    refreshToken: string | undefined;
+    /** Epoch milliseconds at which `accessToken` stops being accepted. */
+    expiresAt: number;
+};
+export type Auth0ErrorBody = {
+    error?: string;
+    error_description?: string;
+};
+/**
+ * Throws rather than calling `failWith` so the device-flow poll can treat a
+ * blip as a retryable iteration instead of losing an in-progress sign-in.
+ */
+export declare function postToAuth0(opts: {
+    path: string;
+    body: URLSearchParams | Record<string, unknown>;
+    timeoutMs?: number;
+}): Promise<Response>;
+export declare function parseTokenResponse(json: unknown): IdentityTokens;
+/**
+ * Falls back to the raw text: a gateway or WAF in front of the provider answers
+ * with HTML, and "no response body" would throw away the only clue about why.
+ */
+export declare function readErrorBody(response: Response): Promise<Auth0ErrorBody | string | undefined>;
+export declare function describeError(body: Auth0ErrorBody | string | undefined): string;
+export declare function errorCodeOf(body: Auth0ErrorBody | string | undefined): string | undefined;
+//# sourceMappingURL=auth0.d.ts.map

package/build/commands/auth/auth0.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth0.d.ts","sourceRoot":"","sources":["../../../src/commands/auth/auth0.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAWF;;;GAGG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,QAAQ,CAAC,CA0BpB;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAoBhE;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,cAAc,GAAG,MAAM,GAAG,SAAS,CAAC,CAkB9C;AAED,wBAAgB,aAAa,CAC3B,IAAI,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,GACxC,MAAM,CAkBR;AAED,wBAAgB,WAAW,CACzB,IAAI,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,GACxC,MAAM,GAAG,SAAS,CAMpB"}

package/build/commands/auth/auth0.js

@@ -0,0 +1,90 @@
+import { getOAuthConfig } from "../../oauthConfig.js";
+import { failWith } from "../runHandler.js";
+const REQUEST_TIMEOUT_MS = 15_000;
+// Only used when the provider omits `expires_in`, which Auth0 does not do.
+const FALLBACK_LIFETIME_SECONDS = 3600;
+/**
+ * Throws rather than calling `failWith` so the device-flow poll can treat a
+ * blip as a retryable iteration instead of losing an in-progress sign-in.
+ */
+export async function postToAuth0(opts) {
+    const config = getOAuthConfig();
+    const timeoutMs = opts.timeoutMs !== undefined ? opts.timeoutMs : REQUEST_TIMEOUT_MS;
+    const isForm = opts.body instanceof URLSearchParams;
+    try {
+        return await fetch(`https://${config.domain}${opts.path}`, {
+            method: "POST",
+            headers: {
+                "content-type": isForm
+                    ? "application/x-www-form-urlencoded"
+                    : "application/json",
+            },
+            body: isForm ? opts.body.toString() : JSON.stringify(opts.body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (err) {
+        const seconds = String(Math.round(timeoutMs / 1000));
+        const reason = err instanceof Error && err.name === "TimeoutError"
+            ? `did not respond within ${seconds}s`
+            : `could not be reached (${err instanceof Error ? err.message : String(err)})`;
+        throw new Error(`The identity provider (${config.domain}) ${reason}.`);
+    }
+}
+export function parseTokenResponse(json) {
+    const token = json;
+    if (typeof token.access_token !== "string") {
+        failWith(`Unexpected token response from the identity provider: ${JSON.stringify(json)}`);
+    }
+    const lifetime = typeof token.expires_in === "number"
+        ? token.expires_in
+        : FALLBACK_LIFETIME_SECONDS;
+    return {
+        accessToken: token.access_token,
+        refreshToken: typeof token.refresh_token === "string" ? token.refresh_token : undefined,
+        expiresAt: Date.now() + lifetime * 1000,
+    };
+}
+/**
+ * Falls back to the raw text: a gateway or WAF in front of the provider answers
+ * with HTML, and "no response body" would throw away the only clue about why.
+ */
+export async function readErrorBody(response) {
+    let text;
+    try {
+        text = await response.text();
+    }
+    catch {
+        return undefined;
+    }
+    if (text.length === 0) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+export function describeError(body) {
+    if (body === undefined) {
+        return "no response body";
+    }
+    if (typeof body === "string") {
+        return body;
+    }
+    if (body.error_description !== undefined) {
+        return body.error_description;
+    }
+    if (body.error !== undefined) {
+        return body.error;
+    }
+    return JSON.stringify(body);
+}
+export function errorCodeOf(body) {
+    if (body === undefined || typeof body === "string") {
+        return undefined;
+    }
+    return body.error;
+}

package/build/commands/auth/email.d.ts

@@ -0,0 +1,16 @@
+/** `--code -` reads the code from stdin, keeping it out of shell history. */
+export declare const STDIN_CODE = "-";
+export type EmailLoginOptions = {
+    email?: string;
+    code?: string;
+    workspaceName?: string;
+    workspaceUuid?: string;
+    baseUrl?: string;
+};
+/**
+ * Signs in with a code emailed by the identity provider, creating the account
+ * on first use. This is the only channel that needs neither a browser nor an
+ * existing credential.
+ */
+export declare function runEmailLogin(opts: EmailLoginOptions): Promise<void>;
+//# sourceMappingURL=email.d.ts.map

package/build/commands/auth/email.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.d.ts","sourceRoot":"","sources":["../../../src/commands/auth/email.ts"],"names":[],"mappings":"AAaA,6EAA6E;AAC7E,eAAO,MAAM,UAAU,MAAM,CAAC;AAE9B,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6C1E"}

package/build/commands/auth/email.js

@@ -0,0 +1,93 @@
+import { getCredentialsPath } from "../../credentials.js";
+import { askQuestion, openPromptInput } from "../../utils/prompt.js";
+import { ExitCodes, failWith, info, outputJson, startSpinner, success, } from "../runHandler.js";
+import { exchangeEmailOtp, startEmailPasswordless } from "./passwordless.js";
+import { establishSession, resolveBaseUrl } from "./session.js";
+/** `--code -` reads the code from stdin, keeping it out of shell history. */
+export const STDIN_CODE = "-";
+/**
+ * Signs in with a code emailed by the identity provider, creating the account
+ * on first use. This is the only channel that needs neither a browser nor an
+ * existing credential.
+ */
+export async function runEmailLogin(opts) {
+    const email = opts.email;
+    if (email === undefined || email.length === 0) {
+        failWith("Must pass --email <email>.", { code: ExitCodes.InvalidUsage });
+    }
+    const resumeCommand = `cargo-ai login --email ${email} --code <code>`;
+    const code = await resolveCode({ email, code: opts.code, resumeCommand });
+    if (code === undefined) {
+        // The code was sent but there is no terminal to type it into. Exit
+        // successfully so an agent can relay the code and re-run non-interactively.
+        outputJson({
+            ok: true,
+            status: "codeSent",
+            email,
+            next: resumeCommand,
+        });
+        return;
+    }
+    const spinner = startSpinner("Verifying code...");
+    const tokens = await exchangeEmailOtp({ email, otp: code });
+    spinner.stop();
+    const workspace = await establishSession({
+        tokens,
+        baseUrlOverride: opts.baseUrl,
+        workspaceUuid: opts.workspaceUuid,
+        workspaceName: opts.workspaceName,
+    });
+    success(`Signed in as ${email}. Workspace: ${workspace.name}.`);
+    outputJson({
+        ok: true,
+        status: "signedIn",
+        credentialsFile: getCredentialsPath(),
+        baseUrl: resolveBaseUrl(opts.baseUrl),
+        email,
+        workspace,
+        tokenType: "session",
+    });
+}
+/**
+ * Returns the one-time code, sending a fresh one first unless the caller
+ * already has it. Resolves to `undefined` when a code was sent but no terminal
+ * is available to read it back.
+ */
+async function resolveCode(opts) {
+    if (opts.code === STDIN_CODE) {
+        return await readCodeFromStdin();
+    }
+    if (opts.code !== undefined && opts.code.length > 0) {
+        return opts.code;
+    }
+    const spinner = startSpinner(`Sending a verification code to ${opts.email}...`);
+    await startEmailPasswordless({ email: opts.email });
+    spinner.stop();
+    success(`Verification code sent to ${opts.email}.`);
+    const promptInput = openPromptInput();
+    if (promptInput === undefined) {
+        info(`No interactive terminal available. Re-run with the code: ${opts.resumeCommand}`);
+        return undefined;
+    }
+    try {
+        const answer = await askQuestion(promptInput.stream, "Enter the code from your inbox: ");
+        if (answer === undefined) {
+            failWith("No code entered.", { code: ExitCodes.InvalidUsage });
+        }
+        return answer;
+    }
+    finally {
+        promptInput.close();
+    }
+}
+async function readCodeFromStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.from(chunk));
+    }
+    const code = Buffer.concat(chunks).toString("utf-8").trim();
+    if (code.length === 0) {
+        failWith("No code received on stdin.", { code: ExitCodes.InvalidUsage });
+    }
+    return code;
+}

package/build/commands/auth/index.d.ts

@@ -1,4 +1,22 @@
-import type { Command } from "commander";
+import { type Command } from "commander";
 import type { Api } from "../../api.js";
+import type { Credentials } from "../../credentials.js";
+export type LogoutOptions = {
+    keepToken?: boolean;
+    keepSession?: boolean;
+};
 export declare function registerAuthCommands(program: Command, getApi: () => Api): void;
+export type RevocationPlan = {
+    kind: "session";
+} | {
+    kind: "none";
+};
+/**
+ * Decides what signing out should invalidate remotely. A token the user
+ * supplied with --token is left alone: it carries no session, and may well be
+ * in use elsewhere.
+ *
+ * Exported for tests; `runLogout` is the only production caller.
+ */
+export declare function planRevocation(credentials: Credentials | undefined, opts: LogoutOptions): RevocationPlan;
 //# sourceMappingURL=index.d.ts.map

package/build/commands/auth/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AA8BxC,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAiFN"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/auth/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,OAAO,EAAU,MAAM,WAAW,CAAC;AAEjD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAExC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAwBxD,MAAM,MAAM,aAAa,GAAG;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAkGN;AAiFD,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,WAAW,GAAG,SAAS,EACpC,IAAI,EAAE,aAAa,GAClB,cAAc,CAchB"}

package/build/commands/auth/index.js

@@ -1,48 +1,66 @@
+import { revokeSession } from "@cargo-ai/cdk/cli";
+import { Option } from "commander";
 import { getConfig } from "../../config.js";
-import { clearCredentials, getCredentialsPath, saveCredentials, } from "../../credentials.js";
+import { clearCredentials, getCredentialsPath, loadCredentials, saveCredentials, } from "../../credentials.js";
 import { ExitCodes, failWith, handleApiCall, info, outputJson, success, } from "../runHandler.js";
+import { runEmailLogin } from "./email.js";
+import { selectLoginChannel } from "./loginChannel.js";
 import { runOAuthDeviceFlow } from "./oauth.js";
-import { resolveWorkspace } from "./workspace.js";
-const DEFAULT_BASE_URL = "https://api.getcargo.io";
+import { DEFAULT_BASE_URL, establishSession, resolveBaseUrl, } from "./session.js";
 export function registerAuthCommands(program, getApi) {
     program
         .command("login")
-        .description("Sign in to Cargo with an API token (--token) or via browser (--oauth)")
-        .option("--token <token>", "Cargo API token; mutually exclusive with --oauth")
+        .description("Sign in to Cargo with an emailed code (--email), via browser (--oauth), or with an existing API token (--token)")
+        .option("--email <email>", "Sign in with a code emailed to this address; creates the account on first use")
+        .option("--code <code>", 'Verification code from the email, or "-" to read it from stdin; omit to have one sent (--email only)')
         .option("--oauth", "Sign in via browser using the OAuth 2.0 Device Authorization Flow")
+        .option("--token <token>", "Existing Cargo API token")
+        .option("--workspace-name <name>", "Workspace to use, created if no workspace of that name exists (skips the workspace prompt)")
+        .option("--workspace-uuid <uuid>", "Workspace UUID to sign in for (skips the workspace prompt)")
         .option("--base-url <url>", `Cargo API base URL (string, default: ${DEFAULT_BASE_URL})`)
-        .option("--workspace-uuid <uuid>", "Default workspace UUID to save (--oauth only; skips the workspace prompt)")
-        .option("--client-id <id>", "OAuth native application client ID (--oauth only; defaults to the built-in Cargo CLI client)")
-        .option("--domain <domain>", "OAuth provider domain (--oauth only; default: auth.getcargo.io)")
-        .option("--audience <audience>", "OAuth API audience (--oauth only; default: https://api.getcargo.io)")
         .addHelpText("after", `
 Examples:
-  $ cargo-ai login --token sk_live_abc123
-  $ cargo-ai login --token sk_live_abc123 --base-url https://api.custom.io
+  $ cargo-ai login --email you@company.com
+  $ cargo-ai login --email you@company.com --code 123456 --workspace-name "Acme GTM"
   $ cargo-ai login --oauth
   $ cargo-ai login --oauth --workspace-uuid 550e8400-e29b-41d4-a716-446655440000
+  $ cargo-ai login --token sk_live_abc123 --base-url https://api.custom.io
+
+--email and --oauth both create the account if it does not exist yet, so there
+is no separate sign-up step. --email needs no browser at any point: a code is
+emailed and read back from the prompt. Where there is no terminal (sandboxes,
+agent shells) the first call sends the code and exits, so re-run with --code to
+finish. To keep the code out of shell history, pass it on stdin instead:
+echo 123456 | cargo-ai login --email you@company.com --code -
+
+Signing in with an address that already has an account resolves to its existing
+workspace rather than creating one, and --workspace-name reuses a workspace of
+that name when one exists, so this is safe to re-run.
+
+--email and --oauth save the signed-in session to
+~/.config/cargo-ai/credentials.json and renew it automatically, so you stay
+signed in without a token being created for each machine. Switch workspace at
+any time with CARGO_WORKSPACE_UUID or by signing in again with
+--workspace-uuid <uuid>. An API token passed with --token stays pinned to its
+own workspace, so the override does not apply to it.
 
-Credentials are stored in ~/.config/cargo-ai/credentials.json.
 Environment variables (CARGO_API_TOKEN, CARGO_WORKSPACE_UUID, CARGO_BASE_URL) take precedence over saved credentials, and the nearest project .env (walking up from the current directory) fills them in when they are not already exported.`)
         .action(async (opts) => {
         await runLogin(opts);
     });
     program
         .command("logout")
-        .description("Remove saved API credentials")
-        .action(() => {
-        const removed = clearCredentials();
-        if (removed === true) {
-            success("Signed out.");
-        }
-        else {
-            info("No saved credentials to remove.");
-        }
-        outputJson({
-            ok: true,
-            removed,
-            credentialsFile: getCredentialsPath(),
-        });
+        .description("Sign out: revoke the saved credential and remove it locally")
+        .option("--keep-token", "Only forget the credentials locally, leaving the session or token valid")
+        // The credential is usually a session now, so accept the name people reach
+        // for; --keep-token stays the documented spelling for existing scripts.
+        .addOption(new Option("--keep-session").hideHelp())
+        .addHelpText("after", `
+A session from "cargo-ai login --email" or "--oauth" is revoked at the identity
+provider, so signing out is final. Tokens you supplied yourself with --token are
+only forgotten locally, since they may be in use elsewhere.`)
+        .action(async (opts) => {
+        await runLogout(opts);
     });
     program
         .command("whoami")
@@ -55,63 +73,107 @@ authentication source ("environment" or "credentials-file"), and base URL.`)
     });
 }
 async function runLogin(opts) {
-    const hasToken = opts.token !== undefined;
-    const wantsOAuth = opts.oauth === true;
-    if (hasToken === true && wantsOAuth === true) {
-        failWith("Cannot combine --token and --oauth; pass only one.", {
-            code: ExitCodes.InvalidUsage,
-        });
+    const selection = selectLoginChannel(opts);
+    if ("error" in selection) {
+        failWith(selection.error, { code: ExitCodes.InvalidUsage });
     }
-    if (hasToken === false && wantsOAuth === false) {
-        failWith("Must pass --token <token> (API token) or --oauth (browser sign-in).", { code: ExitCodes.InvalidUsage });
+    if (selection.channel === "email") {
+        await runEmailLogin(opts);
+        return;
     }
-    const baseUrl = opts.baseUrl !== undefined && opts.baseUrl.length > 0
-        ? opts.baseUrl
-        : DEFAULT_BASE_URL;
-    if (hasToken === true) {
-        const token = opts.token;
+    const baseUrl = resolveBaseUrl(opts.baseUrl);
+    if (selection.channel === "token") {
         saveCredentials({
-            accessToken: token,
+            accessToken: selection.token,
+            workspaceUuid: opts.workspaceUuid,
             baseUrl: opts.baseUrl,
         });
         success("Signed in with API token.");
         outputJson({
             ok: true,
+            status: "signedIn",
             credentialsFile: getCredentialsPath(),
             baseUrl,
+            workspaceUuid: opts.workspaceUuid,
             tokenType: "api-token",
         });
         return;
     }
-    const result = await runOAuthDeviceFlow({
-        clientId: opts.clientId,
-        domain: opts.domain,
-        audience: opts.audience,
-    });
-    const workspace = await resolveWorkspace({
-        baseUrl,
-        accessToken: result.accessToken,
-        explicitUuid: opts.workspaceUuid,
-    });
-    saveCredentials({
-        accessToken: result.accessToken,
-        workspaceUuid: workspace.uuid,
-        baseUrl: opts.baseUrl,
+    const tokens = await runOAuthDeviceFlow();
+    const workspace = await establishSession({
+        tokens,
+        baseUrlOverride: opts.baseUrl,
+        workspaceUuid: opts.workspaceUuid,
+        workspaceName: opts.workspaceName,
     });
     success(`Signed in. Default workspace: ${workspace.name}.`);
     outputJson({
         ok: true,
+        status: "signedIn",
         credentialsFile: getCredentialsPath(),
         baseUrl,
         workspace,
-        tokenType: "oauth-jwt",
-        expiresIn: result.expiresIn,
+        tokenType: "session",
     });
 }
+async function runLogout(opts) {
+    const credentials = loadCredentials();
+    const plan = planRevocation(credentials, opts);
+    const revoked = await applyRevocation(plan, credentials);
+    const removed = clearCredentials();
+    if (removed === true) {
+        success(revoked === true ? "Signed out and revoked access." : "Signed out.");
+    }
+    else {
+        info("No saved credentials to remove.");
+    }
+    outputJson({
+        ok: true,
+        removed,
+        revoked,
+        credentialsFile: getCredentialsPath(),
+    });
+}
+/**
+ * Decides what signing out should invalidate remotely. A token the user
+ * supplied with --token is left alone: it carries no session, and may well be
+ * in use elsewhere.
+ *
+ * Exported for tests; `runLogout` is the only production caller.
+ */
+export function planRevocation(credentials, opts) {
+    if (opts.keepToken === true || opts.keepSession === true) {
+        return { kind: "none" };
+    }
+    if (credentials === undefined) {
+        return { kind: "none" };
+    }
+    if (credentials.session !== undefined) {
+        return { kind: "session" };
+    }
+    return { kind: "none" };
+}
+async function applyRevocation(plan, credentials) {
+    if (plan.kind === "none" || credentials === undefined) {
+        return false;
+    }
+    const session = credentials.session;
+    if (session === undefined) {
+        return false;
+    }
+    try {
+        await revokeSession(session);
+        return true;
+    }
+    catch {
+        info("Could not revoke the session remotely; the local credentials were still removed.");
+        return false;
+    }
+}
 async function runWhoami(getApi) {
-    const { accessToken, baseUrl, source } = getConfig();
-    if (accessToken === undefined) {
-        failWith('Not authenticated. Run "cargo-ai login --token <token>" or "cargo-ai login --oauth".', { code: ExitCodes.NotAuthenticated });
+    const { getAccessToken, baseUrl, source } = getConfig();
+    if (getAccessToken === undefined) {
+        failWith('Not authenticated. Run "cargo-ai login --email you@company.com" (no browser needed) or "cargo-ai login --oauth".', { code: ExitCodes.NotAuthenticated });
     }
     const api = getApi();
     const { user } = await handleApiCall(() => api.userManagement.user.getCurrent());

package/build/commands/auth/loginChannel.d.ts

@@ -0,0 +1,21 @@
+import type { EmailLoginOptions } from "./email.js";
+export type LoginOptions = EmailLoginOptions & {
+    token?: string;
+    oauth?: boolean;
+};
+export type LoginChannelSelection = {
+    channel: "email";
+} | {
+    channel: "oauth";
+} | {
+    channel: "token";
+    token: string;
+} | {
+    error: string;
+};
+/**
+ * Picks the sign-in channel and rejects flag combinations whose extra options
+ * would otherwise be accepted and quietly ignored.
+ */
+export declare function selectLoginChannel(opts: LoginOptions): LoginChannelSelection;
+//# sourceMappingURL=loginChannel.d.ts.map