feat: agent-friendly login flow (--request / --check) (#7971)

* feat: add --request and --check flags to netlify login for agent-friendly auth

Agents can't complete the browser-based OAuth flow on their own. This adds
a non-blocking two-step flow: create a ticket with --request to get a
shareable URL, then check its status with --check to finalize login.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs sync via npm run docs

* feat: pass message to API when creating login ticket via --request

Update @netlify/api to 14.0.18 which adds support for an optional
message field on createTicket. Forward the --request <message> value
through to the API call.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: add type assertion for options.request to satisfy eslint

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: pass apiOpts and globalConfig to login helpers

Use command.netlify.apiOpts and command.netlify.globalConfig instead of
hardcoding API options and calling getGlobalConfigStore() directly, so
login --request and --check respect proxy/custom API URL settings.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: pass missing args in login-check rethrow tests

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: DavidWells <hello@davidwells.io>
Co-authored-by: Sean Roberts <sean.roberts90@gmail.com>

Author: 4 people

docs/commands/login.md

@@ -19,7 +19,10 @@ netlify login
 
 **Flags**
 
+- `check` (*string*) - Check the status of a login ticket created with --request
+- `json` (*boolean*) - Output as JSON (for use with --request or --check)
 - `new` (*boolean*) - Login to new Netlify account
+- `request` (*string*) - Create a login ticket for agent/human-in-the-loop auth
 - `debug` (*boolean*) - Print debugging information
 - `auth` (*string*) - Netlify auth token - can be used to run this command without logging in
 

package-lock.json

@@ -51,7 +51,7 @@ type Analytics = {
 inquirer.registerPrompt('autocomplete', inquirerAutocompletePrompt)
 /** Netlify CLI client id. Lives in bot@netlify.com */
 // TODO: setup client for multiple environments
-const CLIENT_ID = 'd6f37de6614df7ae58664cfca524744d73807a377f5ee71f1a254f78412e3750'
+export const CLIENT_ID = 'd6f37de6614df7ae58664cfca524744d73807a377f5ee71f1a254f78412e3750'
 
 const NANO_SECS_TO_MSECS = 1e6
 /** The fallback width for the help terminal */
@@ -175,6 +175,26 @@ export type BaseOptionValues = {
   verbose?: boolean
 }
 
+export function storeToken(
+  globalConfig: Awaited<ReturnType<typeof getGlobalConfigStore>>,
+  { userId, name, email, accessToken }: { userId: string; name?: string; email?: string; accessToken: string },
+) {
+  const userData = merge(globalConfig.get(`users.${userId}`), {
+    id: userId,
+    name,
+    email,
+    auth: {
+      token: accessToken,
+      github: {
+        user: undefined,
+        token: undefined,
+      },
+    },
+  })
+  globalConfig.set('userId', userId)
+  globalConfig.set(`users.${userId}`, userData)
+}
+
 /** Base command class that provides tracking and config initialization */
 export default class BaseCommand extends Command {
   /** The netlify object inside each command with the state */
@@ -441,30 +461,21 @@ export default class BaseCommand extends Command {
 
     log(`Opening ${authLink}`)
     await openBrowser({ url: authLink })
+    log()
+    log(`To request authorization from a human, run: ${chalk.cyanBright('netlify login --request "<msg>"')}`)
+    log()
 
     const accessToken = await pollForToken({
       api: this.netlify.api,
       ticket,
     })
 
     const { email, full_name: name, id: userId } = await this.netlify.api.getCurrentUser()
+    if (!userId) {
+      return logAndThrowError('Could not retrieve user ID from Netlify API')
+    }
 
-    const userData = merge(this.netlify.globalConfig.get(`users.${userId}`), {
-      id: userId,
-      name,
-      email,
-      auth: {
-        token: accessToken,
-        github: {
-          user: undefined,
-          token: undefined,
-        },
-      },
-    })
-    // Set current userId
-    this.netlify.globalConfig.set('userId', userId)
-    // Set user data
-    this.netlify.globalConfig.set(`users.${userId}`, userData)
+    storeToken(this.netlify.globalConfig, { userId, name, email, accessToken })
 
     await identify({
       name,

src/commands/base-command.ts

@@ -11,6 +11,9 @@ export const createLoginCommand = (program: BaseCommand) =>
 Opens a web browser to acquire an OAuth token.`,
     )
     .option('--new', 'Login to new Netlify account')
+    .option('--request <message>', 'Create a login ticket for agent/human-in-the-loop auth')
+    .option('--check <ticket-id>', 'Check the status of a login ticket created with --request')
+    .option('--json', 'Output as JSON (for use with --request or --check)')
     .addHelpText('after', () => {
       const docsUrl = 'https://docs.netlify.com/cli/get-started/#authentication'
       return `

src/commands/login/index.ts

@@ -0,0 +1,63 @@
+import { NetlifyAPI } from '@netlify/api'
+import { OptionValues } from 'commander'
+
+import { log, logAndThrowError, logJson } from '../../utils/command-helpers.js'
+import { storeToken } from '../base-command.js'
+import type { NetlifyOptions } from '../types.js'
+
+export const loginCheck = async (
+  options: OptionValues,
+  apiOpts: NetlifyOptions['apiOpts'],
+  globalConfig: NetlifyOptions['globalConfig'],
+) => {
+  const ticketId = options.check as string
+
+  const api = new NetlifyAPI('', apiOpts)
+
+  let ticket: { authorized?: boolean }
+  try {
+    ticket = await api.showTicket({ ticketId })
+  } catch (error) {
+    const status = (error as { status?: number }).status
+    if (status === 401 || status === 404) {
+      logJson({ status: 'denied' })
+      log('Status: denied')
+      return
+    }
+    throw error
+  }
+
+  if (!ticket.authorized) {
+    logJson({ status: 'pending' })
+    log('Status: pending')
+    return
+  }
+
+  const tokenResponse = await api.exchangeTicket({ ticketId })
+  const accessToken = tokenResponse.access_token
+  if (!accessToken) {
+    return logAndThrowError('Could not retrieve access token')
+  }
+
+  api.accessToken = accessToken
+  const user = await api.getCurrentUser()
+  if (!user.id) {
+    return logAndThrowError('Could not retrieve user ID from Netlify API')
+  }
+
+  storeToken(globalConfig, {
+    userId: user.id,
+    name: user.full_name,
+    email: user.email,
+    accessToken,
+  })
+
+  logJson({
+    status: 'authorized',
+    user: { id: user.id, email: user.email, name: user.full_name },
+  })
+
+  log('Status: authorized')
+  log(`Name: ${user.full_name ?? ''}`)
+  log(`Email: ${user.email ?? ''}`)
+}

src/commands/login/login-check.ts

@@ -0,0 +1,26 @@
+import { NetlifyAPI } from '@netlify/api'
+
+import { log, logAndThrowError, logJson } from '../../utils/command-helpers.js'
+import { CLIENT_ID } from '../base-command.js'
+import type { NetlifyOptions } from '../types.js'
+
+export const loginRequest = async (message: string, apiOpts: NetlifyOptions['apiOpts']) => {
+  const webUI = process.env.NETLIFY_WEB_UI || 'https://app.netlify.com'
+
+  const api = new NetlifyAPI('', apiOpts)
+
+  const ticket = await api.createTicket({ clientId: CLIENT_ID, body: { message } })
+
+  if (!ticket.id) {
+    return logAndThrowError('Failed to create login ticket')
+  }
+  const ticketId = ticket.id
+  const url = `${webUI}/authorize?response_type=ticket&ticket=${ticketId}`
+
+  logJson({ ticket_id: ticketId, url, check_command: `netlify login --check ${ticketId}` })
+
+  log(`Ticket ID: ${ticketId}`)
+  log(`Authorize URL: ${url}`)
+  log()
+  log(`After authorizing, run: netlify login --check ${ticketId}`)
+}