@cargo-ai/cli 1.0.13 → 1.0.14

package/README.md

@@ -23,10 +23,14 @@ npx @cargo-ai/cli orchestration workflow list
 
 ## Authentication
 
-### Login (recommended)
+A single `cargo-ai login` command supports two modes — pass exactly one of `--token` or `--oauth`:
 
 ```bash
+# 1. Sign in with an existing workspace-scoped API token
 cargo-ai login --token <your-api-token>
+
+# 2. Sign in via your browser using the OAuth 2.0 Device Authorization Flow
+cargo-ai login --oauth
 ```
 
 Credentials are stored in `~/.config/cargo-ai/credentials.json` (file mode `0600`).
@@ -39,6 +43,23 @@ cargo-ai whoami
 cargo-ai logout
 ```
 
+### Browser sign-in (`--oauth`)
+
+`cargo-ai login --oauth` runs the standard [OAuth 2.0 Device Authorization Flow](https://datatracker.ietf.org/doc/html/rfc8628) (similar UX to `gh auth login`) 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`.
+
+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`.
+
+### 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:
+
+- **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.
+
 ### Environment variables (override)
 
 Environment variables take precedence over saved credentials, useful for CI or temporary overrides.
@@ -81,7 +102,7 @@ cargo-ai orchestration workflow --help
 | ------------------------ | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
 | **init**                 | Workspace initialisation (user, workspace, datasets, etc.) | `cargo-ai init`                                                                                                               |
 | **orchestration**        | Workflows, plays, runs, batches, tools, templates          | `cargo-ai orchestration workflow list`, `cargo-ai orchestration run list --workflow-uuid <uuid>`                              |
-| **workspace**            | Workspaces, users, tokens, roles, folders                  | `cargo-ai workspace workspaces list`, `cargo-ai workspace token list`                                                         |
+| **workspaceManagement**  | Workspaces, users, tokens, roles, folders                  | `cargo-ai workspaceManagement workspaces list`, `cargo-ai workspaceManagement token list`                                     |
 | **storage**              | Datasets, models, relationships, runs, records             | `cargo-ai storage dataset list`, `cargo-ai storage model list`                                                                |
 | **connection**           | Connectors and integrations                                | `cargo-ai connection connector list`, `cargo-ai connection integration list`                                                  |
 | **billing**              | Usage and subscription                                     | `cargo-ai billing subscription get`, `cargo-ai billing usage get-metrics --payload '{"from":"2025-01-01","to":"2025-01-31"}'` |

package/build/api.d.ts

@@ -1,4 +1,8 @@
 import { type Api } from "@cargo-ai/api";
 export type { Api };
-export declare function createApi(): Api;
+export declare function createApi(opts: {
+    baseUrl: string;
+    accessToken: string;
+    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;AAMpB,wBAAgB,SAAS,IAAI,GAAG,CAQ/B"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,GAAG,EAAY,MAAM,eAAe,CAAC;AAEnD,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,CAON"}

package/build/api.js

@@ -1,14 +1,13 @@
 import { createRequire } from "node:module";
 import { buildApi } from "@cargo-ai/api";
-import { getConfig } from "./config.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
-export function createApi() {
-    const { baseUrl, accessToken, workspaceUuid } = getConfig();
+const ORIGIN = { name: "cli", version };
+export function createApi(opts) {
     return buildApi({
-        baseUrl,
-        workspaceUuid,
-        getAccessToken: async () => accessToken,
-        origin: { name: "cli", version },
+        baseUrl: opts.baseUrl,
+        workspaceUuid: opts.workspaceUuid,
+        accessToken: opts.accessToken,
+        origin: ORIGIN,
     });
 }

package/build/commands/{auth.d.ts → auth/index.d.ts}

@@ -1,4 +1,4 @@
 import type { Command } from "commander";
-import type { Api } from "../api.js";
+import type { Api } from "../../api.js";
 export declare function registerAuthCommands(program: Command, getApi: () => Api): void;
-//# sourceMappingURL=auth.d.ts.map
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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"}

package/build/commands/auth/index.js

@@ -0,0 +1,131 @@
+import { getConfig } from "../../config.js";
+import { clearCredentials, getCredentialsPath, saveCredentials, } from "../../credentials.js";
+import { ExitCodes, failWith, handleApiCall, info, outputJson, success, } from "../runHandler.js";
+import { runOAuthDeviceFlow } from "./oauth.js";
+import { resolveWorkspace } from "./workspace.js";
+const DEFAULT_BASE_URL = "https://api.getcargo.io";
+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")
+        .option("--oauth", "Sign in via browser using the OAuth 2.0 Device Authorization Flow")
+        .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 --oauth
+  $ cargo-ai login --oauth --workspace-uuid 550e8400-e29b-41d4-a716-446655440000
+
+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.`)
+        .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(),
+        });
+    });
+    program
+        .command("whoami")
+        .description("Show current user and workspace")
+        .addHelpText("after", `
+Returns JSON with: user (uuid, email, name), workspace (uuid, name),
+authentication source ("environment" or "credentials-file"), and base URL.`)
+        .action(async () => {
+        await runWhoami(getApi);
+    });
+}
+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,
+        });
+    }
+    if (hasToken === false && wantsOAuth === false) {
+        failWith("Must pass --token <token> (API token) or --oauth (browser sign-in).", { code: ExitCodes.InvalidUsage });
+    }
+    const baseUrl = opts.baseUrl !== undefined && opts.baseUrl.length > 0
+        ? opts.baseUrl
+        : DEFAULT_BASE_URL;
+    if (hasToken === true) {
+        const token = opts.token;
+        saveCredentials({
+            accessToken: token,
+            baseUrl: opts.baseUrl,
+        });
+        success("Signed in with API token.");
+        outputJson({
+            ok: true,
+            credentialsFile: getCredentialsPath(),
+            baseUrl,
+            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,
+    });
+    success(`Signed in. Default workspace: ${workspace.name}.`);
+    outputJson({
+        ok: true,
+        credentialsFile: getCredentialsPath(),
+        baseUrl,
+        workspace,
+        tokenType: "oauth-jwt",
+        expiresIn: result.expiresIn,
+    });
+}
+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 api = getApi();
+    const { user } = await handleApiCall(() => api.userManagement.user.getCurrent());
+    const { workspace } = await handleApiCall(() => api.workspaceManagement.workspace.getCurrent());
+    outputJson({
+        user: {
+            uuid: user.uuid,
+            email: user.email,
+            firstName: user.firstName,
+            lastName: user.lastName,
+        },
+        workspace: { uuid: workspace.uuid, name: workspace.name },
+        source,
+        baseUrl,
+        credentialsFile: getCredentialsPath(),
+    });
+}

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

@@ -0,0 +1,7 @@
+import { type OAuthConfigOverrides } from "../../oauthConfig.js";
+export type OAuthLoginResult = {
+    accessToken: string;
+    expiresIn: number;
+};
+export declare function runOAuthDeviceFlow(overrides: OAuthConfigOverrides): Promise<OAuthLoginResult>;
+//# sourceMappingURL=oauth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../../src/commands/auth/oauth.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAC;AA8B9B,MAAM,MAAM,gBAAgB,GAAG;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,oBAAoB,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CA0B3B"}

package/build/commands/auth/oauth.js

@@ -0,0 +1,140 @@
+import { spawn } from "node:child_process";
+import { platform } from "node:process";
+import { getOAuthConfig, } from "../../oauthConfig.js";
+import { failWith, info } from "../runHandler.js";
+const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+const SLOW_DOWN_BACKOFF_SECONDS = 5;
+const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+export async function runOAuthDeviceFlow(overrides) {
+    const oauthConfig = getOAuthConfig(overrides);
+    const deviceCode = await requestDeviceCode(oauthConfig);
+    info([
+        "",
+        "To complete sign-in, open this URL in a browser:",
+        `  ${deviceCode.verification_uri_complete}`,
+        "",
+        `If your browser does not show the code prefilled, enter it manually: ${deviceCode.user_code}`,
+        "",
+        "Waiting for you to finish in the browser...",
+        "",
+    ].join("\n"));
+    openBrowser(deviceCode.verification_uri_complete);
+    const token = await pollForToken(oauthConfig, deviceCode);
+    return {
+        accessToken: token.access_token,
+        expiresIn: token.expires_in,
+    };
+}
+async function requestDeviceCode(config) {
+    const body = new URLSearchParams({
+        client_id: config.clientId,
+        scope: config.scope,
+        audience: config.audience,
+    });
+    body.set("screen_hint", "signup");
+    const response = await fetch(`https://${config.domain}/oauth/device/code`, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+    });
+    if (response.ok === false) {
+        const text = await safeReadText(response);
+        failWith(`Failed to start device authorization (HTTP ${String(response.status)}): ${text}`);
+    }
+    const json = (await response.json());
+    if (typeof json.device_code !== "string" ||
+        typeof json.user_code !== "string" ||
+        typeof json.verification_uri_complete !== "string" ||
+        typeof json.expires_in !== "number" ||
+        typeof json.interval !== "number") {
+        failWith(`Unexpected device authorization response from OAuth provider: ${JSON.stringify(json)}`);
+    }
+    return json;
+}
+async function pollForToken(config, deviceCode) {
+    const startedAtMs = Date.now();
+    const expiresAtMs = startedAtMs + deviceCode.expires_in * 1000;
+    let intervalSeconds = deviceCode.interval > 0
+        ? deviceCode.interval
+        : DEFAULT_POLL_INTERVAL_SECONDS;
+    while (Date.now() < expiresAtMs) {
+        await sleep(intervalSeconds * 1000);
+        const response = await fetch(`https://${config.domain}/oauth/token`, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: DEVICE_CODE_GRANT,
+                device_code: deviceCode.device_code,
+                client_id: config.clientId,
+            }).toString(),
+        });
+        if (response.ok === true) {
+            const token = (await response.json());
+            if (typeof token.access_token !== "string") {
+                failWith(`Unexpected token response from OAuth provider: ${JSON.stringify(token)}`);
+            }
+            return token;
+        }
+        const errorBody = (await safeReadJson(response));
+        const errorCode = errorBody !== undefined ? errorBody.error : undefined;
+        if (errorCode === "authorization_pending") {
+            continue;
+        }
+        if (errorCode === "slow_down") {
+            intervalSeconds = intervalSeconds + SLOW_DOWN_BACKOFF_SECONDS;
+            continue;
+        }
+        if (errorCode === "expired_token" ||
+            errorCode === "access_denied" ||
+            errorCode === "invalid_grant") {
+            failWith(`Authorization failed: ${errorCode}${errorBody !== undefined && errorBody.error_description !== undefined
+                ? ` - ${errorBody.error_description}`
+                : ""}`, { extra: { oauthError: errorBody } });
+        }
+        failWith(`Token polling failed (HTTP ${String(response.status)}): ${errorBody !== undefined ? JSON.stringify(errorBody) : "no body"}`, { extra: { oauthError: errorBody } });
+    }
+    failWith("Authorization timed out before the user completed the flow.");
+}
+function openBrowser(url) {
+    const command = pickOpenCommand();
+    const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        const child = spawn(command, args, {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.on("error", () => {
+            // Browser launch failed silently; user can still use the printed URL.
+        });
+        child.unref();
+    }
+    catch {
+        // Ignore; user can still use the printed URL.
+    }
+}
+function pickOpenCommand() {
+    if (platform === "darwin")
+        return "open";
+    if (platform === "win32")
+        return "cmd";
+    return "xdg-open";
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function safeReadText(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return "<unreadable body>";
+    }
+}
+async function safeReadJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -0,0 +1,10 @@
+export type ResolvedWorkspace = {
+    uuid: string;
+    name: string;
+};
+export declare function resolveWorkspace(opts: {
+    baseUrl: string;
+    accessToken: string;
+    explicitUuid: string | undefined;
+}): Promise<ResolvedWorkspace>;
+//# sourceMappingURL=workspace.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../../src/commands/auth/workspace.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAiG7B"}

package/build/commands/auth/workspace.js

@@ -0,0 +1,120 @@
+import * as readline from "node:readline/promises";
+import { createApi } from "../../api.js";
+import { ExitCodes, failWith, info, startSpinner, success, } from "../runHandler.js";
+export async function resolveWorkspace(opts) {
+    const api = createApi({
+        baseUrl: opts.baseUrl,
+        accessToken: opts.accessToken,
+        workspaceUuid: undefined,
+    });
+    let workspaces;
+    try {
+        const result = await api.workspaceManagement.workspace.all({
+            refresh: false,
+        });
+        workspaces = result.workspaces;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        failWith(`Failed to list workspaces: ${message}`);
+    }
+    if (opts.explicitUuid !== undefined) {
+        const matchedWorkspace = workspaces.find((workspace) => {
+            return workspace.uuid === opts.explicitUuid;
+        });
+        if (matchedWorkspace === undefined) {
+            failWith(`Workspace ${opts.explicitUuid} is not in your accessible workspaces.`, { code: ExitCodes.NotFound });
+        }
+        return { uuid: matchedWorkspace.uuid, name: matchedWorkspace.name };
+    }
+    if (workspaces.length === 0) {
+        if (process.stdin.isTTY !== true) {
+            failWith("No workspaces found.", { code: ExitCodes.NotFound });
+        }
+        const name = await promptWorkspaceName();
+        if (name === undefined) {
+            failWith("No workspace name provided.", {
+                code: ExitCodes.InvalidUsage,
+            });
+        }
+        const spinner = startSpinner("Creating workspace...");
+        let createdWorkspace;
+        try {
+            createdWorkspace = await api.workspaceManagement.workspace.create({
+                name,
+            });
+        }
+        catch (err) {
+            spinner.stop();
+            const message = err instanceof Error ? err.message : String(err);
+            failWith(`Failed to create workspace: ${message}`);
+        }
+        spinner.stop();
+        success(`Created workspace: ${createdWorkspace.workspace.name} (${createdWorkspace.workspace.uuid})`);
+        return {
+            uuid: createdWorkspace.workspace.uuid,
+            name: createdWorkspace.workspace.name,
+        };
+    }
+    if (workspaces.length === 1) {
+        const [firstWorkspace] = workspaces;
+        if (firstWorkspace === undefined) {
+            failWith("Unexpected empty workspace list after length check.");
+        }
+        return { uuid: firstWorkspace.uuid, name: firstWorkspace.name };
+    }
+    if (process.stdin.isTTY !== true) {
+        failWith("Multiple workspaces available; pass --workspace-uuid <uuid> to select one.", { code: ExitCodes.InvalidUsage });
+    }
+    const selectedWorkspace = await promptWorkspaceSelection(workspaces);
+    if (selectedWorkspace === undefined) {
+        failWith("No workspace selected.", { code: ExitCodes.InvalidUsage });
+    }
+    return selectedWorkspace;
+}
+async function promptWorkspaceName() {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    try {
+        info("You don't have any workspaces yet. Let's create one.");
+        const answer = await rl.question("Workspace name (or press Enter to skip): ");
+        const trimmed = answer.trim();
+        if (trimmed === "") {
+            return undefined;
+        }
+        return trimmed;
+    }
+    finally {
+        rl.close();
+    }
+}
+async function promptWorkspaceSelection(workspaces) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    try {
+        info("You have multiple workspaces. Pick one to set as the default for this CLI:");
+        workspaces.forEach((workspace, idx) => {
+            info(`  ${String(idx + 1)}) ${workspace.name}  (${workspace.uuid})`);
+        });
+        info("");
+        const maxAttempts = 3;
+        for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+            const answer = await rl.question(`Enter a number [1-${String(workspaces.length)}]: `);
+            const trimmed = answer.trim();
+            const index = Number.parseInt(trimmed, 10);
+            const selectedWorkspace = workspaces[index - 1];
+            if (selectedWorkspace !== undefined) {
+                return { uuid: selectedWorkspace.uuid, name: selectedWorkspace.name };
+            }
+            info(`Invalid selection: ${trimmed}`);
+        }
+        return undefined;
+    }
+    finally {
+        rl.close();
+    }
+}

package/build/commands/billing/subscription.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subscription.d.ts","sourceRoot":"","sources":["../../../src/commands/billing/subscription.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAkKN"}
+{"version":3,"file":"subscription.d.ts","sourceRoot":"","sources":["../../../src/commands/billing/subscription.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAsPN"}

package/build/commands/billing/subscription.js

@@ -5,7 +5,11 @@ export function registerSubscriptionCommands(parent, getApi) {
         .description("Subscription operations");
     subscription
         .command("get")
-        .description("Get current subscription")
+        .description("Get the current subscription for this workspace")
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai billing subscription get
+  $ cargo-ai billing subscription get | jq '.subscription.plan'`)
         .action(async () => {
         const api = getApi();
         const result = await handleApiCall(() => api.billing.subscription.get());
@@ -13,7 +17,11 @@ export function registerSubscriptionCommands(parent, getApi) {
     });
     subscription
         .command("get-invoices")
-        .description("Get invoices")
+        .description("List invoices for the current workspace")
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai billing subscription get-invoices
+  $ cargo-ai billing subscription get-invoices | jq '.invoices | length'`)
         .action(async () => {
         const api = getApi();
         const result = await handleApiCall(() => api.billing.subscription.getInvoices());
@@ -21,7 +29,10 @@ export function registerSubscriptionCommands(parent, getApi) {
     });
     subscription
         .command("get-credit-card")
-        .description("Get credit card")
+        .description("Get the credit card on file for the current workspace")
+        .addHelpText("after", `
+Example:
+  $ cargo-ai billing subscription get-credit-card`)
         .action(async () => {
         const api = getApi();
         const result = await handleApiCall(() => api.billing.subscription.getCreditCard());
@@ -29,7 +40,10 @@ export function registerSubscriptionCommands(parent, getApi) {
     });
     subscription
         .command("create-setup-intent")
-        .description("Create a setup intent")
+        .description("Create a Stripe setup intent for adding/updating a payment method")
+        .addHelpText("after", `
+Example:
+  $ cargo-ai billing subscription create-setup-intent | jq -r .clientSecret`)
         .action(async () => {
         const api = getApi();
         const result = await handleApiCall(() => api.billing.subscription.createSetupIntent());
@@ -37,8 +51,11 @@ export function registerSubscriptionCommands(parent, getApi) {
     });
     subscription
         .command("update-payment-method")
-        .description("Update payment method")
-        .requiredOption("--payment-method-id <id>", "Stripe payment method ID")
+        .description("Replace the workspace's payment method")
+        .requiredOption("--payment-method-id <id>", "Stripe payment method ID (e.g. pm_1OabcXYZ...)")
+        .addHelpText("after", `
+Example:
+  $ cargo-ai billing subscription update-payment-method --payment-method-id pm_1OabcXYZ`)
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.billing.subscription.updatePaymentMethod({
@@ -48,7 +65,10 @@ export function registerSubscriptionCommands(parent, getApi) {
     });
     subscription
         .command("create-portal-session")
-        .description("Create a portal session")
+        .description("Create a Stripe customer portal session URL")
+        .addHelpText("after", `
+Example:
+  $ cargo-ai billing subscription create-portal-session | jq -r .url`)
         .action(async () => {
         const api = getApi();
         const result = await handleApiCall(() => api.billing.subscription.createPortalSession());
@@ -56,7 +76,10 @@ export function registerSubscriptionCommands(parent, getApi) {
     });
     subscription
         .command("create-stripe-credits-checkout-session")
-        .description("Create a Stripe credits checkout session")
+        .description("Create a Stripe checkout session for purchasing credits")
+        .addHelpText("after", `
+Example:
+  $ cargo-ai billing subscription create-stripe-credits-checkout-session | jq -r .url`)
         .action(async () => {
         const api = getApi();
         const result = await handleApiCall(() => api.billing.subscription.createStripeCreditsCheckoutSession());
@@ -64,9 +87,13 @@ export function registerSubscriptionCommands(parent, getApi) {
     });
     subscription
         .command("update-plan")
-        .description("Update subscription plan")
-        .requiredOption("--credits-count <n>", "Number of credits")
-        .requiredOption("--cadence <cadence>", "Subscription cadence")
+        .description("Change the credit allotment and billing cadence")
+        .requiredOption("--credits-count <n>", "Number of credits per period")
+        .requiredOption("--cadence <cadence>", "Billing cadence. Allowed values: monthly, yearly")
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai billing subscription update-plan --credits-count 10000 --cadence monthly
+  $ cargo-ai billing subscription update-plan --credits-count 50000 --cadence yearly`)
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.billing.subscription.updatePlan({
@@ -77,10 +104,14 @@ export function registerSubscriptionCommands(parent, getApi) {
     });
     subscription
         .command("update-topup")
-        .description("Update topup settings")
-        .option("--enabled", "Enable topup")
-        .requiredOption("--credits-count <n>", "Number of credits")
-        .requiredOption("--threshold <n>", "Threshold")
+        .description("Configure automatic credit top-ups")
+        .option("--enabled", "Enable automatic top-ups (omit to disable)")
+        .requiredOption("--credits-count <n>", "Number of credits to add per top-up")
+        .requiredOption("--threshold <n>", "Trigger top-up when remaining credits drop below this number")
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai billing subscription update-topup --enabled --credits-count 5000 --threshold 1000
+  $ cargo-ai billing subscription update-topup --credits-count 5000 --threshold 1000   # disabled`)
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.billing.subscription.updateTopup({
@@ -92,11 +123,18 @@ export function registerSubscriptionCommands(parent, getApi) {
     });
     subscription
         .command("update-credits-overage-behaviors")
-        .description("Update credits overage behaviors")
-        .requiredOption("--behavior <unit:action>", "Behavior as unit:action (e.g. billing.credits:deny), repeatable", (val, acc) => {
+        .description("Set how the workspace behaves when a credit unit runs out (allow vs deny)")
+        .requiredOption("--behavior <unit:action>", "Behavior as unit:action (e.g. billing.credits:deny). Repeat to set multiple units.", (val, acc) => {
         acc.push(val);
         return acc;
     }, [])
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai billing subscription update-credits-overage-behaviors \\
+      --behavior billing.credits:deny
+  $ cargo-ai billing subscription update-credits-overage-behaviors \\
+      --behavior billing.credits:allow \\
+      --behavior data.records:deny`)
         .action(async (opts) => {
         const creditsOverageBehaviors = opts.behavior.map((b) => {
             const parts = b.split(":");