@cargo-ai/cli 1.0.72 → 1.0.73

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

@@ -1,3 +1,4 @@
+import type { ResolvedWorkspace } from "./workspace.js";
 /** `--code -` reads the code from stdin, keeping it out of shell history. */
 export declare const STDIN_CODE = "-";
 export type EmailLoginOptions = {
@@ -6,11 +7,34 @@ export type EmailLoginOptions = {
     workspaceName?: string;
     workspaceUuid?: string;
     baseUrl?: string;
+    /**
+     * What to re-run when a code was sent but there is no terminal to type it
+     * into. Defaults to the `login` form. `start` passes its own, because
+     * finishing through `login` would sign the user in and stop there, losing
+     * the destination the run was headed for.
+     */
+    resumeCommand?: string;
+};
+export type EmailSignInResult = {
+    outcome: "signedIn";
+    email: string;
+    workspace: ResolvedWorkspace;
+}
+/** The code was sent, but there is no terminal to type it back into. */
+ | {
+    outcome: "codeSent";
+    email: string;
+    next: 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.
+ *
+ * Returns rather than prints, because two callers need the same exchange and
+ * report it differently: `login` writes the JSON result a script reads, while
+ * `start` carries on to the next question.
  */
+export declare function signInWithEmail(opts: EmailLoginOptions): Promise<EmailSignInResult>;
 export declare function runEmailLogin(opts: EmailLoginOptions): Promise<void>;
 //# sourceMappingURL=email.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"email.d.ts","sourceRoot":"","sources":["../../../src/commands/auth/email.ts"],"names":[],"mappings":"AAcA,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,CA8C1E"}
+{"version":3,"file":"email.d.ts","sourceRoot":"","sources":["../../../src/commands/auth/email.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,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;IACjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GACzB;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,iBAAiB,CAAA;CAAE;AACtE,wEAAwE;GACtE;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,iBAAiB,CAAC,CA8B5B;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2B1E"}

package/build/commands/auth/email.js

@@ -10,24 +10,22 @@ 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.
+ *
+ * Returns rather than prints, because two callers need the same exchange and
+ * report it differently: `login` writes the JSON result a script reads, while
+ * `start` carries on to the next question.
  */
-export async function runEmailLogin(opts) {
+export async function signInWithEmail(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 resumeCommand = opts.resumeCommand !== undefined
+        ? opts.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;
+        return { outcome: "codeSent", email, next: resumeCommand };
     }
     const spinner = startSpinner("Verifying code...");
     const tokens = await exchangeEmailOtp({ email, otp: code });
@@ -38,15 +36,30 @@ export async function runEmailLogin(opts) {
         workspaceUuid: opts.workspaceUuid,
         workspaceName: opts.workspaceName,
     });
-    success(`Signed in as ${email}. Workspace: ${workspace.name}.`);
+    return { outcome: "signedIn", email, workspace };
+}
+export async function runEmailLogin(opts) {
+    const result = await signInWithEmail(opts);
+    if (result.outcome === "codeSent") {
+        // Exit successfully so an agent can relay the code and re-run
+        // non-interactively.
+        outputJson({
+            ok: true,
+            status: "codeSent",
+            email: result.email,
+            next: result.next,
+        });
+        return;
+    }
+    success(`Signed in as ${result.email}. Workspace: ${result.workspace.name}.`);
     info(AGENT_SKILLS_NEXT_STEP);
     outputJson({
         ok: true,
         status: "signedIn",
         credentialsFile: getCredentialsPath(),
         baseUrl: resolveBaseUrl(opts.baseUrl),
-        email,
-        workspace,
+        email: result.email,
+        workspace: result.workspace,
         tokenType: "session",
     });
 }

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":"AACA,OAAO,EAAE,KAAK,OAAO,EAAU,MAAM,WAAW,CAAC;AAGjD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAExC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AA0BxD,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,CAsIN;AAiGD,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/auth/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,OAAO,EAAU,MAAM,WAAW,CAAC;AAGjD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAExC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AA2BxD,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,CAsIN;AA2GD,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

@@ -5,6 +5,7 @@ import { getConfig } from "../../config.js";
 import { clearCredentials, CredentialsNotClearedError, getCredentialsPath, loadCredentials, saveCredentials, } from "../../credentials.js";
 import { parseBooleanOption } from "../../utils/booleanOption.js";
 import { ExitCodes, failWith, handleApiCall, info, outputJson, success, } from "../runHandler.js";
+import { clearStartState } from "../start/state.js";
 import { runEmailLogin } from "./email.js";
 import { selectLoginChannel } from "./loginChannel.js";
 import { runOAuthDeviceFlow } from "./oauth.js";
@@ -171,16 +172,21 @@ async function runLogout(opts) {
         }
         throw error;
     }
+    // Not conditional on `removed`: someone whose credential was an environment
+    // variable, or who is signing out a second time, still means "start over".
+    const startStateCleared = clearStartState();
     if (removed === true) {
         success(revoked === true ? "Signed out and revoked access." : "Signed out.");
     }
     else {
-        info("No saved credentials to remove.");
+        info("No saved credentials to remove — nothing was signed in through this CLI.");
+        info("If commands still work, the token is coming from CARGO_API_TOKEN or a project .env.");
     }
     outputJson({
         ok: true,
         removed,
         revoked,
+        startStateCleared,
         credentialsFile: getCredentialsPath(),
     });
 }

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

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../../src/commands/auth/workspace.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAYzD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,SAAS,EAAE,iBAAiB,CAAC;IAC7B,mFAAmF;IACnF,UAAU,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA2H/B;AAcD,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,SAAS,mBAAmB,CAAC,SAAS,EAAE,EACpD,IAAI,EAAE,MAAM,GACX,iBAAiB,GAAG,SAAS,CAY/B"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../../src/commands/auth/workspace.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAazD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,SAAS,EAAE,iBAAiB,CAAC;IAC7B,mFAAmF;IACnF,UAAU,EAAE,OAAO,CAAC;CACrB,CAAC;AAUF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAkG/B;AAED,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,SAAS,mBAAmB,CAAC,SAAS,EAAE,EACpD,IAAI,EAAE,MAAM,GACX,iBAAiB,GAAG,SAAS,CAY/B"}

package/build/commands/auth/workspace.js

@@ -1,7 +1,14 @@
 import * as readline from "node:readline/promises";
+import { askText, isInteractive, selectOne } from "@cargo-ai/cdk/cli";
 import { createApi } from "../../api.js";
 import { askQuestion, openPromptInput } from "../../utils/prompt.js";
 import { ExitCodes, failWith, handleApiCall, info, success, } from "../runHandler.js";
+/**
+ * The "make me a new one" row. A leading space keeps it out of the uuid
+ * namespace, so it can never collide with a real workspace.
+ */
+const CREATE = " create";
+const DEFAULT_WORKSPACE_NAME = "My workspace";
 export async function resolveWorkspace(opts) {
     const accessToken = opts.accessToken;
     const api = createApi({
@@ -34,28 +41,6 @@ export async function resolveWorkspace(opts) {
             wasCreated: false,
         };
     }
-    if (workspaces.length === 0) {
-        const promptInput = openPromptInput();
-        if (promptInput === undefined) {
-            failWith("No workspaces found. Re-run with --workspace-name <name> to create one.", { code: ExitCodes.NotFound });
-        }
-        let name;
-        try {
-            info("You don't have any workspaces yet. Let's create one.");
-            name = await askQuestion(promptInput.stream, "Workspace name (or press Enter to skip): ");
-        }
-        finally {
-            promptInput.close();
-        }
-        if (name === undefined) {
-            failWith("No workspace name provided.", {
-                code: ExitCodes.InvalidUsage,
-            });
-        }
-        const workspace = await createWorkspace(api, name);
-        success(`Created workspace: ${workspace.name} (${workspace.uuid})`);
-        return { workspace, wasCreated: true };
-    }
     if (workspaces.length === 1) {
         const [firstWorkspace] = workspaces;
         if (firstWorkspace === undefined) {
@@ -66,6 +51,15 @@ export async function resolveWorkspace(opts) {
             wasCreated: false,
         };
     }
+    // Picking an existing workspace and creating one are the same decision, so
+    // they are one question rather than two branches with two different pieces
+    // of UI. The readline path below stays for the terminals clack cannot use.
+    if (isInteractive() === true) {
+        return await chooseWorkspace(api, workspaces);
+    }
+    if (workspaces.length === 0) {
+        return await createWorkspaceByAsking(api);
+    }
     const promptInput = openPromptInput();
     if (promptInput === undefined) {
         failWith("Multiple workspaces available and no interactive terminal; pass --workspace-uuid <uuid> (or set CARGO_WORKSPACE_UUID when using install.sh) to select one.", { code: ExitCodes.InvalidUsage });
@@ -82,10 +76,6 @@ export async function resolveWorkspace(opts) {
     }
     return { workspace: selectedWorkspace, wasCreated: false };
 }
-async function createWorkspace(api, name) {
-    const result = await handleApiCall(() => api.workspaceManagement.workspace.create({ name }), { spinner: "Creating workspace..." });
-    return { uuid: result.workspace.uuid, name: result.workspace.name };
-}
 export function findWorkspaceByName(workspaces, name) {
     const wanted = name.trim().toLowerCase();
     const matched = workspaces.find((workspace) => {
@@ -96,6 +86,89 @@ export function findWorkspaceByName(workspaces, name) {
     }
     return { uuid: matched.uuid, name: matched.name };
 }
+/** Pick from the workspaces you have, or name a new one, in one question. */
+async function chooseWorkspace(api, workspaces) {
+    if (workspaces.length === 0) {
+        info("You don't have any workspaces yet. Let's create one.");
+        return {
+            workspace: await createWorkspace(api, await askWorkspaceName()),
+            wasCreated: true,
+        };
+    }
+    const chosen = await selectOne({
+        // First, not last: past a dozen workspaces the list scrolls, and a create
+        // row at the bottom is off-screen — reachable only by someone who already
+        // guessed to type "create". The cursor still starts on the first
+        // workspace, so the row is visible without Enter landing on it.
+        message: "Which workspace should this CLI work in?",
+        recommended: workspaces[0] === undefined ? CREATE : workspaces[0].uuid,
+        choices: [
+            {
+                value: CREATE,
+                label: "+ Create a new workspace",
+                hint: "you name it",
+                fallback: true,
+            },
+            ...workspaces.map((workspace) => ({
+                value: workspace.uuid,
+                label: workspace.name,
+                hint: workspace.uuid,
+            })),
+        ],
+    });
+    if (chosen === CREATE) {
+        return {
+            workspace: await createWorkspace(api, await askWorkspaceName()),
+            wasCreated: true,
+        };
+    }
+    const selected = workspaces.find((workspace) => workspace.uuid === chosen);
+    if (selected === undefined) {
+        failWith("No workspace selected.", { code: ExitCodes.InvalidUsage });
+    }
+    return {
+        workspace: { uuid: selected.uuid, name: selected.name },
+        wasCreated: false,
+    };
+}
+async function askWorkspaceName() {
+    return await askText({
+        message: "Name it",
+        placeholder: DEFAULT_WORKSPACE_NAME,
+        defaultValue: DEFAULT_WORKSPACE_NAME,
+    });
+}
+/**
+ * The zero-workspace path for terminals clack cannot drive — `curl | sh`
+ * installers pipe stdin while the controlling terminal stays reachable through
+ * /dev/tty, and this is what reads it.
+ */
+async function createWorkspaceByAsking(api) {
+    const promptInput = openPromptInput();
+    if (promptInput === undefined) {
+        failWith("No workspaces found. Re-run with --workspace-name <name> to create one.", { code: ExitCodes.NotFound });
+    }
+    let name;
+    try {
+        info("You don't have any workspaces yet. Let's create one.");
+        name = await askQuestion(promptInput.stream, "Workspace name (or press Enter to skip): ");
+    }
+    finally {
+        promptInput.close();
+    }
+    if (name === undefined) {
+        failWith("No workspace name provided.", {
+            code: ExitCodes.InvalidUsage,
+        });
+    }
+    const workspace = await createWorkspace(api, name);
+    success(`Created workspace: ${workspace.name} (${workspace.uuid})`);
+    return { workspace, wasCreated: true };
+}
+async function createWorkspace(api, name) {
+    const result = await handleApiCall(() => api.workspaceManagement.workspace.create({ name }), { spinner: "Creating workspace..." });
+    return { uuid: result.workspace.uuid, name: result.workspace.name };
+}
 async function promptWorkspaceSelection(workspaces, input) {
     const rl = readline.createInterface({
         input,

package/build/commands/connection/connector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../../../src/commands/connection/connector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAIxC,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAwPN"}
+{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../../../src/commands/connection/connector.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAcxC,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CA6TN"}

package/build/commands/connection/connector.js

@@ -1,5 +1,8 @@
+import { awaitBrowserStep, buildCliConnectorCreateUrl, buildCliConnectorEditUrl, isCodingAgent, openBrowser, resolveUserUuid, shouldWaitForPerson, } from "@cargo-ai/cdk/cli";
+import { getConfig } from "../../config.js";
 import { parseBooleanOption } from "../../utils/booleanOption.js";
-import { handleApiCall, outputJson, parseJson } from "../runHandler.js";
+import { openPromptInput } from "../../utils/prompt.js";
+import { colors, ExitCodes, failWith, handleApiCall, info, outputJson, parseJson, } from "../runHandler.js";
 export function registerConnectorCommands(parent, getApi) {
     const connector = parent
         .command("connector")
@@ -79,39 +82,70 @@ export function registerConnectorCommands(parent, getApi) {
     });
     connector
         .command("create")
-        .description("Create a connector")
-        .requiredOption("--name <name>", "Connector name (string, required)")
-        .requiredOption("--slug <slug>", "Connector slug identifier (string, required)")
+        .description("Create a connector. Without --config, opens the hosted form in a browser and waits.")
+        .option("--name <name>", "Connector name (string, required with --config)")
+        .option("--slug <slug>", "Connector slug identifier (string, required with --config)")
         .requiredOption("--integration-slug <slug>", "Integration slug to connect to (string, required)")
-        .option("--config <json>", "Connector configuration (JSON object, shape depends on integration)")
+        .option("--config <json>", "Connector configuration (JSON object, shape depends on integration). Skips the browser.")
         .option("--rate-limit <json>", 'Rate limit configuration (JSON object). Shape: {"maxRequests": integer, "windowMs": integer}')
         .option("--cache-ttl-milliseconds <n>", "Cache TTL in milliseconds (integer)")
         .addHelpText("after", `
 Examples:
-  $ cargo-ai connection connector create --name "HubSpot" --slug hubspot-main --integration-slug hubspot
+  # Open the hosted form, wait, then write connectors/hubspot.ts and bind it
+  $ cargo-ai connection connector create --integration-slug hubspot
+
+  # Fully non-interactive — no browser
   $ cargo-ai connection connector create --name "HubSpot" --slug hubspot-main --integration-slug hubspot \\
-      --rate-limit '{"maxRequests":100,"windowMs":60000}' --cache-ttl-milliseconds 300000`)
+      --config '{"method":"privateApp","accessToken":"pat-..."}'
+  $ cargo-ai connection connector create --name "HubSpot" --slug hubspot-main --integration-slug hubspot \\
+      --config '{...}' --rate-limit '{"maxRequests":100,"windowMs":60000}' --cache-ttl-milliseconds 300000`)
         .action(async (opts) => {
         const api = getApi();
-        const result = await handleApiCall(() => api.connection.connector.create({
-            name: opts.name,
-            slug: opts.slug,
-            integrationSlug: opts.integrationSlug,
-            config: opts.config !== undefined
-                ? parseJson(opts.config, "--config")
-                : undefined,
-            rateLimit: opts.rateLimit !== undefined
+        // `--config` keeps the original, fully scriptable behaviour.
+        if (opts.config !== undefined) {
+            const rateLimit = opts.rateLimit !== undefined
                 ? parseJson(opts.rateLimit, "--rate-limit")
-                : undefined,
-            cacheTtlMilliseconds: opts.cacheTtlMilliseconds !== undefined
+                : undefined;
+            const cacheTtlMilliseconds = opts.cacheTtlMilliseconds !== undefined
                 ? parseInt(opts.cacheTtlMilliseconds, 10)
-                : undefined,
-        }));
-        outputJson(result);
+                : undefined;
+            const name = opts.name;
+            const slug = opts.slug;
+            if (name === undefined || slug === undefined) {
+                failWith("--name and --slug are required when --config is passed.", { code: ExitCodes.InvalidUsage });
+                return;
+            }
+            const config = parseJson(opts.config, "--config");
+            const result = await handleApiCall(() => api.connection.connector.create({
+                name,
+                slug,
+                integrationSlug: opts.integrationSlug,
+                config,
+                rateLimit,
+                cacheTtlMilliseconds,
+            }));
+            outputJson(result);
+            return;
+        }
+        const ignored = [
+            opts.name === undefined ? undefined : "--name",
+            opts.slug === undefined ? undefined : "--slug",
+            opts.rateLimit === undefined ? undefined : "--rate-limit",
+            opts.cacheTtlMilliseconds === undefined
+                ? undefined
+                : "--cache-ttl-milliseconds",
+        ].filter((flag) => flag !== undefined);
+        // The hosted form asks for all of these itself, so accepting them here
+        // and dropping them would silently produce a connector the caller did
+        // not describe.
+        if (ignored.length > 0) {
+            failWith(`${ignored.join(", ")} only applies with --config — the browser form asks for it.`, { code: ExitCodes.InvalidUsage });
+        }
+        await runCreateHandoff({ api, integrationSlug: opts.integrationSlug });
     });
     connector
         .command("update")
-        .description("Update a connector")
+        .description("Update a connector. With no field flags, opens the hosted form in a browser (use it to re-authorize).")
         .requiredOption("--uuid <uuid>", "Connector UUID")
         .option("--name <name>", "Connector name")
         .option("--config <json>", "Configuration (JSON object)")
@@ -119,6 +153,19 @@ Examples:
         .option("--cache-ttl-milliseconds <n>", "Cache TTL in milliseconds")
         .action(async (opts) => {
         const api = getApi();
+        // No field to change means "let me edit it in the form" — the only way
+        // to re-run an OAuth flow for an existing connector.
+        const hasFieldFlag = opts.name !== undefined ||
+            opts.config !== undefined ||
+            opts.rateLimit !== undefined ||
+            opts.cacheTtlMilliseconds !== undefined;
+        if (hasFieldFlag === false) {
+            // Re-auth changes credentials, not the binding: the CDK file already
+            // exists and binds by slug, so there is nothing to write and nothing
+            // to wait for. Open the form and get out of the way.
+            openConnectorEditForm(opts.uuid);
+            return;
+        }
         const result = await handleApiCall(() => api.connection.connector.update({
             uuid: opts.uuid,
             name: opts.name,
@@ -144,3 +191,79 @@ Examples:
         outputJson(result);
     });
 }
+/**
+ * Send the user to the connectors page, wait for them to confirm, then report
+ * the connector they made.
+ *
+ * Imperative only: it creates a connector and prints it. Writing
+ * `connectors/<slug>.ts` and binding cargo.state.json is
+ * `cargo-ai cdk add connector/<integration>`, so running this inside a repo
+ * never touches the repo.
+ */
+async function runCreateHandoff(input) {
+    const { api, integrationSlug } = input;
+    const url = buildCliConnectorCreateUrl({
+        ...resolveAppContext(),
+        integrationSlug,
+    });
+    // Nothing can drive a browser for an agent: hand back the URL and where to
+    // look once a human has clicked through. `openPromptInput` still finds
+    // `/dev/tty` when stdin is piped; `shouldWaitForPerson` additionally
+    // refuses coding agents, whose stdin often looks like a TTY.
+    if (shouldWaitForPerson({
+        isCodingAgent: isCodingAgent(),
+        isCi: process.env["CI"] === "true",
+        hasPromptInput: openPromptInput() !== undefined,
+    }) === false) {
+        outputJson({
+            ok: true,
+            status: "actionRequired",
+            action: "openBrowser",
+            integrationSlug,
+            url,
+            reason: "Creating this connector needs the hosted form, which cannot be driven headlessly.",
+            next: `cargo-ai connection connector list --integration-slug ${integrationSlug}`,
+        });
+        return;
+    }
+    const [before, userUuid] = await Promise.all([
+        handleApiCall(() => api.connection.connector.list({ integrationSlug })),
+        resolveUserUuid(api),
+    ]);
+    const connector = await awaitBrowserStep({
+        api,
+        url,
+        integrationSlug,
+        before: before.connectors,
+        userUuid,
+    });
+    if (connector === undefined) {
+        return;
+    }
+    outputJson({ ok: true, status: "connected", connector });
+}
+/** Open this connector's edit form so the user can re-run its auth flow. */
+function openConnectorEditForm(connectorUuid) {
+    const url = buildCliConnectorEditUrl({
+        ...resolveAppContext(),
+        connectorUuid,
+    });
+    info(["", "Re-authorize the connector here:", `  ${colors.cyan(url)}`, ""].join("\n"));
+    openBrowser(url);
+    outputJson({
+        ok: true,
+        status: "actionRequired",
+        action: "openBrowser",
+        url,
+    });
+}
+/** The workspace to act in; the app URL is configuration, not a guess. */
+function resolveAppContext() {
+    const { appUrl, workspaceUuid } = getConfig();
+    if (workspaceUuid === undefined) {
+        return failWith("No workspace selected. Run 'cargo-ai login' first.", {
+            code: ExitCodes.NotAuthenticated,
+        });
+    }
+    return { appUrl, workspaceUuid };
+}

package/build/commands/start/brief.d.ts

@@ -0,0 +1,107 @@
+import { CDK_SKILL, type CodingAgent } from "@cargo-ai/cdk/cli";
+/**
+ * Where the agent is being opened, which decides what it is told to do.
+ *
+ * Three cases, because the right first move is different in each: outside a
+ * project there is nothing to read and the work starts with a conversation;
+ * inside a CDK repo the workspace is already declared in files worth reading
+ * before touching; and inside one carrying a cookbook, that cookbook's own
+ * procedure is the authority and re-deriving intent is the wrong move.
+ *
+ * Naming the same skill in all three, which is what this used to do, sent an
+ * agent into a repo full of answers and told it to start asking questions.
+ */
+export type ProjectContext = {
+    kind: "none";
+} | {
+    kind: "cdk";
+    root: string;
+    companyContextPath: string | undefined;
+} | {
+    kind: "cookbook";
+    root: string;
+    companyContextPath: string | undefined;
+    cookbooks: readonly string[];
+};
+export type StartFacts = {
+    workspace: {
+        uuid: string;
+        name: string;
+    };
+    /** Whether the Cargo skills bundle is already installed for a coding agent. */
+    skillsInstalled: boolean;
+};
+/**
+ * The command group "Explore in the CLI" opens the palette on. The action
+ * catalog is the shortest path from a menu to something real: search one, run
+ * one, see a result.
+ */
+export declare const EXPLORE_PATH: readonly string[];
+/**
+ * The skill a handoff loads before the agent's first turn. `cargo` routes; the
+ * other two own their task outright.
+ *
+ * This type is the one place the whole story lives, because everything about
+ * the handoff depends on getting it right, and it has been got wrong twice.
+ *
+ * A skill reaches the agent by two paths at once: the launch passes it as a
+ * `/<skill>` command, which only Claude Code expands, and the brief names it in
+ * prose, which is all every other agent has. So the two must agree. The first
+ * version of the demo brief described its *outcome* instead of naming a skill
+ * and let the router choose; the router picked `cargo-gtm`, the general
+ * sourcing surface, and the agent spent four of its eight minutes rediscovering
+ * action names and dumping integration JSON to find a config schema. The
+ * second version named `cargo-quickstart` in the launch but left the brief
+ * saying "load `cargo`", which put every non-Claude agent back through the
+ * router and made the demo ask for two different skills in two steps.
+ *
+ * Hence a union rather than `string`: a mistyped or mismatched skill name is
+ * not something the CLI can notice at runtime, and the symptom is slow rather
+ * than broken, which is the kind of bug that survives.
+ */
+export type HandoffSkill = "cargo" | typeof CDK_SKILL | "cargo-quickstart";
+export declare const ROUTER_SKILL: HandoffSkill;
+export declare const DEMO_SKILL: HandoffSkill;
+export { CDK_SKILL };
+export type Destination = {
+    kind: "agent";
+    agent: CodingAgent;
+} | {
+    kind: "code";
+} | {
+    kind: "cli";
+} | {
+    kind: "demo";
+} | {
+    kind: "none";
+};
+/**
+ * `--continue <where>` as a destination. Agents are named the way a person
+ * refers to them ("cursor"), not the way they are installed ("cursor-agent"),
+ * and one that is not on this machine is a usage error rather than a silent
+ * fallback to something else.
+ */
+export declare function parseDestination(value: string, agents: readonly CodingAgent[]): Destination | undefined;
+/**
+ * The brief a coding agent is opened with. An agent launched in a bare
+ * directory has to rediscover the workspace, the skills and the cost rules;
+ * this is the whole reason the handoff beats telling someone to open Claude
+ * Code themselves.
+ *
+ * What it says depends on `project` — see `ProjectContext` for why all three
+ * cases need different words rather than one brief and a different skill name.
+ */
+export declare function buildBrief(facts: StartFacts, skill: HandoffSkill, project?: ProjectContext): string;
+/**
+ * The brief behind the guided demo.
+ *
+ * It names `cargo-quickstart` rather than describing the demo, because that
+ * skill *is* this demo — a persona, ~25 leads, a cost receipt, then saving the
+ * pull as a play. Describing the outcome instead is what cost the first version
+ * half its runtime (see `HandoffSkill`), so this brief spends its length on
+ * pointing at the procedure and forbidding the detour.
+ */
+export declare function buildDemoBrief(facts: StartFacts, icp: string | undefined): string;
+/** The block printed when nobody wanted a handoff. */
+export declare function formatStartNextSteps(facts: StartFacts): string;
+//# sourceMappingURL=brief.d.ts.map

package/build/commands/start/brief.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brief.d.ts","sourceRoot":"","sources":["../../../src/commands/start/brief.ts"],"names":[],"mappings":"AAMA,OAAO,EAEL,SAAS,EACT,KAAK,WAAW,EAEjB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACrE;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B,CAAC;AAEN,MAAM,MAAM,UAAU,GAAG;IACvB,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,+EAA+E;IAC/E,eAAe,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAAgC,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,OAAO,SAAS,GAAG,kBAAkB,CAAC;AAE3E,eAAO,MAAM,YAAY,EAAE,YAAsB,CAAC;AAClD,eAAO,MAAM,UAAU,EAAE,YAAiC,CAAC;AAE3D,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GACf;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,SAAS,WAAW,EAAE,GAC7B,WAAW,GAAG,SAAS,CA8BzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,cAAiC,GACzC,MAAM,CAaR;AAyED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,MAAM,CA+BR;AAED,sDAAsD;AACtD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAgB9D"}