@crvouga/dev-fleet 0.1.0 → 0.3.0

package/src/cli/fleet-sync.ts

@@ -1,5 +1,9 @@
 import { localCheckoutRevision } from '../machine/local-source';
-import { fleet as canonicalDefinition } from '../fleet-config';
+import {
+  definitionSource,
+  fleet as canonicalDefinition,
+  reloadFleet,
+} from '../fleet-config';
 import { managerFailure } from '../manager-failure';
 import { managerText, stdoutColor } from './fleet-sync-output';
 import { managerSchedule, type ScheduleAction } from './fleet-sync-schedule';
@@ -9,12 +13,20 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { existsSync, renameSync } from 'node:fs';
 import {
-  readEnrollment,
   isRevision,
-  saveEnrollment,
   withMachineLock,
   ensurePrivateRoot,
+  type Enrollment,
 } from '../machine/state';
+import { loadEnrollment } from '../state/enrollment';
+import { legacyHome } from '../state/paths';
+import {
+  DIVERGED_REMEDY,
+  refresh,
+  stateContext,
+  type Standing,
+} from '../state/sync';
+import { runRecord } from './fleet-sync-state';
 import { runCommand } from '../runner';
 import type { Runner } from '../types';
 import type { Settings } from './settings';
@@ -23,15 +35,15 @@ import { FleetUsageError } from '../errors';
 import { FleetLockError } from '../machine/lock-error';
 import { selected } from './fleet-sync-remote';
 import { managerIdentity } from './fleet-sync-manager';
-import { trackedScript } from '../remote-bootstrap';
-import { rehome } from './fleet-sync-checkout';
+import { managerRunScript, rehome } from './fleet-sync-checkout';
+import { syncAccounts } from './fleet-sync-accounts';
+import { packageInfo } from '../package-info';
 import {
   forwardingDisabled,
   forwardToManager,
   type ForwardSpawn,
 } from './fleet-sync-forward';
 
-declare const PERSONAL_SOURCE_REVISION: string | null;
 export interface FleetSyncOptions {
   revision?: string;
   dryRun?: boolean;
@@ -42,6 +54,8 @@ export interface FleetSyncOptions {
   node?: string[];
   all?: boolean;
   schedule?: ScheduleAction;
+  /** `accounts`: only the account-derived configuration, on every node. */
+  only?: string;
   /** Internal: this revision already converged the whole fleet, so no canary
    * has to prove it first and every worker converges at once.
    */
@@ -69,9 +83,30 @@ export async function fleetSync(
   if (!(await onManager(run)))
     return offManager(options, settings, run, forward);
   if (options.schedule === 'status') return scheduleStatus(settings, run);
-  const root = machineRoot();
+  if (options.only === 'accounts') return onlyAccounts(options, settings, run);
+  return managerSync(options, settings, {
+    run,
+    root: machineRoot(),
+    restart: () => fleetSync(options, settings, run, forward),
+  });
+}
+
+export interface ManagerSync {
+  run: Runner;
+  /** This machine's run lock and caches. */
+  root: string;
+  /** Starts the request over once the fleet state has been replaced. */
+  restart: () => Promise<CommandOutcome>;
+}
+
+/** fleet-sync on the machine already known to be the manager. */
+export async function managerSync(
+  options: FleetSyncOptions,
+  settings: Settings,
+  { run, root, restart }: ManagerSync
+): Promise<CommandOutcome> {
   await ensurePrivateRoot(root);
-  const state = await readEnrollment(root);
+  const state = await loadEnrollment(legacyHome() ? root : null);
   const revision = await selectedRevision(
     options.revision,
     state?.approvedRevision,
@@ -81,61 +116,100 @@ export async function fleetSync(
   if (!isRevision(revision))
     return actionRequired(
       'FLEET_REVISION_REQUIRED',
-      'Select an approved full SHA with --revision, or use a published package containing clean source provenance.'
+      'No revision to converge to. Run the published dev-fleet package (it names the commit it was built from), or select a full commit SHA with --revision.'
     );
   if (options.schedule)
     return scheduleRequest(options, revision, settings, run);
   const rehomed = await rehome(
     options,
-    { revision, workspace: settings.workspace },
+    { revision, workspace: settings.workspace, root },
     run
   );
-  if (rehomed) return rehomed;
-  const request = { ...options, revision };
-  if (request.dryRun) return selected(request, settings, run);
-  // Applies without a confirmation prompt; --dry-run is the preview.
-  request.apply = true;
-  request.yes = true;
-  if (interactive(options)) {
-    await enrollManager(settings.config, run);
-    // Needed to hand each node its own Vault token; nodes report any gap.
-    await authorizeManager({ interactive: true }, run);
-    request.interactiveAuthorization = true;
+  if (rehomed === 'unavailable')
+    return actionRequired(
+      'FLEET_SOURCE_UNAVAILABLE',
+      `Revision ${revision} could not be taken from ${canonicalDefinition.source.repository}, so nothing was changed. Check the network and Git access to it, and that the revision is pushed there; fleet-sync never converges from the package or working tree it was started in.`,
+      revision
+    );
+  if (rehomed !== 'here') return rehomed;
+  if (options.dryRun) return selected({ ...options, revision }, settings, run);
+  // The bucket is the source of truth: a run starts from its version of the
+  // configuration, the roster and the approval, not from a stale local copy.
+  const fresh = await refresh(stateContext(run));
+  if (fresh.standing === 'diverged')
+    return actionRequired('FLEET_STATE_DIVERGED', DIVERGED_REMEDY, revision);
+  if (fresh.replaced) {
+    // Everything read so far came from the stale copy, the manager's own
+    // identity included.
+    reloadFleet();
+    return restart();
   }
-  return applyLocked(root, state, request, { settings, run });
+  return authorizeAndApply(root, state, options, {
+    settings,
+    run,
+    revision,
+    standing: fresh.standing,
+  });
+}
+
+interface ApplyContext {
+  settings: Settings;
+  run: Runner;
+  revision: string;
+  /** How the fleet state stood with the bucket when this run started. */
+  standing: Standing;
+}
+
+/** Applies without a confirmation prompt; --dry-run is the preview. */
+async function authorizeAndApply(
+  root: string,
+  state: Enrollment | null,
+  options: FleetSyncOptions,
+  context: ApplyContext
+): Promise<CommandOutcome> {
+  const { settings, run, revision } = context;
+  const request = { ...options, revision, apply: true, yes: true };
+  if (!interactive(options)) return applyLocked(root, state, request, context);
+  await enrollManager(settings.config, run);
+  // Needed to hand each node its own Vault token; nodes report any gap.
+  await authorizeManager({ interactive: true }, run);
+  return applyLocked(
+    root,
+    state,
+    { ...request, interactiveAuthorization: true },
+    context
+  );
 }
 
-/** Records the approved revision, converges, then records what was applied. */
+/** Records the approved revision, converges, records what was applied, then
+ * uploads the fleet state: the report says whether the bucket holds it.
+ */
 function applyLocked(
   root: string,
-  state: Awaited<ReturnType<typeof readEnrollment>>,
+  state: Enrollment | null,
   request: FleetSyncOptions & { revision: string },
-  context: { settings: Settings; run: Runner }
+  context: ApplyContext
 ): Promise<CommandOutcome> {
-  const { revision } = request;
-  const { settings, run } = context;
+  const { settings, run, revision } = context;
+  const record = runRecord(state, revision, {
+    context: stateContext(run),
+    standing: context.standing,
+    ...(definitionSource().kind === 'file'
+      ? { definition: JSON.stringify(canonicalDefinition, null, 2) + '\n' }
+      : {}),
+  });
   return withMachineLock(root, async () => {
-    const approval = {
-      ...state,
-      version: 1 as const,
-      id: 'manager',
-      approvedRevision: revision,
-    };
-    await saveEnrollment(root, approval);
-    const result = await selected(
-      { ...request, rolledOut: state?.appliedRevision === revision },
-      settings,
-      run
-    );
-    if (result.exitCode === 0)
-      await saveEnrollment(root, {
-        ...approval,
-        appliedRevision: revision,
-        ...(state?.appliedRevision && state.appliedRevision !== revision
-          ? { previousRevision: state.appliedRevision }
-          : {}),
-      });
-    return result;
+    record.approve();
+    try {
+      return await selected(
+        { ...request, rolledOut: state?.appliedRevision === revision },
+        settings,
+        run,
+        (report) => record.settle(report.ok)
+      );
+    } finally {
+      await record.abandon();
+    }
   }).catch((error: unknown) => {
     if (error instanceof FleetLockError)
       return actionRequired(
@@ -175,12 +249,7 @@ async function offManager(
       revision ?? null
     );
   const runScript = revision
-    ? await trackedScript(
-        settings.workspace,
-        revision,
-        'bootstrap/fleet-manager-run.sh',
-        run
-      )
+    ? await managerRunScript(settings.workspace, revision, run)
     : null;
   return forwardToManager(definition, options, revision, {
     spawn: forward,
@@ -224,11 +293,43 @@ function validate(options: FleetSyncOptions): void {
     throw new FleetUsageError(
       '--revision requires an exact lowercase 40-character commit SHA.'
     );
+  validateOnly(options);
   if (options.dryRun && (options.apply || options.yes))
     throw new FleetUsageError(
       '--dry-run cannot be combined with apply confirmation.'
     );
 }
+function validateOnly(options: FleetSyncOptions): void {
+  if (options.only !== undefined && options.only !== 'accounts')
+    throw new FleetUsageError('--only takes one scope: accounts.');
+  if (options.only && (options.dryRun || options.schedule))
+    throw new FleetUsageError(
+      '--only accounts applies at once; it takes neither --dry-run nor --schedule.'
+    );
+}
+
+/** `--only accounts`: workers keep the revision they run; only their
+ * accounts change.
+ */
+async function onlyAccounts(
+  options: FleetSyncOptions,
+  settings: Settings,
+  run: Runner
+): Promise<CommandOutcome> {
+  const root = machineRoot();
+  await ensurePrivateRoot(root);
+  const state = await loadEnrollment(legacyHome() ? root : null);
+  const revision =
+    state?.approvedRevision ??
+    (await selectedRevision(options.revision, undefined, settings, run));
+  if (!isRevision(revision))
+    return actionRequired(
+      'FLEET_REVISION_REQUIRED',
+      'No revision is applied yet. Run a full fleet-sync first.'
+    );
+  return syncAccounts(options, settings, { revision, run });
+}
+
 function interactive(options: FleetSyncOptions): boolean {
   return (
     ![
@@ -242,10 +343,11 @@ function interactive(options: FleetSyncOptions): boolean {
   );
 }
 
+/** The commit an installed package was published from: the version of
+ * dev-fleet you run is the revision the fleet moves to.
+ */
 function packageRevision(): string | undefined {
-  return typeof PERSONAL_SOURCE_REVISION === 'string'
-    ? PERSONAL_SOURCE_REVISION
-    : undefined;
+  return packageInfo().revision ?? undefined;
 }
 
 async function scheduleRequest(

package/src/cli/fleet.ts

@@ -89,15 +89,17 @@ async function register(
   options: CliOptions
 ): Promise<CommandOutcome> {
   const node = nodeFromOptions(options);
-  const config = await addNode(settings.config, node, options.apply === true);
+  const added = await addNode(settings.config, node, options.apply === true);
   return result({
     version: 1,
     command: 'add',
     ok: true,
     applied: options.apply === true,
     path: settings.config,
+    // How the fleet state stands with the bucket after this change.
+    ...(added.standing ? { state: added.standing } : {}),
     node,
-    nodes: config.nodes,
+    nodes: added.roster.nodes,
     next: options.apply
       ? 'Run fleet-nodes --onboard, then fleet-status --json.'
       : 'Review this preview, then repeat with --apply --yes.',

package/src/cli/managed-health.ts

@@ -6,7 +6,7 @@ import { enrolledRoster } from '../definition';
 import type { Tailnet } from '../tailscale';
 import type { FleetNode } from '../types';
 import {
-  PUBLIC_HUB_URL,
+  publicHubUrl,
   verifyBeszel,
   type BeszelRequest,
 } from '../monitoring/beszel';
@@ -122,7 +122,7 @@ async function hubReachable(
  */
 async function publicEndpoint(fetcher: typeof fetch): Promise<Check> {
   try {
-    const response = await fetcher(`${PUBLIC_HUB_URL}/api/health`, {
+    const response = await fetcher(`${publicHubUrl()}/api/health`, {
       redirect: 'error',
       signal: AbortSignal.timeout(10_000),
     });
@@ -130,7 +130,7 @@ async function publicEndpoint(fetcher: typeof fetch): Promise<Check> {
       return {
         id: 'beszel:public-endpoint',
         status: 'pass',
-        summary: `Dashboard answers publicly at ${PUBLIC_HUB_URL}.`,
+        summary: `Dashboard answers publicly at ${publicHubUrl()}.`,
       };
   } catch {
     /* Connection details are not evidence; fall through. */
@@ -140,7 +140,7 @@ async function publicEndpoint(fetcher: typeof fetch): Promise<Check> {
     status: 'warn',
     summary: 'BESZEL_PUBLIC_ENDPOINT_OFFLINE',
     remedy: {
-      action: `${PUBLIC_HUB_URL} did not answer. Create the Cloudflare tunnel and store its token in the fleet's secrets, then run fleet-sync on the manager so the hub starts its Cloudflare connector. The private dashboard is unaffected.`,
+      action: `${publicHubUrl()} did not answer. Create the Cloudflare tunnel and store its token in the fleet's secrets, then run fleet-sync on the manager so the hub starts its Cloudflare connector. The private dashboard is unaffected.`,
     },
   };
 }

package/src/cli/node-sync.ts

@@ -2,6 +2,7 @@ import { join } from 'node:path';
 import { configureWorkspace } from '../configure';
 import { runCommand } from '../runner';
 import { FleetUsageError } from '../errors';
+import { packageInfo } from '../package-info';
 import type { Runner } from '../types';
 import type { Settings } from './settings';
 import type { CommandOutcome } from './contracts';
@@ -24,6 +25,12 @@ export async function syncNode(
       'Codex proxy node sync requires macOS/Linux/WSL. Use dev-fleet commands for native Windows configuration.'
     );
   const node = nodeId(options.id);
+  // An installed package is not a checkout, and the Git repository around it
+  // is the operator's own project: its HEAD is not a dev-fleet revision.
+  if (packageInfo().revision)
+    throw new FleetUsageError(
+      'fleet-node-sync works on a checkout of dev-fleet. Run fleet-sync instead: it converges this machine from a checkout it owns.'
+    );
   const head = await run(['git', 'rev-parse', '--verify', 'HEAD'], {
     cwd: settings.workspace,
   });

package/src/cli/program.ts

@@ -13,6 +13,14 @@ export interface Release {
   version: string;
   /** ISO timestamp recorded when this distribution was built; null for source runs. */
   releasedAt: string | null;
+  /** The commit a published package was built from: what fleet-sync run from
+   * it converges every machine to. Absent for source runs.
+   */
+  revision?: string | null;
+  /** The issue tracker of the package: where its users report a defect or
+   * ask for a feature.
+   */
+  issues?: string | null;
 }
 
 export const GLOBAL_OPTIONS = [
@@ -23,7 +31,8 @@ export const GLOBAL_OPTIONS = [
   { flag: '--non-interactive', description: 'Never open interactive prompts' },
   {
     flag: '--workspace <path>',
-    description: 'Existing manager checkout; does not clone or change it',
+    description:
+      'A dev-fleet checkout to run from instead of this package (development); does not clone or change it',
   },
   { flag: '--config <path>', description: 'Local, secret-free fleet roster' },
 ];
@@ -34,8 +43,10 @@ export const SOURCE_VERSION = '0.0.0-development';
 export function releaseLabel(release: Release): string {
   if (release.releasedAt)
     return `${release.version} (released ${release.releasedAt})`;
-  return release.version === SOURCE_VERSION
-    ? `${release.version} (unreleased source build)`
+  if (release.version === SOURCE_VERSION)
+    return `${release.version} (unreleased source build)`;
+  return release.revision
+    ? `${release.version} (commit ${release.revision})`
     : release.version;
 }
 
@@ -63,9 +74,14 @@ function createProgram(
       '',
       `Release: ${releaseLabel(release)}`,
       'Groups: fleet-* developer computers · t3-* T3 provider instances · cliproxy the CLI proxy service.',
-      'Apply on invocation (--dry-run previews): fleet-node-sync, t3-apply, t3-cleanup. fleet-sync confirms interactively or with --apply --yes.',
+      'Apply on invocation (--dry-run previews): fleet-node-sync, t3-apply, t3-cleanup. fleet-sync applies on invocation too; --apply --yes is still accepted.',
       'Preview until --apply --yes: fleet-repair, fleet-node-add. --json does not make a command read-only.',
       'Agents: devfleet commands --json. Menu: devfleet --interactive.',
+      ...(release.issues
+        ? [
+            `Bugs and feature requests: ${release.issues}. Report them there; never patch the installed package.`,
+          ]
+        : []),
     ].join('\n')
   );
   return program;

package/src/cli/project.ts

@@ -0,0 +1,51 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { record } from '../config';
+
+/** The file a project keeps its fleet configuration in. */
+export const PROJECT_CONFIG = 'fleet.json';
+
+/** Another tool's fleet.json is not this one: a fleet configuration is a JSON
+ * object that names a manager. Whether it is a valid one is said later, with
+ * the file's path, by whatever reads it.
+ */
+function fleetConfiguration(path: string): boolean {
+  try {
+    const value: unknown = JSON.parse(readFileSync(path, 'utf8'));
+    return record(value) && record(value['manager']);
+  } catch {
+    return false;
+  }
+}
+
+/** The fleet.json of the project a command is run from: the closest one in
+ * the working directory or above it, or null.
+ */
+export function projectConfig(cwd: string): string | null {
+  let current = resolve(cwd);
+  while (true) {
+    const candidate = join(current, PROJECT_CONFIG);
+    if (fleetConfiguration(candidate)) return candidate;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/** A fleet is a project of your own: a fleet.json in Git, and the devfleet
+ * CLI run from inside it. This names that file for the whole command, and
+ * for everything the command starts in another directory (fleet-sync re-runs
+ * itself from a checkout of the revision). `DEVFLEET_CONFIG` names a file
+ * elsewhere and wins. Only the CLI does this: launchers and scheduled jobs
+ * run in directories that belong to other projects and read the copy
+ * fleet-sync installed.
+ */
+export function useProjectConfig(
+  env: NodeJS.ProcessEnv = process.env,
+  cwd = process.cwd()
+): string | null {
+  const named = env['DEVFLEET_CONFIG'];
+  const path = named ? resolve(cwd, named) : projectConfig(cwd);
+  if (path) env['DEVFLEET_CONFIG'] = path;
+  return path;
+}

package/src/cli/register-fleet.ts

@@ -6,6 +6,8 @@ import { resolveSettings } from './settings';
 import { executeFleet } from './fleet';
 import { fleetSync, type FleetSyncOptions } from './fleet-sync';
 import { syncNode, type NodeSyncOptions } from './node-sync';
+import { fleetState, type FleetStateOptions } from './fleet-state';
+import { fleetAccounts, type FleetAccountsOptions } from './fleet-accounts';
 
 type Complete = (outcome: CommandOutcome) => void;
 
@@ -172,7 +174,7 @@ function registerSync({ program, defaults, complete }: Registration) {
     )
     .option(
       '--revision <sha>',
-      'Approve an exact source commit; defaults to published release or current canonical checkout'
+      'Converge to an exact source commit; defaults to the commit the dev-fleet package you run was published from'
     )
     .option(
       '--node <id>',
@@ -197,6 +199,10 @@ function registerSync({ program, defaults, complete }: Registration) {
       '--schedule <action>',
       'Manager-only schedule: enable, pause, resume, disable, status'
     )
+    .option(
+      '--only <scope>',
+      'accounts: only the account-derived configuration, on every node at once, without a full sync'
+    )
     .action(async (_options, command: Command) => {
       const options = command.optsWithGlobals<
         FleetSyncOptions & Partial<Settings>
@@ -228,6 +234,54 @@ function registerSync({ program, defaults, complete }: Registration) {
     });
 }
 
+function registerState({ program, complete }: Registration) {
+  program
+    .command('fleet-state')
+    .description(
+      'Show where the fleet state is kept and whether the bucket holds it; flags connect, upload and restore'
+    )
+    .option(
+      '--init',
+      'Connect the bucket: restore the fleet state from it, or seed it from this machine, and save its credentials for runs this machine starts by itself'
+    )
+    .option(
+      '--bucket <name>',
+      'With --init, when no fleet.json names the bucket: S3-compatible bucket name'
+    )
+    .option(
+      '--endpoint <url>',
+      'With --init: https origin of the S3 service; omit for AWS S3'
+    )
+    .option('--region <name>', 'With --init: bucket region, such as auto')
+    .option('--prefix <prefix>', 'With --init: key prefix; default dev-fleet')
+    .option(
+      '--directory <path>',
+      'With --init: replicate to a directory instead of a bucket'
+    )
+    .option(
+      '--import <path>',
+      'Store a fleet configuration without running fleet-sync'
+    )
+    .option(
+      '--export',
+      'Print the stored fleet configuration: the one fleet-sync last applied'
+    )
+    .option('--example', 'Print an example fleet.json to start a project from')
+    .option('--push', 'Upload this machine’s changes to the bucket')
+    .option(
+      '--restore',
+      'Replace this machine’s copy with the bucket’s version'
+    )
+    .option('--yes', 'With --restore: discard changes the bucket does not hold')
+    .addHelpText(
+      'after',
+      '\nRead-only without a flag. The bucket is the one named under "state" in fleet.json. Every command reads its credentials from DEVFLEET_BUCKET_ACCESS_KEY_ID and DEVFLEET_BUCKET_SECRET_ACCESS_KEY; --init also asks on the terminal. They are never taken from arguments.'
+    )
+    .action(async (_options, command: Command) => {
+      complete(await fleetState(command.optsWithGlobals<FleetStateOptions>()));
+    });
+}
+
 export function registerFleet(
   program: Command,
   defaults: Settings,
@@ -241,6 +295,37 @@ export function registerFleet(
     'List computers visible through Tailscale, including offline devices'
   );
   registerSync(registration);
+  registerState(registration);
   registerRepair(registration);
   registerNodes(registration);
+  registerAccounts(registration);
+}
+
+function registerAccounts({ program, defaults, complete }: Registration) {
+  program
+    .command('fleet-accounts [args...]')
+    .description(
+      'List the provider accounts signed in on the CLI proxy and their state; add, sign in again or remove one'
+    )
+    .option('--diff', 'Also compare what this machine offers with the roster')
+    .option('--add', 'Sign a new account in: --add PROVIDER')
+    .option('--relogin', 'Sign one account in again: --relogin PROVIDER INDEX')
+    .option('--remove', 'Remove one account: --remove PROVIDER INDEX')
+    .option(
+      '--remove-native-logins',
+      'Remove provider logins agent CLIs keep outside the proxy on this machine; needs --yes'
+    )
+    .option('--yes', 'Confirm --remove-native-logins')
+    .action(async (args: string[], _options, command: Command) => {
+      const options = command.optsWithGlobals<
+        FleetAccountsOptions & CliOptions
+      >();
+      complete(
+        await fleetAccounts(
+          options,
+          args,
+          await withSettings(defaults, options)
+        )
+      );
+    });
 }

package/src/cli/registry.ts

@@ -59,10 +59,37 @@ export const COMMANDS: CommandSpec[] = [
     [
       'fleet-sync',
       'Synchronize the enrolled Ubuntu fleet',
-      'Manager push to all enrolled Ubuntu nodes at one approved revision over verified SSH; interactive confirmation or --apply --yes. Readiness is verified separately.',
+      'Manager push to all enrolled Ubuntu nodes at one approved revision over verified SSH: the commit the dev-fleet package was published from, with the fleet.json of the project it is run from. Interactive confirmation or --apply --yes. Readiness is verified separately.',
       ['ubuntu', 'enrollment', 'converge', 'sync'],
       true,
     ],
+    [
+      'fleet-state',
+      'Check the fleet state and its bucket',
+      'Read-only: where the fleet configuration, the roster and the approved revision are kept on this manager, and whether the bucket holds the same version. --example prints a fleet.json to start a project from; --export prints the configuration fleet-sync last applied; --import PATH stores one.',
+      ['state', 'bucket', 's3', 'backup', 'litestream', 'configuration'],
+    ],
+    [
+      'fleet-state --init',
+      'Connect the bucket and restore or seed the fleet state',
+      'Restore the fleet state from the bucket fleet.json names under "state" (or the one given with --bucket/--endpoint or --directory), or seed an empty bucket from this machine, and save the bucket and its credentials on this machine for runs it starts by itself. Credentials come from the environment or a terminal prompt.',
+      ['state', 'bucket', 's3', 'setup', 'restore', 'new manager'],
+      true,
+    ],
+    [
+      'fleet-state --push',
+      'Upload fleet state changes to the bucket',
+      'Upload changes this manager made while the bucket was unreachable. Refuses when the bucket has changed since.',
+      ['state', 'bucket', 'upload', 'replicate'],
+      true,
+    ],
+    [
+      'fleet-state --restore',
+      'Replace the local fleet state with the bucket’s',
+      'Discard this manager’s copy of the fleet state and download the bucket’s version. Needs --yes when this machine has changes the bucket does not hold.',
+      ['state', 'bucket', 'restore', 'recover', 'disposable'],
+      true,
+    ],
     [
       'fleet-node-sync',
       'Sync this node',
@@ -108,6 +135,19 @@ export const COMMANDS: CommandSpec[] = [
       ['onboarding', 'register', 'new', 'setup', 'add'],
       true,
     ],
+    [
+      'fleet-accounts',
+      'List provider accounts and their state',
+      'Read-only: the provider accounts signed in on the CLI proxy (provider, index, label, state, when a cooldown clears), the roster version and the proxy:account:<provider> checks. --diff also compares what this machine offers with the roster.',
+      ['accounts', 'providers', 'login', 'quota', 'cooldown', 'roster'],
+    ],
+    [
+      'fleet-accounts --add',
+      'Add, sign in again or remove a provider account',
+      '--add PROVIDER, --relogin PROVIDER INDEX or --remove PROVIDER INDEX changes one account on the CLI proxy (signing in is the only manual step), then propagates the accounts to every node with fleet-sync --only accounts.',
+      ['accounts', 'login', 'relogin', 'remove', 'add', 'sign in'],
+      true,
+    ],
   ]),
   ...group('T3', [
     [