@mintlify/cli 4.0.1713 → 4.0.1715

package/bin/welcome.js

@@ -36,6 +36,7 @@ const GROUPS = [
         title: 'Account',
         commands: [
             { name: 'login', description: 'Authenticate with Mintlify' },
+            { name: 'claim', description: 'Claim a site created with mint deploy' },
             { name: 'logout', description: 'Sign out on this device' },
             { name: 'status', description: 'View authentication status' },
         ],
@@ -51,6 +52,11 @@ const GROUPS = [
 const EXAMPLES = [
     { name: 'dev', description: 'Start a local preview of your site' },
     { name: 'new docs', description: 'Scaffold a new site in ./docs' },
+    {
+        name: 'claim --email you@example.com',
+        description: 'Get a claim link; use the deployment directory',
+    },
+    { name: 'claim --code <code>', description: 'Finish the claim in the same directory' },
     { name: 'validate', description: 'Validate your site before shipping' },
     { name: 'broken-links', description: 'Find broken links across your site' },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1713",
+  "version": "4.0.1715",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -45,12 +45,12 @@
   },
   "dependencies": {
     "@inquirer/prompts": "7.9.0",
-    "@mintlify/common": "1.0.1295",
-    "@mintlify/link-rot": "3.0.1520",
+    "@mintlify/common": "1.0.1296",
+    "@mintlify/link-rot": "3.0.1521",
     "@mintlify/models": "0.0.378",
-    "@mintlify/og": "0.0.94",
-    "@mintlify/prebuild": "1.0.1460",
-    "@mintlify/previewing": "4.0.1538",
+    "@mintlify/og": "0.0.95",
+    "@mintlify/prebuild": "1.0.1461",
+    "@mintlify/previewing": "4.0.1539",
     "@mintlify/validation": "0.1.940",
     "adm-zip": "0.6.0",
     "chalk": "5.2.0",
@@ -82,7 +82,7 @@
     "keytar": "7.9.0"
   },
   "devDependencies": {
-    "@mintlify/editor": "0.0.562",
+    "@mintlify/editor": "0.0.563",
     "@mintlify/ts-config": "2.0.2",
     "@tsconfig/recommended": "1.0.2",
     "@types/detect-port": "1.3.2",
@@ -101,5 +101,5 @@
     "vitest": "2.1.9",
     "vitest-mock-process": "1.0.4"
   },
-  "gitHead": "c2289baf20353b9ed7e11ed8ec20b8e644b63a8c"
+  "gitHead": "597cd230e480b7026623253191c869f82964b334"
 }

package/src/agent-auth.ts

@@ -13,9 +13,10 @@ const discoverySchema = z.object({
     identity_types_supported: z.array(z.string()),
   }),
 });
+export const agentIdentityAssertionSchema = z.object({ assertion: z.string().min(1) });
 const registrationSchema = z.object({
   id: z.string().min(1),
-  identity: z.object({ assertion: z.string().min(1) }),
+  identity: agentIdentityAssertionSchema,
   claim: z.object({ token: z.string().min(1) }),
 });
 const tokenSchema = z.object({

package/src/agent-claim.ts

@@ -1,7 +1,15 @@
 import { z } from 'zod';
 
-import { discoverAgentAuth } from './agent-auth.js';
-import type { AgentCredentials } from './agent-credentials.js';
+import {
+  agentIdentityAssertionSchema,
+  discoverAgentAuth,
+  exchangeAgentToken,
+} from './agent-auth.js';
+import {
+  loadAgentCredentials,
+  saveAgentCredentials,
+  type AgentCredentials,
+} from './agent-credentials.js';
 import { agentRequest, agentResponse } from './agent-http.js';
 import { DASHBOARD_URL } from './constants.js';
 
@@ -37,3 +45,76 @@ export async function createAgentClaimLink(
   claimUrl.searchParams.set('token', token);
   return claimUrl.toString();
 }
+
+const completedClaimSchema = z.object({
+  identity: agentIdentityAssertionSchema,
+});
+const signupSchema = z.object({ orgId: z.string().min(1), claimed: z.literal(true) });
+
+export async function claimDeployment(
+  options: { apiUrl: string; directory: string; code?: string; email?: string },
+  warn: (message: string) => void,
+  progress: (message: string) => void = () => {}
+): Promise<string> {
+  const { apiUrl, directory } = options;
+  const code = options.code?.trim();
+  const email = options.email?.trim();
+  if ((!code && !email) || (code && email)) {
+    throw new Error(
+      'Provide either --email <email> for a claim link or --code <code> to finish the claim.'
+    );
+  }
+  let credentials = await loadAgentCredentials(apiUrl, directory);
+  if (!credentials)
+    throw new Error(
+      'No saved agent registration. Run from the directory used for mint deploy, or pass --directory.'
+    );
+  if (email && !credentials.claimVerified) {
+    progress('Creating the claim link...');
+    const link = await createAgentClaimLink(apiUrl, credentials, email);
+    return `Claim link for the user: ${link}\nAsk the user to open it, sign in, and return the displayed code. Then run mint claim --code <code> from the same directory (or repeat --directory).`;
+  }
+  const discovery = await discoverAgentAuth(apiUrl);
+  if (new URL(discovery.issuer).origin !== new URL(credentials.issuer).origin) {
+    throw new Error('Saved agent credentials belong to another issuer.');
+  }
+  const save = async (value: AgentCredentials) => {
+    try {
+      await saveAgentCredentials(apiUrl, directory, value);
+    } catch {
+      warn(
+        'Could not save claimed credentials to the keyring. Continuing for this run; a retry may not recover the completed claim.'
+      );
+    }
+  };
+  if (!credentials.claimVerified) {
+    progress('Completing the WorkOS claim...');
+    const completed = await agentResponse(
+      await agentRequest(`${discovery.agent_auth.claim_endpoint.replace(/\/$/, '')}/complete`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ claim_token: credentials.claimToken, user_code: code }),
+      }),
+      completedClaimSchema
+    );
+    credentials = {
+      ...credentials,
+      assertion: completed.identity.assertion,
+      claimVerified: true,
+      accessToken: undefined,
+      accessTokenExpiresAt: undefined,
+    };
+    await save(credentials);
+  }
+  progress('Finishing the site claim...');
+  const authenticated = await exchangeAgentToken(discovery, credentials);
+  await agentResponse(
+    await agentRequest(`${apiUrl}/api/agent/signup`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${authenticated.accessToken}` },
+    }),
+    signupSchema
+  );
+  await save(authenticated);
+  return 'Site claimed successfully. The user can now manage it in the Mintlify dashboard.';
+}

package/src/agent-credentials.ts

@@ -11,6 +11,7 @@ export const agentCredentialsSchema = z.object({
   issuer: z.url(),
   assertion: z.string().min(1),
   claimToken: z.string().min(1),
+  claimVerified: z.boolean().optional(),
   accessToken: z.string().min(1).optional(),
   accessTokenExpiresAt: z.number().optional(),
 });

package/src/cli.tsx

@@ -17,7 +17,7 @@ import { hideBin } from 'yargs/helpers';
 
 import { accessibilityCheck } from './accessibilityCheck.js';
 import { addDomain } from './addDomain.js';
-import { createAgentClaimLink } from './agent-claim.js';
+import { claimDeployment, createAgentClaimLink } from './agent-claim.js';
 import { analyticsBuilder } from './analytics/index.js';
 import { brokenLinksHandler } from './brokenLinks.js';
 import { comingSoon } from './comingSoon.js';
@@ -115,6 +115,42 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
       .middleware(checkNodeVersion)
       .middleware(suppressConsoleWarnings)
       .middleware(telemetryMiddleware)
+      .command(
+        'claim',
+        'Claim a site created with mint deploy',
+        (yargs) =>
+          yargs
+            .option('email', { type: 'string', description: 'User email for a claim link' })
+            .option('code', {
+              type: 'string',
+              description: 'Code returned by the user from the claim page',
+            })
+            .option('directory', {
+              type: 'string',
+              default: '.',
+              description: 'Original documentation directory used for mint deploy',
+            })
+            .conflicts('code', 'email')
+            .example('$0 claim --email you@example.com', 'Get a claim link for the current site')
+            .example('$0 claim --code ABCDEFGH', 'Finish the claim with the code from the user')
+            .epilog(
+              'Run from the same directory as mint deploy, or pass --directory. Ask the user to open the claim link and return the code. The CLI reads saved credentials internally; do not read or print keychain secrets. Retry the same command if Mintlify signup fails.'
+            ),
+        async (argv) => {
+          try {
+            const message = await claimDeployment(
+              { apiUrl: API_URL, directory: argv.directory, code: argv.code, email: argv.email },
+              (message) => process.stderr.write(`Warning: ${message}\n`),
+              (message) => process.stderr.write(`${message}\n`)
+            );
+            process.stdout.write(`${message}\n`);
+            await terminate(0);
+          } catch (error) {
+            process.stderr.write(`${error instanceof Error ? error.message : 'Claim failed.'}\n`);
+            await terminate(1);
+          }
+        }
+      )
       .command(
         'deploy',
         'Provision an anonymous docs site and get Git push instructions',

package/src/deploy-instructions.ts

@@ -1,4 +1,3 @@
-import { API_URL } from './constants.js';
 import type { DeployResult } from './deploy.js';
 
 export const DEPLOY_HELP = [
@@ -7,6 +6,7 @@ export const DEPLOY_HELP = [
   'Run again from the same documentation directory for the current anonymous site and a fresh write token. Use --new --subdomain <name> to create another site.',
   'Claimed sites are managed in the dashboard. Confirmed expired sites start a new anonymous registration.',
   'Pass --email to obtain a claim link for the user. If it is absent, ask the user for their email and rerun with --email from the same directory. Never invent an email address.',
+  'To claim an existing site without provisioning, run mint claim --email <email>. Show the link to the user and ask them to return the displayed code. Then run mint claim --code <code>. Use the original documentation directory for both commands, or pass --directory.',
   'The output contains a short-lived write token. Do not paste it into public logs or save it in a Git remote.',
 ].join('\n\n');
 
@@ -31,7 +31,7 @@ export function deploymentInstructions(result: DeployResult, claimUrl?: string):
       ? [
           `Claim link for the user: ${claimUrl}`,
           'Show this link to the user. Ask them to open it, sign in, and return the displayed code. Do not sign in on their behalf.',
-          `Follow the claim-completion instructions at ${API_URL}/api/agent/auth.md. This document includes the WorkOS steps and the authenticated Mintlify signup request.`,
+          'After the user returns the code, run mint claim --code <code> from the same documentation directory (or repeat --directory). The CLI completes the claim using its saved credentials.',
         ]
       : [
           'Ask the user for the email address they want to use to claim this site. Never invent an email address.',

package/src/welcome.ts

@@ -49,6 +49,7 @@ const GROUPS: CommandGroup[] = [
     title: 'Account',
     commands: [
       { name: 'login', description: 'Authenticate with Mintlify' },
+      { name: 'claim', description: 'Claim a site created with mint deploy' },
       { name: 'logout', description: 'Sign out on this device' },
       { name: 'status', description: 'View authentication status' },
     ],
@@ -65,6 +66,11 @@ const GROUPS: CommandGroup[] = [
 const EXAMPLES: CommandEntry[] = [
   { name: 'dev', description: 'Start a local preview of your site' },
   { name: 'new docs', description: 'Scaffold a new site in ./docs' },
+  {
+    name: 'claim --email you@example.com',
+    description: 'Get a claim link; use the deployment directory',
+  },
+  { name: 'claim --code <code>', description: 'Finish the claim in the same directory' },
   { name: 'validate', description: 'Validate your site before shipping' },
   { name: 'broken-links', description: 'Find broken links across your site' },
 ];