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

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
 

src/commands/base-command.ts

@@ -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/login/index.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/login-check.ts

@@ -0,0 +1,56 @@
+import { NetlifyAPI } from '@netlify/api'
+import { getGlobalConfigStore } from '@netlify/dev-utils'
+import { OptionValues } from 'commander'
+
+import { log, logAndThrowError, logJson, USER_AGENT } from '../../utils/command-helpers.js'
+import { storeToken } from '../base-command.js'
+
+export const loginCheck = async (options: OptionValues) => {
+  const ticketId = options.check as string
+
+  const api = new NetlifyAPI('', { userAgent: USER_AGENT })
+
+  let ticket: { authorized?: boolean }
+  try {
+    ticket = await api.showTicket({ ticketId })
+  } catch {
+    logJson({ status: 'denied' })
+    log('Status: denied')
+    return
+  }
+
+  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')
+  }
+
+  const globalConfig = await getGlobalConfigStore()
+  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-request.ts

@@ -0,0 +1,25 @@
+import { NetlifyAPI } from '@netlify/api'
+
+import { log, logAndThrowError, logJson, USER_AGENT } from '../../utils/command-helpers.js'
+import { CLIENT_ID } from '../base-command.js'
+
+export const loginRequest = async () => {
+  const webUI = process.env.NETLIFY_WEB_UI || 'https://app.netlify.com'
+
+  const api = new NetlifyAPI('', { userAgent: USER_AGENT })
+
+  const ticket = await api.createTicket({ clientId: CLIENT_ID })
+
+  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}`)
+}

src/commands/login/login.ts

@@ -1,6 +1,6 @@
 import { OptionValues } from 'commander'
 
-import { chalk, exit, getToken, log } from '../../utils/command-helpers.js'
+import { chalk, exit, getToken, log, logAndThrowError } from '../../utils/command-helpers.js'
 import { TokenLocation } from '../../utils/types.js'
 import BaseCommand from '../base-command.js'
 
@@ -18,6 +18,22 @@ const msg = function (location: TokenLocation) {
 }
 
 export const login = async (options: OptionValues, command: BaseCommand) => {
+  if (options.request && options.check) {
+    return logAndThrowError('`--request` and `--check` are mutually exclusive')
+  }
+
+  if (options.request) {
+    const { loginRequest } = await import('./login-request.js')
+    await loginRequest()
+    return
+  }
+
+  if (options.check) {
+    const { loginCheck } = await import('./login-check.js')
+    await loginCheck(options)
+    return
+  }
+
   const [accessToken, location] = await getToken()
 
   command.setAnalyticsPayload({ new: options.new })

src/commands/main.ts

@@ -255,7 +255,10 @@ export const createMainCommand = (): BaseCommand => {
       const cliDocsEntrypointUrl = 'https://developers.netlify.com/cli'
       const docsUrl = 'https://docs.netlify.com'
       const bugsUrl = pkg.bugs?.url ?? ''
-      return `→ For more help with the CLI, visit ${NETLIFY_CYAN(
+      return `To get started run: ${NETLIFY_CYAN('netlify login')}
+To ask a human for credentials: ${NETLIFY_CYAN('netlify login --request <msg>')}
+
+→ For more help with the CLI, visit ${NETLIFY_CYAN(
         terminalLink(cliDocsEntrypointUrl, cliDocsEntrypointUrl, { fallback: false }),
       )}
 → For help with Netlify, visit ${NETLIFY_CYAN(terminalLink(docsUrl, docsUrl, { fallback: false }))}

tests/integration/commands/help/__snapshots__/help.test.ts.snap

@@ -41,6 +41,9 @@ COMMANDS
   $ unlink       Unlink a local folder from a Netlify project
   $ watch        Watch for project deploy to finish
 
+To get started run: netlify login
+To ask a human for credentials: netlify login --request <msg>
+
 → For more help with the CLI, visit https://developers.netlify.com/cli
 → For help with Netlify, visit https://docs.netlify.com
 → To report a CLI bug, visit https://github.com/netlify/cli/issues"

tests/unit/commands/login/login-check.test.ts

@@ -0,0 +1,92 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  showTicket: vi.fn(),
+  exchangeTicket: vi.fn(),
+  getCurrentUser: vi.fn(),
+  globalConfigGet: vi.fn().mockReturnValue({}),
+  globalConfigSet: vi.fn(),
+}))
+
+vi.mock('@netlify/api', () => ({
+  NetlifyAPI: vi.fn().mockImplementation(() => ({
+    showTicket: mocks.showTicket,
+    exchangeTicket: mocks.exchangeTicket,
+    getCurrentUser: mocks.getCurrentUser,
+    set accessToken(_val: string) {
+      // no-op for test
+    },
+  })),
+}))
+
+vi.mock('@netlify/dev-utils', () => ({
+  getGlobalConfigStore: vi.fn().mockResolvedValue({
+    get: mocks.globalConfigGet,
+    set: mocks.globalConfigSet,
+  }),
+}))
+
+import { loginCheck } from '../../../../src/commands/login/login-check.js'
+
+describe('loginCheck', () => {
+  let stdoutOutput: string[]
+  const originalWrite = process.stdout.write.bind(process.stdout)
+
+  beforeEach(() => {
+    stdoutOutput = []
+    process.stdout.write = vi.fn((chunk: string) => {
+      stdoutOutput.push(chunk)
+      return true
+    }) as typeof process.stdout.write
+  })
+
+  afterEach(() => {
+    process.stdout.write = originalWrite
+  })
+
+  test('outputs pending when ticket is not authorized', async () => {
+    mocks.showTicket.mockResolvedValue({ authorized: false })
+
+    await loginCheck({ check: 'ticket-abc' })
+
+    const output = stdoutOutput.join('')
+    expect(output).toContain('Status: pending')
+  })
+
+  test('outputs denied when showTicket throws', async () => {
+    mocks.showTicket.mockRejectedValue(new Error('Not found'))
+
+    await loginCheck({ check: 'ticket-bad' })
+
+    const output = stdoutOutput.join('')
+    expect(output).toContain('Status: denied')
+  })
+
+  test('outputs authorized and stores token when ticket is authorized', async () => {
+    mocks.showTicket.mockResolvedValue({ authorized: true })
+    mocks.exchangeTicket.mockResolvedValue({ access_token: 'test-token-xyz' })
+    mocks.getCurrentUser.mockResolvedValue({
+      id: 'user-1',
+      email: 'test@example.com',
+      full_name: 'Test User',
+    })
+
+    await loginCheck({ check: 'ticket-ok' })
+
+    const output = stdoutOutput.join('')
+    expect(output).toContain('Status: authorized')
+    expect(output).toContain('Name: Test User')
+    expect(output).toContain('Email: test@example.com')
+
+    expect(mocks.globalConfigSet).toHaveBeenCalledWith('userId', 'user-1')
+    expect(mocks.globalConfigSet).toHaveBeenCalledWith(
+      'users.user-1',
+      expect.objectContaining({
+        id: 'user-1',
+        email: 'test@example.com',
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        auth: expect.objectContaining({ token: 'test-token-xyz' }),
+      }),
+    )
+  })
+})

tests/unit/commands/login/login-request.test.ts

@@ -0,0 +1,52 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  createTicket: vi.fn().mockResolvedValue({ id: 'test-ticket-123' }),
+}))
+
+vi.mock('@netlify/api', () => ({
+  NetlifyAPI: vi.fn().mockImplementation(() => ({
+    createTicket: mocks.createTicket,
+  })),
+}))
+
+import { loginRequest } from '../../../../src/commands/login/login-request.js'
+
+describe('loginRequest', () => {
+  let stdoutOutput: string[]
+  const originalEnv = { ...process.env }
+  const originalWrite = process.stdout.write.bind(process.stdout)
+
+  beforeEach(() => {
+    stdoutOutput = []
+    process.stdout.write = vi.fn((chunk: string) => {
+      stdoutOutput.push(chunk)
+      return true
+    }) as typeof process.stdout.write
+  })
+
+  afterEach(() => {
+    process.env = { ...originalEnv }
+    process.stdout.write = originalWrite
+  })
+
+  test('outputs ticket info as plain text', async () => {
+    await loginRequest()
+
+    const output = stdoutOutput.join('')
+    expect(output).toContain('Ticket ID: test-ticket-123')
+    expect(output).toContain(
+      'Authorize URL: https://app.netlify.com/authorize?response_type=ticket&ticket=test-ticket-123',
+    )
+    expect(output).toContain('netlify login --check test-ticket-123')
+  })
+
+  test('uses custom NETLIFY_WEB_UI when set', async () => {
+    process.env.NETLIFY_WEB_UI = 'https://custom.netlify.com'
+
+    await loginRequest()
+
+    const output = stdoutOutput.join('')
+    expect(output).toContain('https://custom.netlify.com/authorize?response_type=ticket&ticket=test-ticket-123')
+  })
+})