@fleetkeep/cli 0.1.2 → 0.4.0

package/README.md

@@ -1,21 +1,27 @@
 # Fleetkeep CLI
 
-The Fleetkeep CLI gives an operator or software agent the same bounded fleet import path as the
-Fleetkeep dashboard. It can list vehicles, preview CSV or XLSX imports and apply the exact
-previewed file.
+The Fleetkeep CLI lets an operator or software agent use every operation in Fleetkeep's published
+API. Friendly commands cover common vehicle and spreadsheet work. The allowlisted `api call`
+command covers equipment, maintenance, defects, walkarounds, files, reminders, contacts, bookings,
+tolls, tracking, guidance and exports without opening arbitrary or unpublished paths.
 
 ## Safety model
 
-- Preview is read-only and uses `vehicles:read`.
-- Apply uses `vehicles:write` and requires the exact SHA-256 digest returned by preview.
-- Every apply request has an idempotency key. Retrying the same request does not duplicate vehicles
-  or equipment history.
-- Existing vehicle dates and current equipment are not overwritten by spreadsheet import.
+- `api operations` is generated as a fixed allowlist of the published OpenAPI operation IDs.
+- Consequential actions use short-lived server-issued confirmation tokens. An unconfirmed request
+  returns the token without making the change; review it before repeating with `--confirmation`.
+- Retry-safe creates and sends require `--idempotency-key` when the API contract requires it.
+- Vehicle and toll imports remain preview-first and require the exact preview digest before apply.
+- Multipart uploads accept only explicit `--field` and `--file` values. Each file is capped at 10 MB.
+- Downloads require an explicit output path. Existing files are not replaced unless `--overwrite`
+  is present.
+- Updates distinguish omitted fields from fields explicitly cleared with `--clear`.
 - Interactive login uses an OAuth 2.1 public client with S256 PKCE and a loopback callback.
 - Stored access and refresh tokens use an owner-only local file and are never accepted as command
   arguments.
 - `FLEETKEEP_ACCESS_TOKEN` remains available as an explicit environment override for automation.
-- The API retains the import result in Fleetkeep's audit log.
+- OAuth asks only for the published operational scopes. Account deletion, billing, OAuth-client
+  administration and telematics credential operations are not available.
 
 ## Use
 
@@ -24,10 +30,34 @@ Node.js 20 or newer is required. Sign in through Fleetkeep in your browser, then
 ```sh
 fleetkeep auth login
 fleetkeep vehicles list
+fleetkeep vehicles get <vehicle-id> --json
+fleetkeep vehicles add "AB12 CDE" --label "Service van" --operational-status active --json
+fleetkeep vehicles update <vehicle-id> --operational-status off_road --status-notes "Unsafe tyre"
+fleetkeep vehicles update <vehicle-id> --clear assignedDriverName,assignedDriverContact
+fleetkeep vehicles bulk-add "AB12 CDE" "XY34 ZZZ" --json
+fleetkeep vehicles delete <vehicle-id> --json
+fleetkeep vehicles delete <vehicle-id> --confirmation <server-token> --json
+fleetkeep drivers list
+fleetkeep drivers invite driver@example.com --name "Pat Driver"
+fleetkeep drivers resend <driver-id>
+fleetkeep drivers revoke <driver-id>
 fleetkeep import preview vehicles.xlsx
 fleetkeep import apply vehicles.xlsx --confirm <digest-from-preview>
+fleetkeep api operations --json
+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 uploadVehiclePhoto --path id=<vehicle-id> --file photo=van.jpg
+fleetkeep api call downloadFleetSpreadsheet --output fleetkeep-export.xlsx
 ```
 
-Use `--json` for machine-readable output. Set `FLEETKEEP_API_URL` to an alternate origin for local
-or staging verification. For unattended automation, set `FLEETKEEP_ACCESS_TOKEN` in the process
-environment instead of storing or passing a token in command arguments.
+Run `fleetkeep --help` for API call options and every supported vehicle field. `api call` returns
+JSON for JSON endpoints and a JSON receipt for saved downloads. Use `--path name=value` for each path
+placeholder, `--query name=value` for query values, and `--data` or `--data-file` for JSON bodies.
+Use repeated `--field` and `--file` options for published multipart operations.
+
+Set `FLEETKEEP_API_URL` to an alternate origin for local or staging verification. For unattended
+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`.

package/api-command.mjs

@@ -0,0 +1,288 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { extname, resolve } from 'node:path';
+
+import { getAccessToken } from './auth.mjs';
+import { operationList, operations } from './operations.mjs';
+
+const MAX_UPLOAD_BYTES = 10 * 1024 * 1024;
+const MAX_JSON_BYTES = 15 * 1024 * 1024;
+
+function apiOrigin() {
+  const value = (process.env.FLEETKEEP_API_URL || 'https://fleetkeep.co.uk')
+    .trim()
+    .replace(/\/$/, '');
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error('FLEETKEEP_API_URL must be a valid HTTP or HTTPS origin.');
+  }
+  if (
+    !['http:', 'https:'].includes(url.protocol) ||
+    url.pathname !== '/' ||
+    url.search ||
+    url.hash ||
+    url.username ||
+    url.password
+  ) {
+    throw new Error('FLEETKEEP_API_URL must be an HTTP or HTTPS origin without a path.');
+  }
+  return url.origin;
+}
+
+function parseAssignment(value, option) {
+  const separator = value.indexOf('=');
+  if (separator < 1) throw new Error(`${option} requires name=value.`);
+  return [value.slice(0, separator), value.slice(separator + 1)];
+}
+
+function parseCallOptions(args) {
+  const parsed = {
+    path: [],
+    query: [],
+    fields: [],
+    files: [],
+    data: null,
+    dataFile: null,
+    confirmation: null,
+    idempotencyKey: null,
+    output: null,
+    overwrite: false,
+    json: false
+  };
+  const repeatable = new Map([
+    ['--path', 'path'],
+    ['--query', 'query'],
+    ['--field', 'fields'],
+    ['--file', 'files']
+  ]);
+  const single = new Map([
+    ['--data', 'data'],
+    ['--data-file', 'dataFile'],
+    ['--confirmation', 'confirmation'],
+    ['--idempotency-key', 'idempotencyKey'],
+    ['--output', 'output']
+  ]);
+
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === '--overwrite' || arg === '--json') {
+      parsed[arg === '--overwrite' ? 'overwrite' : 'json'] = true;
+      continue;
+    }
+    const target = repeatable.get(arg) || single.get(arg);
+    if (!target) throw new Error(`Unknown API call option: ${arg}.`);
+    const value = args[++index];
+    if (value === undefined || value.startsWith('--')) throw new Error(`${arg} requires a value.`);
+    if (repeatable.has(arg)) parsed[target].push(parseAssignment(value, arg));
+    else if (parsed[target] !== null) throw new Error(`${arg} may be supplied only once.`);
+    else parsed[target] = value;
+  }
+  return parsed;
+}
+
+function operationPath(operation, assignments) {
+  const values = new Map();
+  for (const [name, value] of assignments) {
+    if (values.has(name)) throw new Error(`--path ${name} was supplied more than once.`);
+    values.set(name, value);
+  }
+  const expected = [...operation.path.matchAll(/\{([^}]+)\}/g)].map((match) => match[1]);
+  for (const name of values.keys()) {
+    if (!expected.includes(name))
+      throw new Error(`Unknown path parameter for ${operation.id}: ${name}.`);
+  }
+  let path = operation.path;
+  for (const name of expected) {
+    if (!values.has(name) || values.get(name) === '') {
+      throw new Error(`${operation.id} requires --path ${name}=<value>.`);
+    }
+    path = path.replace(`{${name}}`, encodeURIComponent(values.get(name)));
+  }
+  return path;
+}
+
+function mimeType(path) {
+  return (
+    {
+      '.csv': 'text/csv',
+      '.doc': 'application/msword',
+      '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+      '.jpeg': 'image/jpeg',
+      '.jpg': 'image/jpeg',
+      '.mov': 'video/quicktime',
+      '.mp4': 'video/mp4',
+      '.pdf': 'application/pdf',
+      '.png': 'image/png',
+      '.webm': 'video/webm',
+      '.webp': 'image/webp',
+      '.xls': 'application/vnd.ms-excel',
+      '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+    }[extname(path).toLowerCase()] || 'application/octet-stream'
+  );
+}
+
+async function readBounded(path, maxBytes, label) {
+  const bytes = await readFile(resolve(path));
+  if (bytes.length > maxBytes) throw new Error(`${label} exceeds ${maxBytes} bytes.`);
+  return bytes;
+}
+
+async function requestBody(operation, options, headers) {
+  const hasMultipart = options.fields.length > 0 || options.files.length > 0;
+  if ((options.data !== null || options.dataFile !== null) && hasMultipart) {
+    throw new Error('--data or --data-file cannot be combined with --field or --file.');
+  }
+  if (options.data !== null && options.dataFile !== null) {
+    throw new Error('--data and --data-file cannot be combined.');
+  }
+  if (hasMultipart && !operation.multipart) {
+    throw new Error(`${operation.id} does not publish a multipart request.`);
+  }
+  if (hasMultipart) {
+    const form = new FormData();
+    for (const [name, value] of options.fields) form.append(name, value);
+    for (const [name, path] of options.files) {
+      const bytes = await readBounded(path, MAX_UPLOAD_BYTES, `Upload ${path}`);
+      form.append(
+        name,
+        new Blob([bytes], { type: mimeType(path) }),
+        resolve(path).split('/').pop()
+      );
+    }
+    return form;
+  }
+  if (options.data === null && options.dataFile === null) return undefined;
+  const source =
+    options.data !== null
+      ? options.data
+      : (await readBounded(options.dataFile, MAX_JSON_BYTES, 'JSON body')).toString('utf8');
+  let value;
+  try {
+    value = JSON.parse(source);
+  } catch {
+    throw new Error('The request body must be valid JSON.');
+  }
+  headers.set('content-type', 'application/json');
+  return JSON.stringify(value);
+}
+
+function confirmationResult(payload, operationId) {
+  if (
+    payload &&
+    typeof payload === 'object' &&
+    payload.error === 'confirmation_required' &&
+    typeof payload.confirmationToken === 'string'
+  ) {
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    process.stderr.write(
+      `No change was made. Review the action, then repeat ${operationId} with --confirmation <confirmationToken>.\n`
+    );
+    process.exitCode = 2;
+    return true;
+  }
+  return false;
+}
+
+async function writeOutput(path, bytes, overwrite) {
+  const destination = resolve(path);
+  try {
+    await writeFile(destination, bytes, overwrite ? undefined : { flag: 'wx' });
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'EEXIST') {
+      throw new Error(`Output already exists: ${destination}. Use --overwrite to replace it.`, {
+        cause: error
+      });
+    }
+    throw error;
+  }
+  return destination;
+}
+
+async function callOperation(operation, args) {
+  const options = parseCallOptions(args);
+  if (operation.binary && !options.output) {
+    throw new Error(`${operation.id} returns a file and requires --output <path>.`);
+  }
+  if (operation.idempotency && !options.idempotencyKey) {
+    throw new Error(`${operation.id} requires --idempotency-key <unique-value>.`);
+  }
+
+  const url = new URL(operationPath(operation, options.path), apiOrigin());
+  for (const [name, value] of options.query) {
+    if (!operation.query?.includes(name)) {
+      throw new Error(`Unknown query parameter for ${operation.id}: ${name}.`);
+    }
+    url.searchParams.append(name, value);
+  }
+  const headers = new Headers({
+    authorization: `Bearer ${await getAccessToken()}`,
+    accept: 'application/json, application/octet-stream;q=0.9, */*;q=0.8'
+  });
+  if (options.confirmation) headers.set('x-fleetkeep-confirmation', options.confirmation);
+  if (options.idempotencyKey) headers.set('idempotency-key', options.idempotencyKey);
+  const body = await requestBody(operation, options, headers);
+  const response = await fetch(url, {
+    method: operation.method,
+    headers,
+    ...(body ? { body } : {})
+  });
+  const contentType = response.headers.get('content-type') || 'application/octet-stream';
+
+  if (!response.ok) {
+    const payload = contentType.includes('json')
+      ? await response.json().catch(() => null)
+      : { error: (await response.text()).slice(0, 500) || `HTTP ${response.status}` };
+    if (response.status === 409 && confirmationResult(payload, operation.id)) return;
+    const code = typeof payload?.error === 'string' ? payload.error : `HTTP ${response.status}`;
+    throw new Error(`Fleetkeep API rejected ${operation.id} (${response.status}): ${code}`);
+  }
+
+  if (options.output) {
+    const bytes = Buffer.from(await response.arrayBuffer());
+    const destination = await writeOutput(options.output, bytes, options.overwrite);
+    process.stdout.write(
+      `${JSON.stringify({ ok: true, operationId: operation.id, status: response.status, output: destination, bytes: bytes.length, contentType }, null, 2)}\n`
+    );
+    return;
+  }
+  if (response.status === 204) {
+    process.stdout.write(`${JSON.stringify({ ok: true, operationId: operation.id }, null, 2)}\n`);
+    return;
+  }
+  if (!contentType.includes('json')) {
+    throw new Error(`${operation.id} returned ${contentType}; repeat with --output <path>.`);
+  }
+  const payload = await response.json();
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function printOperations(jsonOutput) {
+  if (jsonOutput) {
+    process.stdout.write(`${JSON.stringify({ operations: operationList }, null, 2)}\n`);
+    return;
+  }
+  for (const operation of operationList) {
+    process.stdout.write(
+      `${operation.id}\t${operation.method}\t${operation.path}\t${operation.scope}\n`
+    );
+  }
+}
+
+export async function runApiCommand(args) {
+  if (args[0] === 'operations') {
+    const unknown = args.filter((arg) => arg !== 'operations' && arg !== '--json');
+    if (unknown.length) throw new Error(`Unknown API operations option: ${unknown[0]}.`);
+    printOperations(args.includes('--json'));
+    return;
+  }
+  if (args[0] !== 'call')
+    throw new Error('Use `fleetkeep api operations` or `fleetkeep api call`.');
+  const operationId = args[1];
+  if (!operationId || operationId.startsWith('--')) throw new Error('An operation ID is required.');
+  const operation = operations[operationId];
+  if (!operation) {
+    throw new Error(`Unknown or unpublished Fleetkeep operation: ${operationId}.`);
+  }
+  await callOperation(operation, args.slice(2));
+}

package/auth.mjs

@@ -8,7 +8,24 @@ import { spawn } from 'node:child_process';
 const DEFAULT_API_URL = 'https://fleetkeep.co.uk';
 const DEFAULT_CLIENT_ID = 'fleetkeep-cli';
 const DEFAULT_REDIRECT_URI = 'http://127.0.0.1:38741/callback';
-const DEFAULT_SCOPES = ['vehicles:read', 'vehicles:write', 'offline_access'];
+export const DEFAULT_SCOPES = [
+  'vehicles:read',
+  'vehicles:write',
+  'operations:read',
+  'operations:write',
+  'tolls:read',
+  'tolls:write',
+  'documents:read',
+  'documents:write',
+  'maintenance:read',
+  'maintenance:write',
+  'reminders:read',
+  'reminders:write',
+  'profile:read',
+  'guidance:read',
+  'exports:read',
+  'offline_access'
+];
 const AUTH_TIMEOUT_MS = 10 * 60 * 1000;
 
 /** @typedef {{ accessToken: string, refreshToken?: string | null, expiresAt: number }} StoredTokens */

package/fleetkeep.mjs

@@ -2,6 +2,7 @@
 
 import { readFile } from 'node:fs/promises';
 import { basename, extname, resolve } from 'node:path';
+import { runApiCommand } from './api-command.mjs';
 import { authStatus, getAccessToken, login, logout } from './auth.mjs';
 
 const DEFAULT_API_URL = 'https://fleetkeep.co.uk';
@@ -14,15 +15,62 @@ Usage:
   fleetkeep auth status
   fleetkeep auth logout
   fleetkeep vehicles list [--json]
+  fleetkeep vehicles get <vehicle-id> [--json]
+  fleetkeep vehicles add <registration> [vehicle options] [--json]
+  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 drivers list [--json]
+  fleetkeep drivers invite <email> --name <name> [--json]
+  fleetkeep drivers resend <driver-id> [--json]
+  fleetkeep drivers revoke <driver-id> [--json]
   fleetkeep import preview <file.csv|file.xlsx> [--json]
   fleetkeep import apply <file.csv|file.xlsx> --confirm <digest> [--idempotency-key <key>] [--json]
+  fleetkeep api operations [--json]
+  fleetkeep api call <operation-id> [API options]
+
+API options:
+  --path <name=value>          Path parameter; repeat when needed
+  --query <name=value>         Query parameter; repeat when needed
+  --data <json>                JSON request body
+  --data-file <file.json>      JSON request body from a file
+  --field <name=value>         Multipart text field; repeat when needed
+  --file <name=path>           Multipart file; repeat when needed
+  --confirmation <token>       Server-issued action confirmation token
+  --idempotency-key <key>      Required for retry-safe create or send operations
+  --output <path>              Save a download; existing files are protected
+  --overwrite                  Allow --output to replace an existing file
+
+Vehicle options:
+  --label <text>
+  --insurance-due-date <YYYY-MM-DD>
+  --last-service-date <YYYY-MM-DD>
+  --last-service-mileage <integer>
+  --service-interval-months <integer>
+  --operational-status <active|standby|in_maintenance|off_road|sold_or_removed>
+  --assigned-driver-name <text>
+  --assigned-driver-contact <text>
+  --status-notes <text>
+
+Clearable update fields:
+  label, insuranceDueDate, lastServiceDate, lastServiceMileage, serviceIntervalMonths,
+  assignedDriverName, assignedDriverContact, statusNotes
 
 Environment:
   FLEETKEEP_ACCESS_TOKEN  Optional OAuth token override for automation
   FLEETKEEP_API_URL       API origin (default: https://fleetkeep.co.uk)
 
 Import is preview-first. Applying requires the exact digest returned by preview.
-Tokens are never accepted as command arguments.`;
+OAuth access and refresh tokens are never accepted as command arguments.`;
+}
+
+class FleetkeepApiError extends Error {
+  constructor(status, payload) {
+    const code = typeof payload?.error === 'string' ? payload.error : `HTTP ${status}`;
+    super(`Fleetkeep API rejected the request (${status}): ${code}`);
+    this.status = status;
+    this.payload = payload;
+  }
 }
 
 function fail(message, exitCode = 1) {
@@ -37,6 +85,104 @@ function option(args, name) {
   return value && !value.startsWith('--') ? value : '';
 }
 
+function requiredValue(args, name) {
+  const value = option(args, name);
+  if (value === '') throw new Error(`${name} requires a value.`);
+  return value;
+}
+
+const VEHICLE_OPTIONS = new Map([
+  ['--label', { field: 'label', type: 'string' }],
+  ['--insurance-due-date', { field: 'insuranceDueDate', type: 'date' }],
+  ['--last-service-date', { field: 'lastServiceDate', type: 'date' }],
+  [
+    '--last-service-mileage',
+    { field: 'lastServiceMileage', type: 'integer', min: 0, max: 1500000 }
+  ],
+  [
+    '--service-interval-months',
+    { field: 'serviceIntervalMonths', type: 'integer', min: 1, max: 120 }
+  ],
+  ['--operational-status', { field: 'operationalStatus', type: 'status' }],
+  ['--assigned-driver-name', { field: 'assignedDriverName', type: 'string' }],
+  ['--assigned-driver-contact', { field: 'assignedDriverContact', type: 'string' }],
+  ['--status-notes', { field: 'statusNotes', type: 'string' }]
+]);
+
+const CLEARABLE_FIELDS = new Set(
+  [...VEHICLE_OPTIONS.values()]
+    .map(({ field }) => field)
+    .filter((field) => field !== 'operationalStatus')
+);
+const OPERATIONAL_STATUSES = new Set([
+  'active',
+  'standby',
+  'in_maintenance',
+  'off_road',
+  'sold_or_removed'
+]);
+
+function parseVehicleValue(name, value, config) {
+  if (config.type === 'string') return value;
+  if (config.type === 'date') {
+    const date = new Date(`${value}T00:00:00Z`);
+    if (
+      !/^\d{4}-\d{2}-\d{2}$/.test(value) ||
+      Number.isNaN(date.getTime()) ||
+      date.toISOString().slice(0, 10) !== value
+    ) {
+      throw new Error(`${name} must be a valid date in YYYY-MM-DD format.`);
+    }
+    return value;
+  }
+  if (config.type === 'status') {
+    if (!OPERATIONAL_STATUSES.has(value)) {
+      throw new Error(`${name} must be one of: ${[...OPERATIONAL_STATUSES].join(', ')}.`);
+    }
+    return value;
+  }
+  if (!/^-?\d+$/.test(value)) throw new Error(`${name} must be an integer.`);
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < config.min || number > config.max) {
+    throw new Error(`${name} must be between ${config.min} and ${config.max}.`);
+  }
+  return number;
+}
+
+function vehicleBody(args, { allowClear = false } = {}) {
+  const body = {};
+  const recognised = new Set(['--json']);
+  for (const [name, config] of VEHICLE_OPTIONS) {
+    recognised.add(name);
+    const value = requiredValue(args, name);
+    if (value !== null) body[config.field] = parseVehicleValue(name, value, config);
+  }
+
+  if (allowClear) {
+    recognised.add('--clear');
+    const clear = requiredValue(args, '--clear');
+    if (clear !== null) {
+      for (const field of clear
+        .split(',')
+        .map((value) => value.trim())
+        .filter(Boolean)) {
+        if (!CLEARABLE_FIELDS.has(field)) {
+          throw new Error(`--clear contains an unknown or non-clearable field: ${field}.`);
+        }
+        if (Object.hasOwn(body, field)) {
+          throw new Error(`${field} cannot be set and cleared in the same request.`);
+        }
+        body[field] = null;
+      }
+    }
+  }
+
+  for (const arg of args) {
+    if (arg.startsWith('--') && !recognised.has(arg)) throw new Error(`Unknown option: ${arg}.`);
+  }
+  return body;
+}
+
 function apiOrigin() {
   const value = (process.env.FLEETKEEP_API_URL || DEFAULT_API_URL).trim().replace(/\/$/, '');
   let url;
@@ -51,25 +197,37 @@ function apiOrigin() {
   return url.origin;
 }
 
-async function request(path, { method = 'GET', body }) {
+async function request(path, { method = 'GET', body, headers: extraHeaders = {} }) {
   const token = await getAccessToken();
   const response = await fetch(`${apiOrigin()}${path}`, {
     method,
     headers: {
       authorization: `Bearer ${token}`,
       accept: 'application/json',
-      ...(body ? { 'content-type': 'application/json' } : {})
+      ...(body ? { 'content-type': 'application/json' } : {}),
+      ...extraHeaders
     },
     ...(body ? { body: JSON.stringify(body) } : {})
   });
-  const payload = await response.json().catch(() => ({ error: `HTTP ${response.status}` }));
+  const payload =
+    response.status === 204
+      ? null
+      : await response.json().catch(() => ({ error: `HTTP ${response.status}` }));
   if (!response.ok) {
-    const code = typeof payload?.error === 'string' ? payload.error : `HTTP ${response.status}`;
-    throw new Error(`Fleetkeep API rejected the request (${response.status}): ${code}`);
+    throw new FleetkeepApiError(response.status, payload);
   }
   return payload;
 }
 
+function vehiclePath(id) {
+  if (!id || id.startsWith('--')) throw new Error('A vehicle ID is required.');
+  return `/api/v1/vehicles/${encodeURIComponent(id)}`;
+}
+
+function printJsonOr(payload, jsonOutput, line) {
+  process.stdout.write(jsonOutput ? `${JSON.stringify(payload, null, 2)}\n` : `${line}\n`);
+}
+
 async function spreadsheetPayload(fileArg) {
   if (!fileArg || fileArg.startsWith('--')) throw new Error('A .csv or .xlsx file is required.');
   const path = resolve(fileArg);
@@ -150,6 +308,11 @@ async function main() {
     return;
   }
 
+  if (args[0] === 'api') {
+    await runApiCommand(args.slice(1));
+    return;
+  }
+
   if (args[0] === 'vehicles' && args[1] === 'list') {
     const payload = await request('/api/v1/vehicles', {});
     if (jsonOutput) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
@@ -163,6 +326,138 @@ async function main() {
     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`);
+    else {
+      const vehicle = payload.vehicle;
+      process.stdout.write(
+        `${vehicle.registration}\t${vehicle.label || ''}\t${vehicle.make || ''}\t${vehicle.operationalStatus || ''}\n`
+      );
+    }
+    return;
+  }
+
+  if (args[0] === 'vehicles' && args[1] === 'add') {
+    const registration = args[2];
+    if (!registration || registration.startsWith('--'))
+      throw new Error('A registration is required.');
+    const body = { registration, ...vehicleBody(args.slice(3)) };
+    const payload = await request('/api/v1/vehicles', { method: 'POST', body });
+    printJsonOr(payload, jsonOutput, `Vehicle added: ${registration} (${payload.id})`);
+    return;
+  }
+
+  if (args[0] === 'vehicles' && args[1] === 'update') {
+    const body = vehicleBody(args.slice(3), { allowClear: true });
+    if (Object.keys(body).length === 0) {
+      throw new Error('Update requires at least one vehicle option or --clear field.');
+    }
+    const payload = await request(vehiclePath(args[2]), { method: 'PATCH', body });
+    printJsonOr(payload, jsonOutput, `Vehicle updated: ${args[2]}`);
+    return;
+  }
+
+  if (args[0] === 'vehicles' && args[1] === 'delete') {
+    const id = args[2];
+    if (!id || id.startsWith('--')) throw new Error('A vehicle ID is required.');
+    const confirmation = option(args, '--confirmation');
+    try {
+      await request(vehiclePath(id), {
+        method: 'DELETE',
+        headers: confirmation ? { 'x-fleetkeep-confirmation': confirmation } : {}
+      });
+    } 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, null, 2)}\n`);
+        else {
+          process.stdout.write(
+            `No vehicle was deleted. Review the vehicle, then repeat with --confirmation ${error.payload.confirmationToken}\n`
+          );
+        }
+        process.exitCode = 2;
+        return;
+      }
+      throw error;
+    }
+    printJsonOr({ ok: true, deletedVehicleId: id }, jsonOutput, `Vehicle deleted: ${id}`);
+    return;
+  }
+
+  if (args[0] === 'vehicles' && args[1] === 'bulk-add') {
+    const registrations = args.slice(2).filter((arg) => arg !== '--json');
+    if (registrations.length === 0) throw new Error('At least one registration is required.');
+    if (registrations.length > 50) throw new Error('Bulk add accepts at most 50 registrations.');
+    const payload = await request('/api/v1/vehicles/bulk', {
+      method: 'POST',
+      body: { registrations }
+    });
+    if (jsonOutput) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    else {
+      for (const vehicle of payload.created || []) {
+        process.stdout.write(`Added: ${vehicle.registration} (${vehicle.id})\n`);
+      }
+      for (const error of payload.errors || []) {
+        process.stdout.write(`Not added: ${error.reg} (${error.reason})\n`);
+      }
+    }
+    return;
+  }
+
+  if (args[0] === 'drivers' && args[1] === 'list') {
+    const payload = await request('/api/v1/drivers', {});
+    if (jsonOutput) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    else {
+      for (const driver of payload.drivers || []) {
+        const state = driver.revokedAt
+          ? 'access removed'
+          : driver.acceptedAt
+            ? 'active'
+            : 'invitation pending';
+        process.stdout.write(`${driver.id}\t${driver.name}\t${driver.email}\t${state}\n`);
+      }
+    }
+    return;
+  }
+
+  if (args[0] === 'drivers' && args[1] === 'invite') {
+    const email = args[2];
+    const name = option(args, '--name');
+    if (!email || email.startsWith('--')) throw new Error('A driver email address is required.');
+    if (!name) throw new Error('--name is required.');
+    const payload = await request('/api/v1/drivers', {
+      method: 'POST',
+      body: { email, name }
+    });
+    printJsonOr(
+      payload,
+      jsonOutput,
+      `Invitation emailed to ${payload.driver.email} (${payload.driver.id})`
+    );
+    return;
+  }
+
+  if (args[0] === 'drivers' && ['resend', 'revoke'].includes(args[1])) {
+    const id = args[2];
+    if (!id || id.startsWith('--')) throw new Error('A driver ID is required.');
+    const action = args[1];
+    const payload = await request(`/api/v1/drivers/${encodeURIComponent(id)}`, {
+      method: 'POST',
+      body: { action }
+    });
+    printJsonOr(
+      payload,
+      jsonOutput,
+      action === 'resend' ? 'Invitation emailed again.' : 'Driver access removed.'
+    );
+    return;
+  }
+
   if (args[0] === 'import' && args[1] === 'preview') {
     const body = await spreadsheetPayload(args[2]);
     const payload = await request('/api/v1/imports/vehicles/preview', {

package/operations.mjs

@@ -0,0 +1,243 @@
+/** @type {Array<[string, string, string, string, Record<string, unknown>?]>} */
+const definitions = [
+  ['listVehicles', 'GET', '/api/v1/vehicles', 'vehicles:read'],
+  ['addVehicle', 'POST', '/api/v1/vehicles', 'vehicles:write'],
+  ['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 }],
+  ['listVehicleEquipment', 'GET', '/api/v1/vehicles/{id}/checks', 'vehicles:read'],
+  ['addVehicleEquipment', 'POST', '/api/v1/vehicles/{id}/checks', 'vehicles:write'],
+  ['updateVehicleEquipment', 'PATCH', '/api/v1/vehicles/{id}/checks', 'vehicles:write'],
+  [
+    'removeVehicleEquipment',
+    'DELETE',
+    '/api/v1/vehicles/{id}/checks',
+    'vehicles:write',
+    { confirmation: true }
+  ],
+  ['listEquipmentTemplates', 'GET', '/api/v1/equipment/templates', 'vehicles:read'],
+  ['previewEquipmentTemplate', 'POST', '/api/v1/equipment/templates', 'vehicles:read'],
+  ['applyEquipmentTemplate', 'PUT', '/api/v1/equipment/templates', 'vehicles:write'],
+  ['bulkAddVehicles', 'POST', '/api/v1/vehicles/bulk', 'vehicles:write'],
+  ['previewVehicleImport', 'POST', '/api/v1/imports/vehicles/preview', 'vehicles:read'],
+  ['applyVehicleImport', 'POST', '/api/v1/imports/vehicles/apply', 'vehicles:write'],
+  ['getWalkaroundDefinition', 'GET', '/api/v1/operations/walkaround-definition', 'operations:read'],
+  [
+    'listWalkarounds',
+    'GET',
+    '/api/v1/vehicles/{id}/walkarounds',
+    'operations:read',
+    { query: ['limit', 'offset'] }
+  ],
+  [
+    'submitWalkaround',
+    'POST',
+    '/api/v1/vehicles/{id}/walkarounds',
+    'operations:write',
+    { confirmation: true, multipart: true }
+  ],
+  [
+    'getWalkaroundEvidence',
+    'GET',
+    '/api/v1/vehicles/{id}/walkarounds/{checkId}/media/{mediaId}',
+    'operations:read',
+    { binary: true }
+  ],
+  [
+    'listVehicleDocuments',
+    'GET',
+    '/api/v1/vehicles/{id}/documents',
+    'documents:read',
+    { query: ['limit', 'offset'] }
+  ],
+  [
+    'createVehicleDocument',
+    'POST',
+    '/api/v1/vehicles/{id}/documents',
+    'documents:write',
+    { multipart: true }
+  ],
+  [
+    'downloadVehicleDocument',
+    'GET',
+    '/api/v1/vehicles/{id}/documents/{documentId}/download',
+    'documents:read',
+    { binary: true }
+  ],
+  ['getVehiclePhoto', 'GET', '/api/v1/vehicles/{id}/photo', 'vehicles:read', { binary: true }],
+  [
+    'uploadVehiclePhoto',
+    'POST',
+    '/api/v1/vehicles/{id}/photo',
+    'vehicles:write',
+    { multipart: true }
+  ],
+  [
+    'deleteVehiclePhoto',
+    'DELETE',
+    '/api/v1/vehicles/{id}/photo',
+    'vehicles:write',
+    { confirmation: true }
+  ],
+  [
+    'listServiceRecords',
+    'GET',
+    '/api/v1/vehicles/{id}/service-records',
+    'maintenance:read',
+    { query: ['limit', 'offset'] }
+  ],
+  [
+    'createServiceRecord',
+    'POST',
+    '/api/v1/vehicles/{id}/service-records',
+    'maintenance:write',
+    { idempotency: true }
+  ],
+  [
+    'getServiceRecord',
+    'GET',
+    '/api/v1/vehicles/{id}/service-records/{recordId}',
+    'maintenance:read'
+  ],
+  [
+    'updateServiceRecord',
+    'PUT',
+    '/api/v1/vehicles/{id}/service-records/{recordId}',
+    'maintenance:write',
+    { confirmation: true }
+  ],
+  [
+    'deleteServiceRecord',
+    'DELETE',
+    '/api/v1/vehicles/{id}/service-records/{recordId}',
+    'maintenance:write',
+    { confirmation: true }
+  ],
+  ['listMaintenance', 'GET', '/api/v1/operations/maintenance', 'maintenance:read'],
+  ['createMaintenance', 'POST', '/api/v1/vehicles/{id}/maintenance', 'maintenance:write'],
+  ['getMaintenance', 'GET', '/api/v1/operations/maintenance/{eventId}', 'maintenance:read'],
+  ['updateMaintenance', 'PATCH', '/api/v1/operations/maintenance/{eventId}', 'maintenance:write'],
+  [
+    'deleteMaintenance',
+    'DELETE',
+    '/api/v1/operations/maintenance/{eventId}',
+    'maintenance:write',
+    { confirmation: true }
+  ],
+  ['listDefects', 'GET', '/api/v1/operations/defects', 'operations:read'],
+  ['createDefect', 'POST', '/api/v1/operations/defects', 'operations:write'],
+  [
+    'completeMaintenance',
+    'POST',
+    '/api/v1/agent/operations/maintenance/{eventId}/complete',
+    'maintenance:write',
+    { confirmation: true }
+  ],
+  [
+    'completeDefect',
+    'POST',
+    '/api/v1/agent/operations/defects/{eventId}/complete',
+    'operations:write',
+    { confirmation: true }
+  ],
+  ['getReminderSettings', 'GET', '/api/v1/settings/reminders', 'reminders:read'],
+  ['updateReminderSettings', 'PUT', '/api/v1/settings/reminders', 'reminders:write'],
+  ['getVehicleReminderRecipients', 'GET', '/api/v1/vehicles/{id}/reminders', 'reminders:read'],
+  ['replaceVehicleReminderRecipients', 'PUT', '/api/v1/vehicles/{id}/reminders', 'reminders:write'],
+  [
+    'createMobileVehicleReminderRecipient',
+    'POST',
+    '/api/v1/vehicles/{id}/reminders',
+    'reminders:write'
+  ],
+  ['listContacts', 'GET', '/api/v1/contacts', 'reminders:read'],
+  ['createContact', 'POST', '/api/v1/contacts', 'reminders:write'],
+  ['deleteContact', 'DELETE', '/api/v1/contacts/{id}', 'reminders:write', { confirmation: true }],
+  [
+    'previewContactVerification',
+    'POST',
+    '/api/v1/contacts/{id}/verification/preview',
+    'reminders:write'
+  ],
+  [
+    'sendContactVerification',
+    'POST',
+    '/api/v1/contacts/{id}/verification/send',
+    'reminders:write',
+    { confirmation: true, idempotency: true }
+  ],
+  ['listBookings', 'GET', '/api/v1/bookings', 'maintenance:read'],
+  ['createBooking', 'POST', '/api/v1/bookings', 'maintenance:write', { idempotency: true }],
+  ['getBooking', 'GET', '/api/v1/bookings/{id}', 'maintenance:read'],
+  ['updateBookingStatus', 'PATCH', '/api/v1/bookings/{id}', 'maintenance:write'],
+  ['previewGarageEmail', 'POST', '/api/v1/bookings/{id}/garage-email/preview', 'maintenance:write'],
+  [
+    'sendGarageEmail',
+    'POST',
+    '/api/v1/bookings/{id}/garage-email/send',
+    'maintenance:write',
+    { confirmation: true, idempotency: true }
+  ],
+  ['getTollOperations', 'GET', '/api/v1/operations/tolls', 'operations:read'],
+  ['reviewTollCrossing', 'POST', '/api/v1/operations/tolls', 'operations:write'],
+  [
+    'listTollAccounts',
+    'GET',
+    '/api/v1/tolls/accounts',
+    'tolls:read',
+    { query: ['limit', 'offset', 'vehicleId'] }
+  ],
+  ['createTollAccount', 'POST', '/api/v1/tolls/accounts', 'tolls:write', { idempotency: true }],
+  [
+    'listTollTransactions',
+    'GET',
+    '/api/v1/tolls/transactions',
+    'tolls:read',
+    { query: ['limit', 'offset', 'vehicleId'] }
+  ],
+  [
+    'createTollTransaction',
+    'POST',
+    '/api/v1/tolls/transactions',
+    'tolls:write',
+    { idempotency: true }
+  ],
+  ['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'],
+  [
+    'getWexRouteHistory',
+    'GET',
+    '/api/v1/operations/tracking/{vehicleId}/route',
+    'operations:read',
+    { query: ['period'] }
+  ],
+  ['getProfile', 'GET', '/api/v1/profile', 'profile:read'],
+  ['getDriverGuidance', 'GET', '/api/v1/driver-guidance', 'guidance:read'],
+  [
+    'downloadDriverGuidanceDocument',
+    'GET',
+    '/api/v1/driver-guidance/document',
+    'guidance:read',
+    { binary: true }
+  ],
+  ['downloadAccountExport', 'GET', '/api/v1/exports/account.json', 'exports:read'],
+  [
+    'downloadFleetSpreadsheet',
+    'GET',
+    '/api/v1/exports/fleet.xlsx',
+    'exports:read',
+    { binary: true }
+  ]
+];
+
+export const operations = Object.freeze(
+  Object.fromEntries(
+    definitions.map(([id, method, path, scope, options = {}]) => [
+      id,
+      Object.freeze({ id, method, path, scope, ...options })
+    ])
+  )
+);
+
+export const operationList = Object.freeze(Object.values(operations));

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@fleetkeep/cli",
-  "version": "0.1.2",
-  "description": "Preview and apply Fleetkeep fleet spreadsheet imports through the Fleetkeep API",
+  "version": "0.4.0",
+  "description": "Operate every published Fleetkeep API workflow with guarded writes and machine-readable output",
   "type": "module",
   "bin": {
     "fleetkeep": "fleetkeep.mjs"
   },
   "files": [
+    "api-command.mjs",
     "auth.mjs",
     "fleetkeep.mjs",
+    "operations.mjs",
     "README.md"
   ],
   "engines": {