@mintlify/cli 4.0.1701 → 4.0.1703

package/bin/welcome.js

@@ -7,6 +7,10 @@ const GROUPS = [
         commands: [
             { name: 'dev', description: 'Start a local preview of your site' },
             { name: 'new', description: 'Scaffold a new documentation site' },
+            {
+                name: 'deploy',
+                description: 'Provision a docs site without login; get Git push instructions',
+            },
         ],
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1701",
+  "version": "4.0.1703",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -45,12 +45,12 @@
   },
   "dependencies": {
     "@inquirer/prompts": "7.9.0",
-    "@mintlify/common": "1.0.1290",
-    "@mintlify/link-rot": "3.0.1514",
+    "@mintlify/common": "1.0.1291",
+    "@mintlify/link-rot": "3.0.1515",
     "@mintlify/models": "0.0.377",
-    "@mintlify/og": "0.0.88",
-    "@mintlify/prebuild": "1.0.1455",
-    "@mintlify/previewing": "4.0.1533",
+    "@mintlify/og": "0.0.89",
+    "@mintlify/prebuild": "1.0.1456",
+    "@mintlify/previewing": "4.0.1534",
     "@mintlify/validation": "0.1.939",
     "adm-zip": "0.6.0",
     "chalk": "5.2.0",
@@ -82,7 +82,7 @@
     "keytar": "7.9.0"
   },
   "devDependencies": {
-    "@mintlify/editor": "0.0.553",
+    "@mintlify/editor": "0.0.554",
     "@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": "0873aa5354dd9084254ffa50e997d84966aa1d65"
+  "gitHead": "56ea8d8eb5516d26960a41d5aef1b63eea741717"
 }

package/src/agent-auth.ts

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+
+import type { AgentCredentials } from './agent-credentials.js';
+import { agentRequest, agentResponse } from './agent-http.js';
+
+const resourceSchema = z.object({ authorization_servers: z.array(z.url()).min(1) });
+const discoverySchema = z.object({
+  issuer: z.url(),
+  token_endpoint: z.url(),
+  agent_auth: z.object({
+    identity_endpoint: z.url(),
+    claim_endpoint: z.url(),
+    identity_types_supported: z.array(z.string()),
+  }),
+});
+const registrationSchema = z.object({
+  id: z.string().min(1),
+  identity: z.object({ assertion: z.string().min(1) }),
+  claim: z.object({ token: z.string().min(1) }),
+});
+const tokenSchema = z.object({
+  access_token: z.string().min(1),
+  expires_in: z.number().positive(),
+  token_type: z.string().regex(/^bearer$/i),
+});
+const identitySchema = z.discriminatedUnion('identityType', [
+  z.object({ registrationId: z.string(), identityType: z.literal('anonymous') }),
+  z.object({
+    registrationId: z.string(),
+    identityType: z.literal('user_bound'),
+    userId: z.string(),
+    orgId: z.string(),
+  }),
+]);
+
+export type AgentDiscovery = z.infer<typeof discoverySchema>;
+
+export async function discoverAgentAuth(apiUrl: string): Promise<AgentDiscovery> {
+  const resource = await agentResponse(
+    await agentRequest(`${apiUrl}/api/agent/.well-known/oauth-protected-resource`),
+    resourceSchema
+  );
+  const issuer = resource.authorization_servers[0];
+  if (!issuer || new URL(issuer).protocol !== 'https:')
+    throw new Error('Agent authentication requires an HTTPS issuer.');
+  const discovery = await agentResponse(
+    await agentRequest(`${issuer.replace(/\/$/, '')}/.well-known/oauth-authorization-server`),
+    discoverySchema
+  );
+  const origin = new URL(issuer).origin;
+  if (
+    [
+      discovery.issuer,
+      discovery.token_endpoint,
+      discovery.agent_auth.identity_endpoint,
+      discovery.agent_auth.claim_endpoint,
+    ].some((url) => new URL(url).origin !== origin)
+  ) {
+    throw new Error('Agent authentication endpoints do not match the configured issuer.');
+  }
+  return discovery;
+}
+
+export async function registerAgent(discovery: AgentDiscovery): Promise<AgentCredentials> {
+  if (!discovery.agent_auth.identity_types_supported.includes('anonymous')) {
+    throw new Error('Anonymous registration is not enabled for this environment.');
+  }
+  const result = await agentResponse(
+    await agentRequest(discovery.agent_auth.identity_endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ type: 'anonymous' }),
+    }),
+    registrationSchema
+  );
+  return {
+    registrationId: result.id,
+    issuer: discovery.issuer,
+    assertion: result.identity.assertion,
+    claimToken: result.claim.token,
+  };
+}
+
+export async function exchangeAgentToken(
+  discovery: AgentDiscovery,
+  credentials: AgentCredentials
+): Promise<AgentCredentials & { accessToken: string }> {
+  if (new URL(credentials.issuer).origin !== new URL(discovery.issuer).origin) {
+    throw new Error('Saved agent credentials belong to another issuer.');
+  }
+  if (credentials.accessToken && (credentials.accessTokenExpiresAt ?? 0) > Date.now() + 30_000) {
+    return { ...credentials, accessToken: credentials.accessToken };
+  }
+  const token = await agentResponse(
+    await agentRequest(discovery.token_endpoint, {
+      method: 'POST',
+      body: new URLSearchParams({
+        grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+        assertion: credentials.assertion,
+      }),
+    }),
+    tokenSchema
+  );
+  return {
+    ...credentials,
+    accessToken: token.access_token,
+    accessTokenExpiresAt: Date.now() + token.expires_in * 1000,
+  };
+}
+
+export async function getAgentIdentity(apiUrl: string, accessToken: string) {
+  return agentResponse(
+    await agentRequest(`${apiUrl}/api/agent/identity`, {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    }),
+    identitySchema
+  );
+}

package/src/agent-claim.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+
+import { discoverAgentAuth } from './agent-auth.js';
+import type { AgentCredentials } from './agent-credentials.js';
+import { agentRequest, agentResponse } from './agent-http.js';
+import { DASHBOARD_URL } from './constants.js';
+
+const claimAttemptSchema = z.object({ attempt: z.object({ verification_uri: z.url() }) });
+
+export async function createAgentClaimLink(
+  apiUrl: string,
+  credentials: AgentCredentials,
+  email: string
+): Promise<string> {
+  const loginHint = z.email().parse(email);
+  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 claim = await agentResponse(
+    await agentRequest(discovery.agent_auth.claim_endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        type: 'service_auth',
+        claim_token: credentials.claimToken,
+        login_hint: loginHint,
+      }),
+    }),
+    claimAttemptSchema
+  );
+  const token = z
+    .string()
+    .min(1)
+    .parse(new URL(claim.attempt.verification_uri).searchParams.get('token'));
+  const claimUrl = new URL('/agent-claim', DASHBOARD_URL);
+  claimUrl.searchParams.set('token', token);
+  return claimUrl.toString();
+}

package/src/agent-credentials.ts

@@ -0,0 +1,60 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { z } from 'zod';
+
+import { getKeytar } from './keyring.js';
+
+const service = 'mintlify-agent';
+
+export const agentCredentialsSchema = z.object({
+  registrationId: z.string().min(1),
+  issuer: z.url(),
+  assertion: z.string().min(1),
+  claimToken: z.string().min(1),
+  accessToken: z.string().min(1).optional(),
+  accessTokenExpiresAt: z.number().optional(),
+});
+
+export type AgentCredentials = z.infer<typeof agentCredentialsSchema>;
+
+function projectAccount(apiUrl: string, directory: string): string {
+  return `project:${createHash('sha256')
+    .update(JSON.stringify([new URL(apiUrl).origin, path.resolve(directory)]))
+    .digest('hex')}`;
+}
+
+function registrationAccount(apiUrl: string, registrationId: string): string {
+  return `${new URL(apiUrl).origin}:${registrationId}`;
+}
+
+export async function loadAgentCredentials(
+  apiUrl: string,
+  directory: string
+): Promise<AgentCredentials | null> {
+  const keytar = await getKeytar();
+  const registrationId = await keytar.getPassword(service, projectAccount(apiUrl, directory));
+  if (!registrationId) return null;
+  const value = await keytar.getPassword(service, registrationAccount(apiUrl, registrationId));
+  if (!value)
+    throw new Error('Saved agent credentials are missing. Use --new to create another site.');
+  const credentials = agentCredentialsSchema.parse(JSON.parse(value));
+  if (credentials.registrationId !== registrationId) {
+    throw new Error('Saved agent credentials do not match this project.');
+  }
+  return credentials;
+}
+
+export async function saveAgentCredentials(
+  apiUrl: string,
+  directory: string,
+  credentials: AgentCredentials
+): Promise<void> {
+  const value = agentCredentialsSchema.parse(credentials);
+  const keytar = await getKeytar();
+  await keytar.setPassword(
+    service,
+    registrationAccount(apiUrl, value.registrationId),
+    JSON.stringify(value)
+  );
+  await keytar.setPassword(service, projectAccount(apiUrl, directory), value.registrationId);
+}

package/src/agent-deployment.ts

@@ -0,0 +1,75 @@
+import { setTimeout } from 'node:timers/promises';
+import { z } from 'zod';
+
+import { agentRequest, agentResponse } from './agent-http.js';
+
+const readySchema = z.object({
+  status: z.literal('ready'),
+  deploymentId: z.string().min(1),
+  subdomain: z.string().min(1),
+  remote: z.url(),
+  branch: z.literal('main'),
+  expiresAt: z.iso.datetime(),
+});
+const existingSchema = z.discriminatedUnion('status', [
+  readySchema.extend({ code: z.literal('deployment_already_exists') }),
+  z.object({
+    status: z.literal('provisioning'),
+    code: z.literal('deployment_already_exists'),
+    deploymentId: z.string().optional(),
+    subdomain: z.string().optional(),
+  }),
+  z.object({
+    status: z.literal('expired'),
+    code: z.literal('deployment_already_exists'),
+    deploymentId: z.string(),
+    subdomain: z.string(),
+    expiresAt: z.iso.datetime().optional(),
+  }),
+]);
+const writeTokenSchema = z.object({
+  remote: z.url(),
+  branch: z.literal('main'),
+  token: z.string().min(1),
+  tokenExpiresAt: z.iso.datetime(),
+});
+
+export type AgentSite = z.infer<typeof readySchema>;
+export type AgentWriteToken = z.infer<typeof writeTokenSchema>;
+export type AgentSiteSettings = { subdomain: string; orgName?: string };
+
+export async function provisionAgentSite(
+  apiUrl: string,
+  accessToken: string,
+  settings: AgentSiteSettings
+) {
+  for (let attempt = 0; attempt < 4; attempt++) {
+    const response = await agentRequest(`${apiUrl}/api/agent/deployments/provision`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ ...settings, docsPath: '' }),
+    });
+    if (response.status !== 409) {
+      return { ...(await agentResponse(response, readySchema)), created: true };
+    }
+    const body: unknown = await response.json().catch(() => null);
+    const parsed = existingSchema.safeParse(body);
+    if (!parsed.success) throw new Error('The deployment service returned an unexpected response.');
+    if (parsed.data.status !== 'provisioning') return { ...parsed.data, created: false };
+    if (attempt < 3) await setTimeout(1000 * (attempt + 1));
+  }
+  throw new Error('Your site is still provisioning. Run the same command again.');
+}
+
+export async function getAgentWriteToken(
+  apiUrl: string,
+  accessToken: string
+): Promise<AgentWriteToken> {
+  return agentResponse(
+    await agentRequest(`${apiUrl}/api/agent/deployments/token`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${accessToken}` },
+    }),
+    writeTokenSchema
+  );
+}

package/src/agent-http.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+
+const errorSchema = z.object({ code: z.string().optional(), error: z.string().optional() });
+
+export class AgentApiError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly code?: string
+  ) {
+    super(`Agent request failed (HTTP ${status}).${code ? ` Code: ${code}.` : ''}`);
+  }
+}
+
+export async function agentRequest(url: string, init?: RequestInit): Promise<Response> {
+  try {
+    const timeout = AbortSignal.timeout(30_000);
+    const signal = init?.signal ? AbortSignal.any([init.signal, timeout]) : timeout;
+    return await fetch(url, { ...init, redirect: 'error', signal });
+  } catch {
+    throw new Error('Could not reach the agent service. Retry the same command.');
+  }
+}
+
+export async function agentResponse<T>(response: Response, schema: z.ZodType<T>): Promise<T> {
+  const body: unknown = await response.json().catch(() => null);
+  if (!response.ok) {
+    const error = errorSchema.safeParse(body);
+    const code = error.success ? (error.data.code ?? error.data.error) : undefined;
+    throw new AgentApiError(response.status, code?.match(/^[a-z_]{1,80}$/)?.[0]);
+  }
+  const parsed = schema.safeParse(body);
+  if (!parsed.success) throw new Error('The agent service returned an unexpected response.');
+  return parsed.data;
+}

package/src/cli.tsx

@@ -21,11 +21,14 @@ import { hideBin } from 'yargs/helpers';
 
 import { accessibilityCheck } from './accessibilityCheck.js';
 import { addDomain } from './addDomain.js';
+import { createAgentClaimLink } from './agent-claim.js';
 import { analyticsBuilder } from './analytics/index.js';
 import { comingSoon } from './comingSoon.js';
 import { setTelemetryEnabled } from './config.js';
 import { getConfigValue, setConfigValue, clearConfigValue } from './config.js';
 import { API_URL } from './constants.js';
+import { DEPLOY_HELP, deploymentInstructions } from './deploy-instructions.js';
+import { formatDeployment, prepareAgentDeployment } from './deploy.js';
 import { formatHandler } from './format.js';
 import {
   CMD_EXEC_PATH,
@@ -117,6 +120,74 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
       .middleware(checkNodeVersion)
       .middleware(suppressConsoleWarnings)
       .middleware(telemetryMiddleware)
+      .command(
+        'deploy',
+        'Provision an anonymous docs site and get Git push instructions',
+        (yargs) =>
+          yargs
+            .option('subdomain', {
+              type: 'string',
+              description: 'Requested site name; required for the first deployment or --new',
+            })
+            .option('org-name', { type: 'string', description: 'Organization display name' })
+            .option('directory', {
+              type: 'string',
+              default: '.',
+              description: 'Documentation directory associated with this site',
+            })
+            .option('new', {
+              type: 'boolean',
+              default: false,
+              description: 'Create a new registration and site',
+            })
+            .option('email', {
+              type: 'string',
+              description: 'User email for an optional claim link',
+            })
+            .example('$0 deploy --subdomain my-docs', 'Provision a site without signing in')
+            .example(
+              '$0 deploy --email you@example.com',
+              'Get repository access and a claim link for the current site'
+            )
+            .example('$0 deploy --new --subdomain another-site', 'Create another anonymous site')
+            .epilog(DEPLOY_HELP),
+        async (argv) => {
+          try {
+            const result = await prepareAgentDeployment(
+              {
+                apiUrl: API_URL,
+                directory: argv.directory,
+                subdomain: argv.subdomain,
+                orgName: argv.orgName,
+                newSite: argv.new,
+              },
+              (message) => {
+                process.stderr.write(`Warning: ${message}\n`);
+              },
+              (message) => process.stderr.write(`${message}\n`)
+            );
+            process.stdout.write(`${formatDeployment(result, API_URL)}\n`);
+            let claimUrl: string | undefined;
+            if (argv.email && result.status === 'ready') {
+              try {
+                process.stderr.write('Creating the claim link...\n');
+                claimUrl = await createAgentClaimLink(API_URL, result.credentials, argv.email);
+              } catch {
+                process.stderr.write(
+                  'Warning: Could not create the claim link. Your site is provisioned; retry with --email later.\n'
+                );
+              }
+            }
+            process.stdout.write(`${deploymentInstructions(result, claimUrl)}\n`);
+            await terminate(0);
+          } catch (error) {
+            process.stderr.write(
+              `${error instanceof Error ? error.message : 'Deployment failed.'}\n`
+            );
+            await terminate(1);
+          }
+        }
+      )
       .command(
         'dev',
         'Initialize a local preview environment',

package/src/config.ts

@@ -1,5 +1,6 @@
 import fs from 'fs';
 import { ensureDir } from 'fs-extra';
+import { z } from 'zod';
 
 import { CLI_CONFIG_FILE, CONFIG_DIR } from './constants.js';
 
@@ -9,6 +10,21 @@ interface MintlifyConfig {
   dateFrom?: string;
   dateTo?: string;
   publishPromptShown?: string[];
+  agentSites?: Record<string, { registrationId: string; subdomain: string }>;
+}
+
+const agentSiteMetadataSchema = z.object({ registrationId: z.string(), subdomain: z.string() });
+
+export function getAgentSiteMetadata(key: string) {
+  const parsed = agentSiteMetadataSchema.safeParse(readConfig().agentSites?.[key]);
+  return parsed.success ? parsed.data : undefined;
+}
+
+export async function setAgentSiteMetadata(
+  key: string,
+  site: z.infer<typeof agentSiteMetadataSchema>
+) {
+  await writeConfig({ agentSites: { ...readConfig().agentSites, [key]: site } });
 }
 
 function readConfig(): MintlifyConfig {

package/src/deploy-instructions.ts

@@ -0,0 +1,41 @@
+import { API_URL } from './constants.js';
+import type { DeployResult } from './deploy.js';
+
+export const DEPLOY_HELP = [
+  'No login is required. This command provisions a temporary site and returns repository access. Commit and push the documentation yourself; the CLI does not upload files.',
+  'Run from your documentation directory, or pass --directory. Put docs.json, pages, and assets at the hosted repository root.',
+  '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.',
+  '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');
+
+export function deploymentInstructions(result: DeployResult, claimUrl?: string): string {
+  if (result.status !== 'ready') return '';
+  return [
+    '\nNext steps:',
+    '1. Clone the hosted repository into a separate directory. Do not replace the user’s existing Git remote.',
+    '2. Copy the selected documentation into its root, including docs.json, .md/.mdx pages, images, and other required assets. Exclude credentials, .env files, node_modules, and .git.',
+    '3. Commit the documentation. For subsequent updates, fetch the hosted main branch and commit on top of it. Do not force-push.',
+    '4. Push to main. Supply the write token as an HTTP Authorization: Bearer header for this Git operation only; never embed it in the remote URL or persist it in Git config.',
+    '5. If the write token expires, run mint deploy again from the same documentation directory to obtain a fresh token.',
+    'A successful push starts the normal build. Provisioning and Git success do not confirm build success.',
+    '',
+    'Git examples (POSIX shell): set REPOSITORY_URL and WRITE_TOKEN from the output above. Set CHECKOUT_DIR to a new directory outside the source documentation directory. Keep the token private and do not enable shell tracing.',
+    'GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0="http.${REPOSITORY_URL}.extraHeader" GIT_CONFIG_VALUE_0="Authorization: Bearer ${WRITE_TOKEN}" git clone "$REPOSITORY_URL" "$CHECKOUT_DIR"',
+    'After copying and committing the documentation:',
+    'GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0="http.${REPOSITORY_URL}.extraHeader" GIT_CONFIG_VALUE_0="Authorization: Bearer ${WRITE_TOKEN}" git -C "$CHECKOUT_DIR" push origin HEAD:main',
+    'These settings apply only to that Git process. Use the same authentication settings for later fetches.',
+    '',
+    ...(claimUrl
+      ? [
+          `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.`,
+        ]
+      : [
+          'Ask the user for the email address they want to use to claim this site. Never invent an email address.',
+          'After they provide it, run mint deploy --email <their-email> from the same documentation directory (or repeat --directory). This reuses the site and returns its claim link.',
+        ]),
+  ].join('\n');
+}

package/src/deploy.ts

@@ -0,0 +1,130 @@
+import path from 'node:path';
+
+import {
+  discoverAgentAuth,
+  exchangeAgentToken,
+  getAgentIdentity,
+  registerAgent,
+} from './agent-auth.js';
+import {
+  loadAgentCredentials,
+  saveAgentCredentials,
+  type AgentCredentials,
+} from './agent-credentials.js';
+import {
+  getAgentWriteToken,
+  provisionAgentSite,
+  type AgentSite,
+  type AgentWriteToken,
+} from './agent-deployment.js';
+import { getAgentSiteMetadata, setAgentSiteMetadata } from './config.js';
+
+export type DeployOptions = {
+  apiUrl: string;
+  directory: string;
+  subdomain?: string;
+  orgName?: string;
+  newSite?: boolean;
+};
+
+export type DeployResult =
+  | { status: 'claimed' }
+  | {
+      status: 'ready';
+      site: AgentSite;
+      write: AgentWriteToken;
+      created: boolean;
+      credentials: AgentCredentials;
+    };
+
+export async function prepareAgentDeployment(
+  options: DeployOptions,
+  warn: (message: string) => void,
+  progress: (message: string) => void = () => {}
+): Promise<DeployResult> {
+  const { apiUrl } = options;
+  const directory = path.resolve(options.directory);
+  const metadataKey = JSON.stringify([new URL(apiUrl).origin, directory]);
+  const previous = getAgentSiteMetadata(metadataKey);
+  progress('Authenticating agent...');
+  let saved = options.newSite
+    ? null
+    : await loadAgentCredentials(apiUrl, directory).catch(() => {
+        if (previous)
+          throw new Error(
+            'Could not read this site’s saved credentials. Unlock your keyring or use --new for another site.'
+          );
+        warn('Could not read the keyring. Continuing with a new registration for this run.');
+        return null;
+      });
+  const subdomain = options.subdomain ?? (options.newSite ? undefined : previous?.subdomain);
+  if (!subdomain) throw new Error('Choose a site name with --subdomain <name>.');
+  const discovery = await discoverAgentAuth(apiUrl);
+
+  const save = async (credentials: AgentCredentials) => {
+    try {
+      await saveAgentCredentials(apiUrl, directory, credentials);
+    } catch {
+      warn(
+        'Could not save agent credentials to the keyring. Continuing for this run; later commands may not recover access.'
+      );
+    }
+  };
+
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const credentials = saved ?? (await registerAgent(discovery));
+    await save(credentials);
+    const authenticated = await exchangeAgentToken(discovery, credentials);
+    await save(authenticated);
+    const identity = await getAgentIdentity(apiUrl, authenticated.accessToken);
+    if (identity.registrationId !== credentials.registrationId)
+      throw new Error('Agent identity does not match the saved registration.');
+    if (identity.identityType === 'user_bound') return { status: 'claimed' };
+    progress('Provisioning the site and repository...');
+    const site = await provisionAgentSite(apiUrl, authenticated.accessToken, {
+      subdomain,
+      orgName: options.orgName,
+    });
+    if (site.status === 'expired') {
+      warn('The previous anonymous site expired. Creating a new registration and site.');
+      saved = null;
+      continue;
+    }
+    await setAgentSiteMetadata(metadataKey, {
+      registrationId: credentials.registrationId,
+      subdomain: site.subdomain,
+    }).catch(() =>
+      warn('Could not save the site name locally. Provide --subdomain on your next invocation.')
+    );
+    progress('Getting repository write access...');
+    const write = await getAgentWriteToken(apiUrl, authenticated.accessToken);
+    if (write.remote !== site.remote)
+      throw new Error('Repository credentials do not match the provisioned site.');
+    return { status: 'ready', site, write, created: site.created, credentials: authenticated };
+  }
+  throw new Error('The new anonymous site is already expired. Please retry later.');
+}
+
+export function formatDeployment(result: DeployResult, apiUrl: string): string {
+  if (result.status === 'claimed')
+    return 'This site has been claimed. Manage it in the Mintlify dashboard. Use mint deploy --new --subdomain <name> to create another site.';
+  const { site, write } = result;
+  const domain =
+    new URL(apiUrl).hostname === 'leaves-dev.mintlify.com'
+      ? 'mint-dev.mintlify.me'
+      : 'mintlify.site';
+  const siteUrl = new URL(`https://${site.subdomain}.${domain}`).toString();
+  return [
+    result.created
+      ? 'Repository provisioned; push required to build the site.'
+      : 'Using the existing anonymous repository; push any changes to build the site.',
+    `Site: ${siteUrl}`,
+    `Expires: ${site.expiresAt}`,
+    `Repository: ${site.remote}`,
+    `Branch: ${site.branch}`,
+    `Write token: ${write.token}`,
+    `Write token expires: ${write.tokenExpiresAt}`,
+    'Commit and push your documentation to this repository to start the build.',
+    'The site link becomes available after the push and build complete.',
+  ].join('\n');
+}