@fleetkeep/cli 0.6.0 → 0.8.0

package/README.md

@@ -5,6 +5,27 @@ API. Friendly commands cover common vehicle and spreadsheet work. The allowliste
 command covers equipment, maintenance, defects, walkarounds, files, reminders, contacts, bookings,
 tolls, tracking, guidance and exports without opening arbitrary or unpublished paths.
 
+## Start here
+
+Run `npx @fleetkeep/cli setup` after installation. It signs you in through your
+browser, checks your existing account and shows the next step. Return to the
+terminal after each website step and refresh to see the current status.
+
+Choose your intended fleet size on the website. Eligible new accounts can start
+a 30-day trial without a card; the price is shown before confirmation. Existing
+customers keep their account and subscription. App-store subscribers should
+contact Fleetkeep about Fleet access before purchasing a separate web plan.
+
+Once Fleet access is active, use `fleetkeep import preview "fleet.xlsx"` to
+review a spreadsheet before saving. The preview supplies the exact confirmation
+command. Review missing dates, reminder timing and recipients on the dashboard.
+Add a card only through the website after checking the first payment date.
+
+`fleetkeep setup --json` returns the current setup state for automation without
+opening a browser or starting an interactive login. `--no-browser` prints links
+for you to open yourself. Setup never starts a subscription, imports records or
+enables reminders on its own. It requires the matching setup API deployment.
+
 ## Shared jobs and running costs
 
 Friendly commands return JSON, including missing-data and stale-tracking fields:
@@ -41,6 +62,18 @@ credentials are not transferred between products or customer workspaces.
 
 ## Service intervals and equipment
 
+Record completed servicing by registration without looking up an internal vehicle ID first:
+
+```sh
+fleetkeep service record "BD15 KFG" --date 2026-09-27 --mileage 48212 \
+  --work "Scheduled service"
+```
+
+Fleetkeep matches the exact normalised registration and shows the proposed record. Nothing is
+saved until the operator repeats the same command with the short-lived confirmation token. The
+CLI derives a stable idempotency key from the matched vehicle and record, so an identical retry
+returns the original result rather than creating a duplicate.
+
 Set one service interval in days, weeks or months. The vehicle command clears the
 alternative unit when switching, and converts weeks to days:
 
@@ -72,6 +105,28 @@ maintenance updates cannot edit calculated forecast dates. There are no automati
 fuel-card feeds in the CLI. Wex credentials and Xero authorisation are entered in
 the website, never through CLI command arguments.
 
+## Toll statements and email forwarding
+
+```sh
+fleetkeep tolls forwarding
+fleetkeep tolls forwarding enable
+fleetkeep tolls import preview statement.csv
+fleetkeep tolls import apply statement.csv --confirm <digest-from-preview>
+```
+
+The forwarding command shows your private account address, recent imports and
+email delivery results. `enable` creates the address if needed. Forward CSV
+statement attachments to that address; the inbox is checked every 60 minutes.
+Each email accepts up to five attachments of 512 KiB each. Review unmatched
+vehicles and delivery messages in Fleetkeep. Keep the address private.
+
+For a local CSV, preview first and review the importable, duplicate and unmatched
+counts. Apply requires the exact preview digest and rejects a changed file before
+sending it. The CLI sends a stable idempotency key in the request header; use
+`--idempotency-key <key>` to choose your own and reuse it for an identical retry.
+Add `--json` to any command for the full API response. These commands require the
+matching toll API deployment. Statement preview requires `tolls:read`; applying an import and both forwarding commands require `tolls:write`.
+
 ## Safety model
 
 - `api operations` is generated as a fixed allowlist of the published OpenAPI operation IDs.
@@ -115,6 +170,9 @@ fleetkeep api call listTrackingSnapshots
 fleetkeep api call getWexRouteHistory --path vehicleId=<vehicle-id> --query period=7d
 fleetkeep api call createServiceRecord --path id=<vehicle-id> \
   --idempotency-key <unique-value> --data-file service-record.json
+fleetkeep api call createServiceRecord --path id=<vehicle-id> \
+  --idempotency-key <same-unique-value> --confirmation <server-token> \
+  --data-file service-record.json
 fleetkeep api call uploadVehiclePhoto --path id=<vehicle-id> --file photo=van.jpg
 fleetkeep api call downloadFleetSpreadsheet --output fleetkeep-export.xlsx
 ```
@@ -128,3 +186,11 @@ Set `FLEETKEEP_API_URL` to an alternate origin for local or staging verification
 automation, set `FLEETKEEP_ACCESS_TOKEN` in the process environment. OAuth access and refresh tokens
 are never accepted in command arguments. Short-lived action confirmations are supplied separately
 with `--confirmation`.
+
+Service-record creation is a two-step operator-confirmed action. The first call returns a 409
+challenge. Retry the identical body and idempotency key with its `--confirmation` token. A safe
+retry with the same key returns the original record instead of creating a duplicate.
+
+The private email-forwarding address requires `tolls:write`, including when reading it: anyone holding that address can submit statements. Read-only integrations do not receive it.
+
+CLI toll statement imports accept CSV files up to 256 KiB, the published API limit. Email forwarding accepts up to five CSV attachments of 512 KiB each. Preview and confirm the exact file digest before a CLI import is applied.

package/auth.mjs

@@ -224,7 +224,7 @@ export async function getAccessToken() {
 }
 
 /** @param {string} url */
-function openBrowser(url) {
+export function openBrowser(url) {
   /** @type {[string, string[]]} */
   const command =
     process.platform === 'darwin'

package/fleetkeep.mjs

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 
 import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import { basename, extname, resolve } from 'node:path';
 import { runApiCommand } from './api-command.mjs';
+import { runSetup } from './setup.mjs';
 import { authStatus, getAccessToken, login, logout } from './auth.mjs';
 
 const DEFAULT_API_URL = 'https://fleetkeep.co.uk';
@@ -11,6 +13,7 @@ function usage() {
   return `Fleetkeep CLI
 
 Usage:
+  fleetkeep setup [--no-browser] [--json]
   fleetkeep auth login [--no-browser]
   fleetkeep auth status
   fleetkeep auth logout
@@ -20,6 +23,8 @@ Usage:
   fleetkeep vehicles update <vehicle-id> [vehicle options] [--clear <field,...>] [--json]
   fleetkeep vehicles delete <vehicle-id> [--confirmation <server-token>] [--json]
   fleetkeep vehicles bulk-add <registration>... [--json]
+  fleetkeep service record <registration> --date <YYYY-MM-DD> --mileage <integer> --work <text>
+    [--supplier <text>] [--invoice <text>] [--confirmation <server-token>] [--json]
   fleetkeep drivers list [--json]
   fleetkeep drivers activity [--search <job-driver-registration>] [--json]
   fleetkeep costs list [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>] [--json]
@@ -35,6 +40,10 @@ Usage:
   fleetkeep jobs reopen <job-id> [--json]
   fleetkeep import preview <file.csv|file.xlsx> [--json]
   fleetkeep import apply <file.csv|file.xlsx> --confirm <digest> [--idempotency-key <key>] [--json]
+  fleetkeep tolls forwarding [--json]
+  fleetkeep tolls forwarding enable [--json]
+  fleetkeep tolls import preview <file.csv> [--json]
+  fleetkeep tolls import apply <file.csv> --confirm <digest> [--idempotency-key <key>] [--json]
   fleetkeep api operations [--json]
   fleetkeep api call <operation-id> [API options]
 
@@ -260,6 +269,129 @@ function printJsonOr(payload, jsonOutput, line) {
   process.stdout.write(jsonOutput ? `${JSON.stringify(payload, null, 2)}\n` : `${line}\n`);
 }
 
+function normaliseRegistration(value) {
+  return value.toUpperCase().replace(/\s+/g, '');
+}
+
+function serviceRecordBody(args) {
+  const allowed = new Set([
+    '--date',
+    '--mileage',
+    '--work',
+    '--supplier',
+    '--invoice',
+    '--notes',
+    '--next-date',
+    '--next-mileage',
+    '--confirmation',
+    '--json'
+  ]);
+  for (const arg of args) {
+    if (arg.startsWith('--') && !allowed.has(arg)) throw new Error(`Unknown option: ${arg}.`);
+  }
+  const servicedAt = option(args, '--date');
+  const mileage = option(args, '--mileage');
+  const workSummary = option(args, '--work');
+  if (!servicedAt) throw new Error('--date is required.');
+  parseVehicleValue('--date', servicedAt, { type: 'date' });
+  if (!mileage) throw new Error('--mileage is required.');
+  const odometerMileage = parseVehicleValue('--mileage', mileage, {
+    type: 'integer',
+    min: 0,
+    max: 1500000
+  });
+  if (!workSummary) throw new Error('--work is required.');
+  const body = { servicedAt, odometerMileage, workSummary };
+  for (const [name, field] of [
+    ['--supplier', 'supplier'],
+    ['--invoice', 'invoiceReference'],
+    ['--notes', 'notes'],
+    ['--next-date', 'nextServiceDueDate']
+  ]) {
+    const value = option(args, name);
+    if (value) {
+      if (name === '--next-date') parseVehicleValue(name, value, { type: 'date' });
+      body[field] = value;
+    }
+  }
+  const nextMileage = option(args, '--next-mileage');
+  if (nextMileage) {
+    body.nextServiceDueMileage = parseVehicleValue('--next-mileage', nextMileage, {
+      type: 'integer',
+      min: 0,
+      max: 1500000
+    });
+  }
+  return body;
+}
+
+async function recordServiceByRegistration(registration, args, jsonOutput) {
+  if (!registration || registration.startsWith('--'))
+    throw new Error('A registration is required.');
+  const body = serviceRecordBody(args);
+  const listed = await request('/api/v1/vehicles', {});
+  const wanted = normaliseRegistration(registration);
+  const matches = (listed.vehicles || []).filter(
+    (vehicle) => normaliseRegistration(vehicle.registration || '') === wanted
+  );
+  if (matches.length === 0) throw new Error(`No vehicle matched registration ${registration}.`);
+  if (matches.length > 1)
+    throw new Error(`More than one vehicle matched registration ${registration}.`);
+  const vehicle = matches[0];
+  const idempotencyKey = `service:${createHash('sha256')
+    .update(JSON.stringify({ vehicleId: vehicle.id, body }))
+    .digest('hex')
+    .slice(0, 32)}`;
+  const confirmation = option(args, '--confirmation');
+  try {
+    const payload = await request(
+      `/api/v1/vehicles/${encodeURIComponent(vehicle.id)}/service-records`,
+      {
+        method: 'POST',
+        body,
+        headers: {
+          'idempotency-key': idempotencyKey,
+          ...(confirmation ? { 'x-fleetkeep-confirmation': confirmation } : {})
+        }
+      }
+    );
+    printJsonOr(
+      payload,
+      jsonOutput,
+      `${payload.replay ? 'Service record already saved' : 'Service record saved'}: ${vehicle.registration}, ${body.servicedAt}, ${body.odometerMileage.toLocaleString('en-GB')} miles.`
+    );
+  } catch (error) {
+    if (
+      error instanceof FleetkeepApiError &&
+      error.status === 409 &&
+      error.payload?.error === 'confirmation_required' &&
+      typeof error.payload.confirmationToken === 'string'
+    ) {
+      if (jsonOutput)
+        process.stdout.write(
+          `${JSON.stringify({ ...error.payload, vehicle, proposedRecord: body }, null, 2)}\n`
+        );
+      else {
+        process.stdout.write(
+          [
+            'No record was saved.',
+            `Vehicle: ${vehicle.registration}${vehicle.label ? ` (${vehicle.label})` : ''}`,
+            `Service date: ${body.servicedAt}`,
+            `Mileage: ${body.odometerMileage.toLocaleString('en-GB')}`,
+            `Work: ${body.workSummary}`,
+            '',
+            'After checking those details, repeat the same command with:',
+            `--confirmation ${error.payload.confirmationToken}`
+          ].join('\n') + '\n'
+        );
+      }
+      process.exitCode = 2;
+      return;
+    }
+    throw error;
+  }
+}
+
 async function spreadsheetPayload(fileArg) {
   if (!fileArg || fileArg.startsWith('--')) throw new Error('A .csv or .xlsx file is required.');
   const path = resolve(fileArg);
@@ -317,6 +449,93 @@ function printImport(payload, jsonOutput) {
   }
 }
 
+function printTollForwarding(payload, jsonOutput) {
+  const lines = [
+    `Email forwarding: ${payload.available === false ? 'not available' : payload.enabled ? 'enabled' : 'not enabled'}`,
+    ...(payload.address ? [`Forward CSV statements to: ${payload.address}`] : []),
+    `Inbox checked every ${payload.pollIntervalMinutes.toLocaleString('en-GB')} minutes.`,
+    ...(payload.enabled || payload.available === false
+      ? []
+      : ['To create your forwarding address: fleetkeep tolls forwarding enable']),
+    ...payload.recentImports.map(
+      (item) =>
+        `${item.fileName}: ${item.importedCount.toLocaleString('en-GB')} imported, ${item.unmatchedCount.toLocaleString('en-GB')} unmatched, ${item.duplicateCount.toLocaleString('en-GB')} duplicates (${item.status})`
+    ),
+    ...payload.recentDeliveries.map((item) => `${item.createdAt}: ${item.message}`)
+  ];
+  printJsonOr(payload, jsonOutput, lines.join('\n'));
+}
+
+async function tollImport(action, fileArg, args, jsonOutput) {
+  const allowed = new Set(
+    action === 'apply' ? ['--json', '--confirm', '--idempotency-key'] : ['--json']
+  );
+  for (let index = 0; index < args.length; index += 1) {
+    const name = args[index];
+    if (!allowed.has(name)) throw new Error(`Unknown option: ${name}.`);
+    if (name !== '--json') {
+      requiredValue(args, name);
+      index += 1;
+    }
+  }
+  const confirmDigest = requiredValue(args, '--confirm');
+  if (action === 'apply' && !/^[0-9a-f]{64}$/.test(confirmDigest || '')) {
+    throw new Error(
+      'Apply is blocked until --confirm contains the exact digest returned by preview.'
+    );
+  }
+  const idempotencyKey = requiredValue(args, '--idempotency-key');
+  if (!fileArg || fileArg.startsWith('--') || extname(fileArg).toLowerCase() !== '.csv') {
+    throw new Error('A .csv toll statement is required.');
+  }
+  const body = await spreadsheetPayload(fileArg);
+  if (Buffer.byteLength(body.csv, 'utf8') > 256 * 1024) {
+    throw new Error(
+      'CLI toll imports accept CSV files up to 256 KiB. Split a larger statement first.'
+    );
+  }
+  if (
+    action === 'apply' &&
+    createHash('sha256').update(body.csv, 'utf8').digest('hex') !== confirmDigest
+  ) {
+    throw new Error('The file does not match --confirm. Preview this file again before applying.');
+  }
+  const payload = await request(`/api/v1/tolls/imports/${action}`, {
+    method: 'POST',
+    body: action === 'apply' ? { ...body, confirmDigest } : body,
+    ...(action === 'apply'
+      ? { headers: { 'idempotency-key': idempotencyKey || `cli:tolls:${confirmDigest}` } }
+      : {})
+  });
+  if (jsonOutput) {
+    printJsonOr(payload, true, '');
+    return;
+  }
+  const count = (value) => value.toLocaleString('en-GB');
+  const lines =
+    action === 'preview'
+      ? [
+          `Source: ${payload.sourceName}`,
+          `Digest: ${payload.digest}`,
+          `Rows: ${count(payload.rowCount)}`,
+          `Importable: ${count(payload.importableCount)}`,
+          `Duplicates: ${count(payload.duplicateCount)}`,
+          `Unmatched vehicles: ${count(payload.unknownCount)}`,
+          '',
+          'No data was changed. To apply this exact file:',
+          `fleetkeep tolls import apply ${JSON.stringify(fileArg)} --confirm ${payload.digest}`
+        ]
+      : [
+          payload.replay
+            ? 'Toll import result replayed from the original request.'
+            : 'Toll import completed.',
+          `Imported: ${count(payload.imported)}`,
+          `Duplicates: ${count(payload.duplicates)}`,
+          `Unmatched vehicles: ${count(payload.unknown)}`
+        ];
+  process.stdout.write(lines.join('\n') + '\n');
+}
+
 async function main() {
   const args = process.argv.slice(2);
   const jsonOutput = args.includes('--json');
@@ -325,6 +544,29 @@ async function main() {
     return;
   }
 
+  if (args[0] === 'setup') {
+    await runSetup(args.slice(1));
+    return;
+  }
+
+  if (args[0] === 'tolls' && args[1] === 'forwarding') {
+    const rest = args.slice(2).filter((arg) => arg !== '--json');
+    if (rest.length > 1 || (rest.length === 1 && rest[0] !== 'enable')) {
+      throw new Error('Use fleetkeep tolls forwarding [enable] [--json].');
+    }
+    const payload = await request(
+      '/api/v1/tolls/forwarding',
+      rest[0] === 'enable' ? { method: 'POST', body: {} } : {}
+    );
+    printTollForwarding(payload, jsonOutput);
+    return;
+  }
+
+  if (args[0] === 'tolls' && args[1] === 'import' && ['preview', 'apply'].includes(args[2])) {
+    await tollImport(args[2], args[3], args.slice(4), jsonOutput);
+    return;
+  }
+
   if (args[0] === 'costs' && args[1] === 'list') {
     const query = [];
     for (const name of ['from', 'to']) {
@@ -398,6 +640,11 @@ async function main() {
     return;
   }
 
+  if (args[0] === 'service' && args[1] === 'record') {
+    await recordServiceByRegistration(args[2], args.slice(3), jsonOutput);
+    return;
+  }
+
   if (args[0] === 'vehicles' && args[1] === 'get') {
     const payload = await request(vehiclePath(args[2]), {});
     if (jsonOutput) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);

package/operations.mjs

@@ -1,5 +1,68 @@
 /** @type {Array<[string, string, string, string, Record<string, unknown>?]>} */
 const definitions = [
+  ['getFuelPrices', 'GET', '/api/fuel-prices', 'operations:read'],
+  [
+    'getFuelEconomy',
+    'GET',
+    '/api/fuel-economy',
+    'operations:read',
+    { query: ['year', 'make', 'model'] }
+  ],
+  [
+    'listFuelEconomyModels',
+    'GET',
+    '/api/fuel-economy/models',
+    'operations:read',
+    { query: ['year', 'make'] }
+  ],
+  [
+    'getChargingPrices',
+    'GET',
+    '/api/charging-prices',
+    'operations:read',
+    { query: ['region', 'days'] }
+  ],
+  ['getPublicChargingPrices', 'GET', '/api/public-charging-prices', 'operations:read'],
+  [
+    'replaceServiceSchedule',
+    'POST',
+    '/api/v1/vehicles/{id}/service-schedules',
+    'maintenance:write',
+    { idempotency: true }
+  ],
+  [
+    'prepareServiceEvidenceRequest',
+    'POST',
+    '/api/v1/vehicles/{id}/service-evidence-requests',
+    'maintenance:write',
+    { idempotency: true }
+  ],
+  [
+    'recordServiceEvidenceContact',
+    'POST',
+    '/api/v1/vehicles/{id}/service-evidence-requests/{requestId}/contacts',
+    'maintenance:write',
+    { idempotency: true }
+  ],
+  [
+    'recordServiceEvidenceSubmission',
+    'POST',
+    '/api/v1/vehicles/{id}/service-evidence-requests/{requestId}/submissions',
+    'maintenance:write',
+    { idempotency: true }
+  ],
+  [
+    'reviewServiceEvidenceSubmission',
+    'POST',
+    '/api/v1/vehicles/{id}/service-evidence-requests/{requestId}/submissions/{submissionId}/review',
+    'maintenance:write',
+    { idempotency: true }
+  ],
+  ['listDrivers', 'GET', '/api/v1/drivers', 'operations:read'],
+  ['getDriverActivity', 'GET', '/api/v1/drivers/activity', 'operations:read', { query: ['q'] }],
+  ['listDriverMemberships', 'GET', '/api/v1/driver-workspace', 'vehicles:read'],
+  ['getDriverWorkspace', 'GET', '/api/v1/driver-workspace/{id}', 'operations:read'],
+  ['getPushNotificationStatus', 'GET', '/api/v1/settings/push-notifications', 'reminders:read'],
   ['importProviderJobs', 'POST', '/api/v1/jobs/import', 'operations:write'],
   ['listFleetJobs', 'GET', '/api/v1/jobs', 'operations:read', { query: ['q'] }],
   ['saveFleetJob', 'POST', '/api/v1/jobs', 'operations:write'],
@@ -14,6 +77,7 @@ const definitions = [
   ],
   ['listVehicles', 'GET', '/api/v1/vehicles', 'vehicles:read'],
   ['addVehicle', 'POST', '/api/v1/vehicles', 'vehicles:write'],
+  ['searchVehicles', 'GET', '/api/v1/vehicles/search', 'vehicles:read', { query: ['q', 'limit'] }],
   ['getVehicle', 'GET', '/api/v1/vehicles/{id}', 'vehicles:read'],
   ['updateVehicle', 'PATCH', '/api/v1/vehicles/{id}', 'vehicles:write'],
   ['deleteVehicle', 'DELETE', '/api/v1/vehicles/{id}', 'vehicles:write', { confirmation: true }],
@@ -92,6 +156,27 @@ const definitions = [
     'vehicles:write',
     { confirmation: true }
   ],
+  [
+    'listServiceSchedules',
+    'GET',
+    '/api/v1/vehicles/{id}/service-schedules',
+    'maintenance:read',
+    { query: ['limit', 'offset'] }
+  ],
+  [
+    'listServiceEvidenceRequests',
+    'GET',
+    '/api/v1/vehicles/{id}/service-evidence-requests',
+    'maintenance:read',
+    { query: ['limit', 'offset'] }
+  ],
+  [
+    'getServiceEvidenceTimeline',
+    'GET',
+    '/api/v1/vehicles/{id}/service-evidence-requests/{requestId}/contacts',
+    'maintenance:read',
+    { query: ['limit'] }
+  ],
   [
     'listServiceRecords',
     'GET',
@@ -104,7 +189,7 @@ const definitions = [
     'POST',
     '/api/v1/vehicles/{id}/service-records',
     'maintenance:write',
-    { idempotency: true }
+    { confirmation: true, idempotency: true }
   ],
   [
     'getServiceRecord',
@@ -215,6 +300,8 @@ const definitions = [
     'tolls:write',
     { idempotency: true }
   ],
+  ['getTollForwarding', 'GET', '/api/v1/tolls/forwarding', 'tolls:write'],
+  ['enableTollForwarding', 'POST', '/api/v1/tolls/forwarding', 'tolls:write'],
   ['previewTollImport', 'POST', '/api/v1/tolls/imports/preview', 'tolls:read'],
   ['applyTollImport', 'POST', '/api/v1/tolls/imports/apply', 'tolls:write', { idempotency: true }],
   ['listTrackingSnapshots', 'GET', '/api/v1/operations/tracking', 'operations:read'],
@@ -225,6 +312,7 @@ const definitions = [
     'operations:read',
     { query: ['period'] }
   ],
+  ['getSetupStatus', 'GET', '/api/v1/setup', 'profile:read'],
   ['getProfile', 'GET', '/api/v1/profile', 'profile:read'],
   ['getDriverGuidance', 'GET', '/api/v1/driver-guidance', 'guidance:read'],
   [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fleetkeep/cli",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Operate every published Fleetkeep API workflow with guarded writes and machine-readable output",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "auth.mjs",
     "fleetkeep.mjs",
     "operations.mjs",
+    "setup.mjs",
     "README.md"
   ],
   "engines": {

package/setup.mjs

@@ -0,0 +1,94 @@
+import { createInterface } from 'node:readline/promises';
+import { getAccessToken, loadStoredTokens, login, oauthConfig, openBrowser } from './auth.mjs';
+
+/** @param {string[]} args */
+export async function runSetup(args) {
+  for (const arg of args) {
+    if (!['--json', '--no-browser'].includes(arg)) throw new Error(`Unknown setup option: ${arg}`);
+  }
+  const json = args.includes('--json');
+  const interactive = !json && Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const origin = oauthConfig().origin;
+  if (!process.env.FLEETKEEP_ACCESS_TOKEN?.trim() && !(await loadStoredTokens())) {
+    if (!interactive) {
+      const next = { nextStep: 'sign_in', command: 'fleetkeep auth login', url: `${origin}/login` };
+      process.stdout.write(
+        json
+          ? `${JSON.stringify(next)}\n`
+          : `Sign in or create your Fleetkeep account in the browser:\n${next.command}\nThen run fleetkeep setup again.\n`
+      );
+      return;
+    }
+    process.stdout.write(
+      'Sign in or create your account in the browser. Existing plans stay on the same account.\n'
+    );
+    await login({ noBrowser: args.includes('--no-browser') });
+  }
+  const input = interactive
+    ? createInterface({ input: process.stdin, output: process.stdout })
+    : null;
+  try {
+    do {
+      const response = await fetch(new URL('/api/v1/setup', origin), {
+        headers: { authorization: `Bearer ${await getAccessToken()}`, accept: 'application/json' },
+        redirect: 'error',
+        signal: AbortSignal.timeout(25_000)
+      });
+      if (!response.ok)
+        throw new Error(
+          `Setup status unavailable (${response.status}). No changes were made. Try fleetkeep auth login if your session expired.`
+        );
+      const state = await response.json();
+      if (json) {
+        process.stdout.write(`${JSON.stringify(state, null, 2)}\n`);
+        return;
+      }
+      process.stdout.write(
+        `\nFleetkeep setup\n${Number(state.vehicleCount).toLocaleString('en-GB')} vehicles saved\n${state.nextAction}\n`
+      );
+      if (state.billing.trialEndsAt)
+        process.stdout.write(
+          `Trial ends: ${new Date(state.billing.trialEndsAt).toLocaleDateString('en-GB', { day: 'numeric', month: 'long', year: 'numeric', timeZone: 'Europe/London' })}\n`
+        );
+      process.stdout.write(`${state.paymentNote}\n`);
+      const steps = /** @type {Record<string, string>} */ ({
+        plan: 'plans',
+        fleet_access: 'billing',
+        vehicles: 'addVehicle',
+        reminders: 'reminders',
+        review: 'dashboard'
+      });
+      const key = steps[state.nextStep];
+      // Only open the known website paths, never an arbitrary returned URL.
+      const paths = /** @type {Record<string, string>} */ ({
+        plans: '/dashboard/choose-plan',
+        billing: '/dashboard/settings#billing',
+        addVehicle: '/dashboard/vehicles/new',
+        reminders: '/dashboard/settings#reminders',
+        dashboard: '/dashboard'
+      });
+      const url = new URL(paths[key] || '/dashboard', origin).href;
+      process.stdout.write(`Next: ${url}\n`);
+      if (state.canUseApi)
+        process.stdout.write(
+          'Spreadsheet: fleetkeep import preview "fleet.xlsx"\nReview the preview, then use its confirmation command to save.\n'
+        );
+      if (!input) return;
+      const answer = (
+        await input.question(
+          '\n[o] Open next step  [r] Refresh after completing it  [Enter] Finish: '
+        )
+      )
+        .trim()
+        .toLowerCase();
+      if (answer === 'o') {
+        if (!args.includes('--no-browser')) openBrowser(url);
+        await input.question(
+          'Complete the step in your browser, then press Enter to check again. '
+        );
+      } else if (answer !== 'r') return;
+    } while (true);
+  } finally {
+    input?.close();
+  }
+}