@cantinasecurity/apex-cli 0.1.16 → 0.1.18

package/dist/config.js

@@ -1,13 +1,92 @@
-import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { lock } from "proper-lockfile";
 const CONFIG_DIR = path.join(os.homedir(), ".config", "apex");
 const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 const CREDENTIALS_PATH = path.join(CONFIG_DIR, "credentials.json");
+const CREDENTIAL_LIFECYCLE_LOCK_PATH = path.join(CONFIG_DIR, "credential-lifecycle");
 const DEFAULT_BASE_URL = process.env.APEX_BASE_URL ?? "https://ai.cantina.xyz/";
+const GUEST_CREDENTIAL_FIELDS = [
+    "guest",
+    "guestCompanyId",
+    "claimToken",
+    "claimExpiresAt",
+    "guestSessionExpiresAt",
+    "onboardingCodeHash",
+];
+let configWriteChain = Promise.resolve();
+let credentialsWriteChain = Promise.resolve();
+let credentialLifecycleChain = Promise.resolve();
+const FILE_LOCK_STALE_MS = 30_000;
+const FILE_LOCK_RETRY_OPTIONS = {
+    retries: 80,
+    factor: 1.15,
+    minTimeout: 10,
+    maxTimeout: 100,
+    randomize: true,
+};
+function canonicalizeCredentialValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(canonicalizeCredentialValue);
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, nested]) => [key, canonicalizeCredentialValue(nested)]));
+    }
+    return value;
+}
+/**
+ * Returns an opaque, non-secret identifier for one complete credential-file
+ * generation. Device-login flows can carry this value across process/tool
+ * boundaries without exposing access, refresh, or claim credentials.
+ */
+export function getCredentialGeneration(credentials) {
+    const canonical = JSON.stringify(canonicalizeCredentialValue(credentials));
+    const digest = createHash("sha256").update(canonical).digest("hex");
+    return `v1:${digest}`;
+}
+function serializeWrite(chain, setChain, action) {
+    const result = chain.then(action, action);
+    setChain(result.then(() => undefined, () => undefined));
+    return result;
+}
+async function withInterprocessFileLock(targetPath, action, retries = FILE_LOCK_RETRY_OPTIONS) {
+    await ensureConfigDir();
+    const release = await lock(targetPath, {
+        realpath: false,
+        stale: FILE_LOCK_STALE_MS,
+        update: 10_000,
+        retries,
+    });
+    try {
+        return await action();
+    }
+    finally {
+        await release();
+    }
+}
+function isLockContentionError(error) {
+    return Boolean(error &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "ELOCKED");
+}
 async function ensureConfigDir() {
     await mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
 }
+/**
+ * Serializes multi-request auth lifecycle flows (redeem/claim/revoke/logout)
+ * across CLI and MCP processes without holding the credential-file lock during
+ * network I/O.
+ */
+export function withCredentialLifecycleLock(action) {
+    return serializeWrite(credentialLifecycleChain, (next) => {
+        credentialLifecycleChain = next;
+    }, () => withInterprocessFileLock(CREDENTIAL_LIFECYCLE_LOCK_PATH, action));
+}
 async function readJsonFile(filePath) {
     try {
         const contents = await readFile(filePath, "utf8");
@@ -19,40 +98,295 @@ async function readJsonFile(filePath) {
 }
 async function writeJsonFile(filePath, value, mode) {
     await ensureConfigDir();
-    await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, {
-        encoding: "utf8",
-        mode,
-    });
-    await chmod(filePath, mode);
+    const temporaryPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, {
+            encoding: "utf8",
+            mode,
+        });
+        await chmod(temporaryPath, mode);
+        await rename(temporaryPath, filePath);
+        await chmod(filePath, mode);
+    }
+    catch (error) {
+        await rm(temporaryPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
 }
 export async function loadConfig() {
     const config = await readJsonFile(CONFIG_PATH);
-    if (!config?.baseUrl) {
-        return {
-            version: 1,
-            baseUrl: DEFAULT_BASE_URL,
-            defaultCompanyId: null,
-            telemetryDisabled: config?.telemetryDisabled ?? null,
-            telemetryInstallId: config?.telemetryInstallId ?? null,
-        };
-    }
     return {
         version: 1,
-        baseUrl: config.baseUrl,
-        defaultCompanyId: config.defaultCompanyId ?? null,
-        telemetryDisabled: config.telemetryDisabled ?? null,
-        telemetryInstallId: config.telemetryInstallId ?? null,
+        baseUrl: config?.baseUrl || DEFAULT_BASE_URL,
+        defaultCompanyId: config?.defaultCompanyId ?? null,
+        telemetryDisabled: config?.telemetryDisabled ?? null,
+        telemetryInstallId: config?.telemetryInstallId ?? null,
+        onboardingFingerprint: config?.onboardingFingerprint ?? null,
     };
 }
 export async function saveConfig(config) {
-    await writeJsonFile(CONFIG_PATH, config, 0o600);
+    await serializeWrite(configWriteChain, (next) => {
+        configWriteChain = next;
+    }, () => withInterprocessFileLock(CONFIG_PATH, () => writeJsonFile(CONFIG_PATH, config, 0o600)));
+}
+export async function updateConfig(updates) {
+    await serializeWrite(configWriteChain, (next) => {
+        configWriteChain = next;
+    }, () => withInterprocessFileLock(CONFIG_PATH, async () => {
+        const existing = (await readJsonFile(CONFIG_PATH)) ?? {};
+        await writeJsonFile(CONFIG_PATH, { ...existing, ...updates, version: 1 }, 0o600);
+    }));
+}
+/**
+ * Atomically returns a normalized config value or persists a freshly created
+ * one. The read and write share the same interprocess lock so concurrent CLI
+ * and MCP processes cannot each observe and use a different first-use value.
+ */
+export async function getOrCreateConfigString(key, normalizeExisting, createValue) {
+    return serializeWrite(configWriteChain, (next) => {
+        configWriteChain = next;
+    }, () => withInterprocessFileLock(CONFIG_PATH, async () => {
+        const existing = (await readJsonFile(CONFIG_PATH)) ?? {};
+        const normalized = normalizeExisting(existing[key]);
+        if (normalized !== null) {
+            if (existing[key] !== normalized || existing.version !== 1) {
+                await writeJsonFile(CONFIG_PATH, { ...existing, [key]: normalized, version: 1 }, 0o600);
+            }
+            return normalized;
+        }
+        const created = createValue();
+        await writeJsonFile(CONFIG_PATH, { ...existing, [key]: created, version: 1 }, 0o600);
+        return created;
+    }));
 }
 export async function loadCredentials() {
     return readJsonFile(CREDENTIALS_PATH);
 }
-export async function saveCredentials(credentials) {
-    await writeJsonFile(CREDENTIALS_PATH, credentials, 0o600);
+export async function saveCredentials(credentials, options = {}) {
+    await serializeWrite(credentialsWriteChain, (next) => {
+        credentialsWriteChain = next;
+    }, () => withInterprocessFileLock(CREDENTIALS_PATH, async () => {
+        const existing = options.replace
+            ? null
+            : await readJsonFile(CREDENTIALS_PATH);
+        const nextCredentials = {
+            ...(existing ?? {}),
+            ...credentials,
+        };
+        if (options.clearGuestFields) {
+            for (const field of GUEST_CREDENTIAL_FIELDS) {
+                delete nextCredentials[field];
+            }
+        }
+        await writeJsonFile(CREDENTIALS_PATH, nextCredentials, 0o600);
+    }));
+}
+/**
+ * Commits device-login account credentials only while the exact credential
+ * file observed before device auth is still current. The matching file is
+ * merged so recoverable guest claim metadata survives an intentional account
+ * login; a mismatched winner is neither returned nor modified.
+ */
+export async function saveDeviceLoginCredentialsIfGenerationMatches(expectedGeneration, credentials) {
+    try {
+        // Device approval may arrive while a long-running claim is waiting on the
+        // browser. Do not hold or queue behind that flow: the lifecycle lock makes
+        // this commit all-or-nothing, and immediate contention safely discards the
+        // approved tokens while preserving the operation already in progress.
+        return await withInterprocessFileLock(CREDENTIAL_LIFECYCLE_LOCK_PATH, () => serializeWrite(credentialsWriteChain, (next) => {
+            credentialsWriteChain = next;
+        }, () => withInterprocessFileLock(CREDENTIALS_PATH, async () => {
+            const existing = await readJsonFile(CREDENTIALS_PATH);
+            if (getCredentialGeneration(existing) !== expectedGeneration) {
+                return "generation_changed";
+            }
+            const nextCredentials = {
+                ...(existing ?? {}),
+                ...credentials,
+                guest: false,
+            };
+            await writeJsonFile(CREDENTIALS_PATH, nextCredentials, 0o600);
+            return "saved";
+        })), 0);
+    }
+    catch (error) {
+        if (isLockContentionError(error)) {
+            return "credential_operation_busy";
+        }
+        throw error;
+    }
+}
+/**
+ * Commits a rotated token pair only while the credential generation that
+ * initiated the refresh is still current. Callers must inspect `saved`: when
+ * claim/login advanced storage in the meantime, the stale response is
+ * discarded and the winner is returned only for diagnostics, never as retry
+ * credentials for the operation that lost the compare-and-swap.
+ */
+export async function saveRefreshedCredentialsIfCurrent(expectedRefreshToken, credentials) {
+    return serializeWrite(credentialsWriteChain, (next) => {
+        credentialsWriteChain = next;
+    }, () => withInterprocessFileLock(CREDENTIALS_PATH, async () => {
+        const existing = await readJsonFile(CREDENTIALS_PATH);
+        if (!existing || existing.refreshToken !== expectedRefreshToken) {
+            return { saved: false, credentials: existing };
+        }
+        const nextCredentials = { ...existing, ...credentials };
+        await writeJsonFile(CREDENTIALS_PATH, nextCredentials, 0o600);
+        return { saved: true, credentials: nextCredentials };
+    }));
 }
-export async function clearCredentials() {
+/**
+ * Adds an issuer origin to a legacy credential file only while the complete
+ * observed generation is still current. Origin migration must never overwrite
+ * a concurrent refresh, login, redeem, claim, or logout winner.
+ */
+export async function bindCredentialIssuerOriginIfCurrent(expectedCredentials, issuerOrigin) {
+    return serializeWrite(credentialsWriteChain, (next) => {
+        credentialsWriteChain = next;
+    }, () => withInterprocessFileLock(CREDENTIALS_PATH, async () => {
+        const existing = await readJsonFile(CREDENTIALS_PATH);
+        if (getCredentialGeneration(existing) !==
+            getCredentialGeneration(expectedCredentials)) {
+            return { saved: false, credentials: existing };
+        }
+        const nextCredentials = { ...existing, issuerOrigin };
+        await writeJsonFile(CREDENTIALS_PATH, nextCredentials, 0o600);
+        return { saved: true, credentials: nextCredentials };
+    }));
+}
+function isCompatibleCredentialState(expectedCredentials, existing) {
+    const isAuthenticatedAccount = (credentials) => Boolean(credentials?.guest !== true &&
+        (credentials?.accessToken?.trim() || credentials?.refreshToken?.trim()));
+    const expectedRefreshToken = expectedCredentials?.refreshToken?.trim() ?? "";
+    const isExactGeneration = expectedCredentials === null
+        ? existing === null
+        : Boolean(expectedRefreshToken &&
+            existing?.refreshToken === expectedCredentials.refreshToken);
+    const isSameGuestRefresh = Boolean(expectedCredentials?.guest === true &&
+        existing?.guest === true &&
+        existing.guestCompanyId === expectedCredentials.guestCompanyId &&
+        existing.claimToken === expectedCredentials.claimToken &&
+        existing.claimExpiresAt === expectedCredentials.claimExpiresAt &&
+        existing.guestSessionExpiresAt ===
+            expectedCredentials.guestSessionExpiresAt &&
+        existing.onboardingCodeHash === expectedCredentials.onboardingCodeHash);
+    const expectedClaimToken = expectedCredentials?.claimToken?.trim() ?? "";
+    const isSameProofLifecycle = Boolean(expectedClaimToken &&
+        existing?.guestCompanyId === expectedCredentials?.guestCompanyId &&
+        existing?.claimToken === expectedCredentials?.claimToken &&
+        existing?.claimExpiresAt === expectedCredentials?.claimExpiresAt &&
+        existing?.guestSessionExpiresAt ===
+            expectedCredentials?.guestSessionExpiresAt &&
+        existing?.onboardingCodeHash === expectedCredentials?.onboardingCodeHash &&
+        !isAuthenticatedAccount(expectedCredentials) &&
+        !isAuthenticatedAccount(existing));
+    return isExactGeneration || isSameGuestRefresh || isSameProofLifecycle;
+}
+/**
+ * Replaces the complete credential file only when the auth state observed
+ * before a network flow is still compatible. A same-guest token refresh is
+ * compatible because it preserves the proof and guest lifecycle identity; a
+ * login, claim, replacement, or newer redeem is not. This prevents a slow
+ * redeem from overwriting a different auth flow without penalizing routine
+ * CLI/MCP refresh concurrency.
+ */
+export async function replaceCredentialsIfCurrent(expectedCredentials, credentials) {
+    return serializeWrite(credentialsWriteChain, (next) => {
+        credentialsWriteChain = next;
+    }, () => withInterprocessFileLock(CREDENTIALS_PATH, async () => {
+        const existing = await readJsonFile(CREDENTIALS_PATH);
+        if (!isCompatibleCredentialState(expectedCredentials, existing)) {
+            return { saved: false, credentials: existing };
+        }
+        await writeJsonFile(CREDENTIALS_PATH, credentials, 0o600);
+        return { saved: true, credentials };
+    }));
+}
+/** Clears the observed guest lifecycle, including a compatible token refresh. */
+export async function clearCredentialsIfCurrent(expectedCredentials, options = {}) {
+    return serializeWrite(credentialsWriteChain, (next) => {
+        credentialsWriteChain = next;
+    }, () => withInterprocessFileLock(CREDENTIALS_PATH, async () => {
+        const existing = await readJsonFile(CREDENTIALS_PATH);
+        if (!isCompatibleCredentialState(expectedCredentials, existing)) {
+            return false;
+        }
+        await clearCredentialFile(existing, options);
+        return true;
+    }));
+}
+/**
+ * Removes a revoked guest proof from a newer account session without touching
+ * that session's token pair. The claim-token match prevents an older revoke
+ * response from stripping a newer redeem generation.
+ */
+export async function clearGuestFieldsIfClaimTokenMatches(expectedClaimToken) {
+    return serializeWrite(credentialsWriteChain, (next) => {
+        credentialsWriteChain = next;
+    }, () => withInterprocessFileLock(CREDENTIALS_PATH, async () => {
+        const existing = await readJsonFile(CREDENTIALS_PATH);
+        if (!existing || existing.claimToken !== expectedClaimToken) {
+            return false;
+        }
+        const nextCredentials = { ...existing };
+        for (const field of GUEST_CREDENTIAL_FIELDS) {
+            delete nextCredentials[field];
+        }
+        await writeJsonFile(CREDENTIALS_PATH, nextCredentials, 0o600);
+        return true;
+    }));
+}
+async function clearCredentialFile(existing, options) {
+    if (options.preserveClaimProof && existing?.claimToken) {
+        await writeJsonFile(CREDENTIALS_PATH, {
+            accessToken: "",
+            refreshToken: "",
+            accessTokenExpiresAt: "1970-01-01T00:00:00.000Z",
+            refreshTokenExpiresAt: "1970-01-01T00:00:00.000Z",
+            ...(existing.issuerOrigin
+                ? { issuerOrigin: existing.issuerOrigin }
+                : {}),
+            // A proof-only stub has no usable guest bearer session. Keeping
+            // guest=true would make local status and logout treat dead auth as
+            // active even though claim can use the proof independently.
+            guest: false,
+            ...(existing.guestCompanyId
+                ? { guestCompanyId: existing.guestCompanyId }
+                : {}),
+            claimToken: existing.claimToken,
+            claimExpiresAt: existing.claimExpiresAt ?? null,
+            guestSessionExpiresAt: existing.guestSessionExpiresAt ?? null,
+            ...(existing.onboardingCodeHash
+                ? { onboardingCodeHash: existing.onboardingCodeHash }
+                : {}),
+        }, 0o600);
+        return;
+    }
     await rm(CREDENTIALS_PATH, { force: true });
 }
+export async function clearCredentials(options = {}) {
+    await serializeWrite(credentialsWriteChain, (next) => {
+        credentialsWriteChain = next;
+    }, () => withInterprocessFileLock(CREDENTIALS_PATH, async () => {
+        const existing = options.preserveClaimProof
+            ? await readJsonFile(CREDENTIALS_PATH)
+            : null;
+        await clearCredentialFile(existing, options);
+    }));
+}
+/** Clears only the credential generation that received the unauthorized result. */
+export async function clearCredentialsIfRefreshTokenMatches(expectedRefreshToken, options = {}) {
+    return serializeWrite(credentialsWriteChain, (next) => {
+        credentialsWriteChain = next;
+    }, () => withInterprocessFileLock(CREDENTIALS_PATH, async () => {
+        const existing = await readJsonFile(CREDENTIALS_PATH);
+        if (!existing ||
+            existing.refreshToken !== expectedRefreshToken ||
+            (options.preserveGuestSession && existing.guest === true)) {
+            return false;
+        }
+        await clearCredentialFile(existing, options);
+        return true;
+    }));
+}

package/dist/findings.js

@@ -1,5 +1,5 @@
 import { fetchWorkspaceScans, getScanDisplayId, matchesScanId, } from "./scan.js";
-import { ApiError } from "./api-client.js";
+import { ApiError, CredentialGenerationChangedError, isTerminalGuestSessionError, } from "./api-client.js";
 const FINDING_UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const CANTINA_AUTH_TOKEN_ENV = "CANTINA_AUTH_TOKEN";
 const FINDING_WRITE_AUTH_ERROR = "Finding comments, feedback, and fix review scans require Apex authentication. Run `apex login` or use MCP `apex-auth-start` followed by `apex-auth-wait`, then retry.";
@@ -61,10 +61,27 @@ function matchesFindingRef(finding, findingRef) {
 }
 async function requestFindingAppRoute(client, path, options = {}) {
     const baseUrl = await client.getBaseUrl();
-    const accessToken = await client.getAccessToken();
+    let bearerTerminalError = null;
+    let accessCredentials = null;
+    try {
+        accessCredentials = await client.getAccessCredentials();
+    }
+    catch (error) {
+        if (!isTerminalGuestSessionError(error))
+            throw error;
+        // getAccessCredentials already demoted the exact failed generation. Keep
+        // the typed error for claim-first guidance if cookie fallback is absent or
+        // also unauthorized.
+        bearerTerminalError = error;
+    }
+    const accessToken = accessCredentials?.accessToken ?? null;
+    const attemptedRefreshToken = accessCredentials?.refreshToken ?? null;
+    let activeBearerRefreshToken = attemptedRefreshToken;
     const legacyCookieToken = getCantinaAuthToken();
     let attemptedBearerAuth = false;
     if (!accessToken && !legacyCookieToken) {
+        if (bearerTerminalError)
+            throw bearerTerminalError;
         throw new Error(FINDING_WRITE_AUTH_ERROR);
     }
     const send = async (auth) => {
@@ -97,12 +114,27 @@ async function requestFindingAppRoute(client, path, options = {}) {
         ? { type: "bearer", token: accessToken }
         : { type: "cookie", token: legacyCookieToken };
     let { response, body } = await sendAndParse(primaryAuth);
-    if (!response.ok && response.status === 401 && primaryAuth.type === "bearer") {
-        const refreshedToken = await client
-            .refreshSession()
-            .then((credentials) => credentials?.accessToken ?? null)
-            .catch(() => null);
+    if (!response.ok &&
+        response.status === 401 &&
+        primaryAuth.type === "bearer" &&
+        attemptedRefreshToken) {
+        let refreshedCredentials = null;
+        try {
+            refreshedCredentials = await client.refreshSession(attemptedRefreshToken, {
+                expectedAccessToken: accessToken ?? undefined,
+            });
+        }
+        catch (error) {
+            if (error instanceof CredentialGenerationChangedError)
+                throw error;
+            if (isTerminalGuestSessionError(error)) {
+                await client.clearCredentialsForGeneration(attemptedRefreshToken, error);
+                bearerTerminalError = error;
+            }
+        }
+        const refreshedToken = refreshedCredentials?.accessToken ?? null;
         if (refreshedToken) {
+            activeBearerRefreshToken = refreshedCredentials?.refreshToken ?? null;
             ({ response, body } = await sendAndParse({
                 type: "bearer",
                 token: refreshedToken,
@@ -117,8 +149,17 @@ async function requestFindingAppRoute(client, path, options = {}) {
     }
     if (!response.ok) {
         if (response.status === 401) {
-            if (attemptedBearerAuth) {
-                await client.clearCredentials();
+            const unauthorizedError = new ApiError(`Request failed with ${response.status}`, response.status, body);
+            if (isTerminalGuestSessionError(unauthorizedError)) {
+                if (attemptedBearerAuth && activeBearerRefreshToken) {
+                    await client.clearCredentialsForGeneration(activeBearerRefreshToken, unauthorizedError);
+                }
+                throw unauthorizedError;
+            }
+            if (bearerTerminalError)
+                throw bearerTerminalError;
+            if (attemptedBearerAuth && activeBearerRefreshToken) {
+                await client.clearCredentialsForGeneration(activeBearerRefreshToken, unauthorizedError);
             }
             throw new Error(FINDING_WRITE_AUTH_ERROR);
         }

package/dist/help.js

@@ -1,6 +1,6 @@
 export const CLI_HELP_TEXT = `Usage:
   apex                              Open the interactive Apex shell
-  apex credits                      Show scan credits plus audit and fix review scan entitlements for the active company
+  apex credits                      Show standard, audit, fix review, and Lite scan entitlements for the active company
   apex scan                         Create or resolve a workspace for this directory and start a scan
   apex scans                        List scans for the current workspace binding
   apex findings                     List findings for the latest or selected scan
@@ -19,6 +19,8 @@ export const CLI_HELP_TEXT = `Usage:
   apex status                       Show progress for the latest or selected scan
   apex doctor                       Validate auth, repos, connections, and workspace binding
   apex login                        Sign in to Apex
+  apex redeem <trial-code>          Start a temporary guest session without device login
+  apex claim                        Link a guest workspace and findings to a Cantina account
   apex logout                       Sign out locally
   apex service-key create           Create an organization service key (shown once)
   apex service-key list             List service-key metadata for an organization
@@ -55,11 +57,12 @@ Flags:
                                     Choose the export format for findings
   --output <path>                   Write exported findings to this file path
   --limit <count>                   Limit the number of findings returned
-  --mode standard|audit|pr          Choose the scan mode
+  --mode standard|audit|lite|pr     Choose the scan mode
   --pr <number[:path,path]>         Select a GitHub pull request for --mode pr
   --pr-path <path>                  Limit a single-PR scan to a changed file path
   --source-mode auto|remote|local   Control remote-vs-local source materialization
-  --force                           Start a new scan even if another scan is active
+  --force                           Start an overlapping scan, or confirm destructive guest logout
+  --replace                         Revoke and replace an existing guest trial session
   --repo <path>                     Include one or more explicit local source roots
   --json                            Print machine-readable JSON output
   --no-open                         Do not open browser flows automatically
@@ -71,8 +74,14 @@ Tips:
   apex scan uses the current directory as the default source root unless you pass --repo.
   PR scans require --mode pr and at least one --pr selection for a GitHub repository.
   audit is the current scan mode for audit scans; ultra remains accepted as a legacy alias.
+  Lite scans use --mode lite and require beta access plus provider-backed GitHub or GitLab sources.
   apex workspace use accepts a workspace name, prefix, or ID.
   Finding comments, feedback, and fix review scans use the same Apex login credentials as other CLI commands.
+  Trial codes go only to apex redeem. Never echo, log, save, telemeter, or send them through MCP.
+  Trial redemption, claim, and revocation require https://ai.cantina.xyz and reject other APEX_BASE_URL origins before sending secrets.
+  apex redeem never starts device login or opens a browser; apex claim is the only onboarding command that may open one.
+  After a guest scan, run apex claim on the same machine within the displayed claim deadline to keep the results.
+  Claim currently requires an account without an existing personal Apex tenant; otherwise contact Cantina support before the deadline.
   Service-key commands require an existing login; run apex login first when needed.
   Apex automatically selects your company when only one is available. With multiple companies, choose one interactively or pass --company.
   Service-key creation also requires --name and reveals the secret only once; omit --scope to grant all hosted API scopes.
@@ -87,8 +96,9 @@ Tips:
 export const SHELL_HELP_TEXT = `Press Tab to autocomplete commands and common arguments.
 
 Commands:
-  /credits                Show scan credits plus audit and fix review scan entitlements for the active company
-  /scan [standard|audit]  Start a new Apex scan for this workspace
+  /credits                Show standard, audit, fix review, and Lite scan entitlements for the active company
+  /scan [standard|audit|lite]
+                           Start a new Apex scan for this workspace
   /scan pr <pr-number>    Start a PR scan for this workspace
   /scans                  List scans for this workspace
   /findings [scan-id]     List findings for the latest or selected scan
@@ -108,6 +118,7 @@ Commands:
   /telemetry [status|enable|disable]
                           Show or change local anonymous usage telemetry settings
   /update                 Update the local Apex CLI install and exit the shell
+  /claim                  Link the current guest workspace and findings to a Cantina account
   /logout                 Sign out locally and exit the shell
   /repos                  List detected repositories
   /workspace              Show the current local workspace binding
@@ -122,6 +133,8 @@ Commands:
   /exit                   Exit Apex
 
 Scripted-only commands (run outside the interactive shell):
+  apex redeem <trial-code> [--json] [--replace]
+                           Start a guest session without device login or browser access
   apex service-key create --name <name> [--company <id-or-handle>] [--scope <scope[,scope]>]
                            Create an organization service key (shown once)
   apex service-key list [--company <id-or-handle>]
@@ -132,8 +145,11 @@ Scripted-only commands (run outside the interactive shell):
 Tips:
   PR scans require a GitHub PR number and provider-backed repository access.
   audit is the current scan mode for audit scans; ultra remains accepted as a legacy alias.
+  Lite scans require beta access plus provider-backed GitHub or GitLab sources.
   /workspace use accepts a workspace name, prefix, or ID.
   /findings comment, /findings feedback, and /findings fix-review use the current Apex login.
+  /claim is the only onboarding command that may open a browser. Trial redemption stays scripted-only and is not exposed through MCP.
+  Claim currently requires an account without an existing personal Apex tenant; otherwise contact Cantina support before the deadline.
   Service-key commands automatically use your company when only one is available. With multiple companies, choose one interactively or pass --company.
   Service-key secrets are shown once. Run these commands in your terminal, not in the interactive shell or through MCP.
   Invalid finding feedback requires a dismissal reason.