From 5b5fbb887c1fc41e495667dc33f9536ba680d119 Mon Sep 17 00:00:00 2001
From: William Valentin <william.valentin.info@gmail.com>
Date: Mon, 16 Feb 2026 18:30:17 -0800
Subject: [PATCH] feat(cli): add onboard alias for setup wizard

---
 README.md             |  1 +
 docs/plans/state.json | 14 ++++++++++++++
 src/cli/index.test.ts |  2 ++
 src/cli/index.ts      |  2 ++
 src/cli/onboard.ts    | 14 ++++++++++++++
 5 files changed, 33 insertions(+)
 create mode 100644 src/cli/onboard.ts

diff --git a/README.md b/README.md
index f5b4b1e..b4b2500 100644
--- a/README.md
+++ b/README.md
@@ -73,6 +73,7 @@ Flynn provides a full CLI via the `flynn` binary (or `npx tsx src/cli/index.ts`
 | `flynn backup` | Create a snapshot backup and optionally upload to MinIO |
 | `flynn completion <shell>` | Generate shell completions (bash, zsh, fish) |
 | `flynn setup` | Interactive setup wizard |
+| `flynn onboard` | Guided onboarding alias for setup wizard |
 | `flynn gmail-auth` | Authenticate with Gmail via OAuth2 |
 | `flynn gcal-auth` | Authenticate with Google Calendar via OAuth2 |
 | `flynn skills` | List/install/manage skills |
diff --git a/docs/plans/state.json b/docs/plans/state.json
index a838dc2..49b2ee1 100644
--- a/docs/plans/state.json
+++ b/docs/plans/state.json
@@ -160,6 +160,20 @@
       ],
       "test_status": "pnpm test:run src/tools/builtin/browser/tools.test.ts src/tools/policy.test.ts passing"
     },
+    "onboard-command-alias-for-setup-wizard": {
+      "status": "completed",
+      "date": "2026-02-17",
+      "updated": "2026-02-17",
+      "summary": "Added a first-class `flynn onboard` CLI entrypoint as an explicit guided-onboarding alias to the setup wizard (`runSetup`), improving onboarding discoverability and OpenClaw-style command-surface parity without changing setup behavior.",
+      "files_modified": [
+        "src/cli/onboard.ts",
+        "src/cli/index.ts",
+        "src/cli/index.test.ts",
+        "README.md",
+        "docs/plans/state.json"
+      ],
+      "test_status": "pnpm test:run src/cli/index.test.ts + pnpm typecheck passing"
+    },
     "browser-tools-activation-clarity": {
       "status": "completed",
       "date": "2026-02-17",
diff --git a/src/cli/index.test.ts b/src/cli/index.test.ts
index fcb19b9..c43a94a 100644
--- a/src/cli/index.test.ts
+++ b/src/cli/index.test.ts
@@ -14,6 +14,8 @@ describe('CLI program', () => {
     expect(commandNames).toContain('config');
     expect(commandNames).toContain('skills');
     expect(commandNames).toContain('backup');
+    expect(commandNames).toContain('setup');
+    expect(commandNames).toContain('onboard');
 
     expect(commandNames).toContain('openai-auth');
     expect(commandNames).toContain('openai-key');
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 2a30f14..b2e23d9 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -17,6 +17,7 @@ import { registerConfigCommand } from './config-cmd.js';
 import { registerTuiCommand } from './tui.js';
 import { registerCompletionCommand } from './completion.js';
 import { registerSetupCommand } from './setup.js';
+import { registerOnboardCommand } from './onboard.js';
 import { registerGmailAuthCommand } from './gmail-auth.js';
 import { registerGcalAuthCommand } from './gcal-auth.js';
 import { registerGdocsAuthCommand } from './gdocs-auth.js';
@@ -45,6 +46,7 @@ export function createProgram(): Command {
   registerConfigCommand(program);
   registerCompletionCommand(program);
   registerSetupCommand(program);
+  registerOnboardCommand(program);
   registerGmailAuthCommand(program);
   registerGcalAuthCommand(program);
   registerGdocsAuthCommand(program);
diff --git a/src/cli/onboard.ts b/src/cli/onboard.ts
new file mode 100644
index 0000000..a4bf2bc
--- /dev/null
+++ b/src/cli/onboard.ts
@@ -0,0 +1,14 @@
+import type { Command } from 'commander';
+import { getConfigPath } from './shared.js';
+import { runSetup } from './setup.js';
+
+export function registerOnboardCommand(program: Command): void {
+  program
+    .command('onboard')
+    .description('Run guided onboarding (alias for setup wizard)')
+    .option('-c, --config <path>', 'Config file path')
+    .action(async (opts: { config?: string }) => {
+      const configPath = opts.config ?? getConfigPath();
+      await runSetup(configPath);
+    });
+}