chore(cli): remove deprecated 'ao init' command (#1438)

* chore(cli): remove deprecated 'ao init' command

Delete the `init` command and its deprecation shim. `ao start` already
auto-creates the config on first run in an unconfigured repo, so the
separate entry point is redundant.

- Remove `packages/cli/src/commands/init.ts` and its test.
- Remove `registerInit` call from the CLI program.
- Drop `createConfigOnly()` from start.ts (only the init shim used it);
  export `autoCreateConfig` so the existing default-config test can
  invoke it directly.
- Update user-facing "Run `ao init` first" messages in `verify`/`status`
  to point to `ao start`.
- Refresh stale `ao init` references in ao-doctor, onboarding test,
  openclaw setup doc, and the config/types doc comments.

Closes #1420

* docs: remove ao init website docs

Agent-Logs-Url: https://github.com/ComposioHQ/agent-orchestrator/sessions/41663963-ca49-4673-982f-ca10dee68d31

Co-authored-by: miniMaddy <77185670+miniMaddy@users.noreply.github.com>

---------

Co-authored-by: Prateek <karnalprateek@gmail.com>
Co-authored-by: iamasx <adilshaikh4064@gmail.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: miniMaddy <77185670+miniMaddy@users.noreply.github.com>

.changeset/remove-deprecated-ao-init.md

@@ -0,0 +1,5 @@
+---
+"@aoagents/ao-cli": minor
+---
+
+Remove the deprecated `ao init` command. Use `ao start` instead — it auto-creates the config on first run in an unconfigured repo.

docs/openclaw-plugin-setup.md

@@ -5,7 +5,7 @@ How to set up the Agent Orchestrator (AO) plugin for OpenClaw so the AI bot dele
 ## Prerequisites
 
 - [OpenClaw](https://openclaw.ai) installed and running
-- [Agent Orchestrator](https://github.com/ComposioHQ/agent-orchestrator) installed with `ao init` completed in your repo
+- [Agent Orchestrator](https://github.com/ComposioHQ/agent-orchestrator) installed with `ao start` completed in your repo
 - `ao`, `gh`, `tmux`, and `node` available in PATH
 - GitHub CLI (`gh`) authenticated
 

packages/cli/__tests__/commands/init.test.ts

@@ -1,28 +0,0 @@
-import { describe, it, expect } from "vitest";
-
-import { Command } from "commander";
-import { registerInit } from "../../src/commands/init.js";
-
-describe("init command", () => {
-  it("registers as a deprecated command", () => {
-    const program = new Command();
-    registerInit(program);
-
-    const initCmd = program.commands.find((c) => c.name() === "init");
-    expect(initCmd).toBeDefined();
-    expect(initCmd!.description()).toContain("deprecated");
-  });
-
-  it("has no --output, --auto, or --smart flags", () => {
-    const program = new Command();
-    registerInit(program);
-
-    const initCmd = program.commands.find((c) => c.name() === "init");
-    expect(initCmd).toBeDefined();
-
-    const optionNames = initCmd!.options.map((o) => o.long);
-    expect(optionNames).not.toContain("--output");
-    expect(optionNames).not.toContain("--auto");
-    expect(optionNames).not.toContain("--smart");
-  });
-});

packages/cli/__tests__/commands/start.test.ts

@@ -260,7 +260,7 @@ vi.mock("node:process", async (importOriginal) => {
 // ---------------------------------------------------------------------------
 
 import { Command } from "commander";
-import { registerStart, registerStop, createConfigOnly } from "../../src/commands/start.js";
+import { registerStart, registerStop, autoCreateConfig } from "../../src/commands/start.js";
 
 let tmpDir: string;
 let program: Command;
@@ -2133,7 +2133,7 @@ describe("start command — autoCreateConfig", () => {
     const callerContext = await import("../../src/lib/caller-context.js");
     vi.spyOn(callerContext, "isHumanCaller").mockReturnValue(false);
 
-    await createConfigOnly();
+    await autoCreateConfig(tmpDir);
 
     const configPath = join(tmpDir, "agent-orchestrator.yaml");
     expect(existsSync(configPath)).toBe(true);

packages/cli/src/assets/scripts/ao-doctor.sh

@@ -349,7 +349,7 @@ check_config_dirs() {
   local config_path data_dir worktree_dir
   config_path="$(find_config || true)"
   if [ -z "$config_path" ]; then
-    warn "No agent-orchestrator config was found. Fix: run ao init --auto in a target repo"
+    warn "No agent-orchestrator config was found. Fix: run ao start in a target repo"
     return
   fi
 

packages/cli/src/commands/init.ts

@@ -1,18 +0,0 @@
-import chalk from "chalk";
-import type { Command } from "commander";
-
-export function registerInit(program: Command): void {
-  program
-    .command("init")
-    .description("[deprecated] Use 'ao start' instead — it auto-creates config on first run")
-    .action(async () => {
-      console.log(
-        chalk.yellow(
-          "⚠ 'ao init' is deprecated. Use 'ao start' instead.\n" +
-            "  'ao start' auto-detects your project and creates the config.\n",
-        ),
-      );
-      const { createConfigOnly } = await import("./start.js");
-      await createConfigOnly();
-    });
-}

packages/cli/src/commands/start.ts

@@ -464,7 +464,7 @@ async function cloneRepo(parsed: ParsedRepoUrl, targetDir: string, cwd: string):
  * Detects environment, project type, and generates config with smart defaults.
  * Returns the loaded config.
  */
-async function autoCreateConfig(workingDir: string): Promise<OrchestratorConfig> {
+export async function autoCreateConfig(workingDir: string): Promise<OrchestratorConfig> {
   console.log(chalk.bold.cyan("\n  Agent Orchestrator — First Run Setup\n"));
   console.log(chalk.dim("  Detecting project and generating config...\n"));
 
@@ -760,14 +760,6 @@ async function addProjectToConfig(
   return projectId;
 }
 
-/**
- * Create config without starting dashboard/orchestrator.
- * Used by deprecated `ao init` wrapper.
- */
-export async function createConfigOnly(): Promise<void> {
-  await autoCreateConfig(cwd());
-}
-
 /**
  * Start dashboard server in the background.
  * Returns the child process handle for cleanup.

packages/cli/src/commands/status.ts

@@ -348,7 +348,7 @@ export function registerStatus(program: Command): void {
         try {
           config = loadConfig();
         } catch {
-          console.log(chalk.yellow("No config found. Run `ao init` first."));
+          console.log(chalk.yellow("No config found. Run `ao start` first."));
           console.log(chalk.dim("Falling back to session discovery...\n"));
           await showFallbackStatus();
           return;

packages/cli/src/commands/verify.ts

@@ -29,7 +29,7 @@ function resolveProject(
 
   const ids = Object.keys(config.projects);
   if (ids.length === 0) {
-    console.error(chalk.red("No projects configured. Run `ao init` first."));
+    console.error(chalk.red("No projects configured. Run `ao start` first."));
     process.exit(1);
   }
   if (ids.length > 1) {
@@ -91,7 +91,7 @@ export function registerVerify(program: Command): void {
         try {
           config = loadConfig();
         } catch {
-          console.error(chalk.red("No config found. Run `ao init` first."));
+          console.error(chalk.red("No config found. Run `ao start` first."));
           process.exit(1);
           return;
         }

packages/cli/src/lib/web-dir.ts

@@ -44,7 +44,6 @@ export const MAX_PORT_SCAN = 100;
 /**
  * Find the first available port starting from `start`, scanning upward.
  * Returns `null` if no free port is found within `maxScan` attempts.
- * Shared between `ao init` and `ao start <url>`.
  */
 export async function findFreePort(start: number, maxScan = MAX_PORT_SCAN): Promise<number | null> {
   for (let port = start; port < start + maxScan; port++) {

packages/cli/src/program.ts

@@ -1,5 +1,4 @@
 import { Command } from "commander";
-import { registerInit } from "./commands/init.js";
 import { registerStatus } from "./commands/status.js";
 import { registerSpawn, registerBatchSpawn } from "./commands/spawn.js";
 import { registerSession } from "./commands/session.js";
@@ -29,7 +28,6 @@ export function createProgram(): Command {
     .description("Agent Orchestrator — manage parallel AI coding agents")
     .version(getCliVersion());
 
-  registerInit(program);
   registerStart(program);
   registerStop(program);
   registerStatus(program);

packages/core/src/config.ts

@@ -995,7 +995,7 @@ export function validateConfig(raw: unknown): OrchestratorConfig {
   return config;
 }
 
-/** Get the default config (useful for `ao init`) */
+/** Get the default config (useful for first-run setup) */
 export function getDefaultConfig(): OrchestratorConfig {
   return validateConfig({
     projects: {},

packages/core/src/types.ts

@@ -522,7 +522,7 @@ export interface Agent {
 
   /**
    * Optional: Set up agent-specific hooks/config in the workspace for automatic metadata updates.
-   * Called once per workspace during ao init/start and when creating new worktrees.
+   * Called once per workspace during ao start and when creating new worktrees.
    *
    * Each agent plugin implements this for their own config format:
    * - Claude Code: writes .claude/settings.json with PostToolUse hook
@@ -603,7 +603,7 @@ export interface AgentLaunchConfig {
 export interface WorkspaceHooksConfig {
   /** Data directory where session metadata files are stored */
   dataDir: string;
-  /** Optional session ID (may not be known at ao init time) */
+  /** Optional session ID (may not be known at workspace setup time) */
   sessionId?: string;
 }
 

tests/integration/onboarding-test.sh

@@ -81,7 +81,7 @@ end_step "Step 4: Configuration created"
 
 # Step 5: Verify config is valid
 start_step "Step 5: Validate configuration"
-# ao init would fail if run again, so we just verify the file is readable
+# Verify the config file is readable
 if [ ! -f agent-orchestrator.yaml ]; then
     fail_step "Step 5: Config file not found"
 fi

website/content/docs/cli.mdx

@@ -184,12 +184,6 @@ Behavior depends on how AO was installed — git, npm-global, pnpm-global, or un
 
 No flags.
 
-### `ao init` (deprecated)
-
-> Use `ao start` instead — it auto-creates config on first run.
-
-Runs the same config-only bootstrap; kept for backward compatibility.
-
 ## Session subcommands
 
 ### `ao session ls`

website/content/docs/migration.mdx

@@ -36,7 +36,7 @@ ao spawn 42
 
 ## `ao init` → `ao start`
 
-`ao init` is deprecated — `ao start` auto-creates `agent-orchestrator.yaml` on first run and opens the dashboard in one step. `ao init` still works and prints a migration hint.
+`ao init` has been removed. Use `ao start` instead; it auto-creates `agent-orchestrator.yaml` on first run and opens the dashboard in one step.
 
 ## Upgrading