feat(cli): add interactive setup wizard and modernize init command

Add `xcodebuildmcp setup` — an interactive terminal wizard that walks
users through configuring project defaults (project/workspace, scheme,
simulator, workflows, debug mode, Sentry opt-out) and persists the
result to .xcodebuildmcp/config.yaml.

Key changes:
- New setup command with clack-based interactive prompts
- Shared Prompter abstraction for testable TTY/non-interactive prompts
- Promote sentryDisabled from env-var-only to first-class config key
- Extract reusable functions from discover_projs, list_schemes, list_sims
  so both MCP tools and CLI can call them directly
- Modernize init command to use clack prompts and interactive selection
- Replace Cursor/Codex client targets with generic Agents Skills target
- Add persistProjectConfigPatch for atomic config file updates

Author: cameroncooke

config.example.yaml

@@ -3,6 +3,8 @@ enabledWorkflows: ['simulator', 'ui-automation', 'debugging']
 experimentalWorkflowDiscovery: false
 disableSessionDefaults: false
 incrementalBuildsEnabled: false
+debug: false
+sentryDisabled: false
 sessionDefaults:
   projectPath: './MyApp.xcodeproj' # xor workspacePath
   workspacePath: './MyApp.xcworkspace' # xor projectPath

docs/CLI.md

@@ -25,6 +25,9 @@ xcodebuildmcp --help
 
 # View tool help
 xcodebuildmcp <workflow> <tool> --help
+
+# Run interactive setup for .xcodebuildmcp/config.yaml
+xcodebuildmcp setup
 ```
 
 ## Tool Options
@@ -116,6 +119,8 @@ enabledWorkflows:
 
 See [CONFIGURATION.md](CONFIGURATION.md) for the full schema.
 
+To create/update config interactively, run `xcodebuildmcp setup`.
+
 ## Environment Variables
 
 | Variable | Description |

docs/CONFIGURATION.md

@@ -25,6 +25,12 @@ Create a config file at your workspace root:
 <workspace-root>/.xcodebuildmcp/config.yaml
 ```
 
+Or run the interactive setup wizard:
+
+```bash
+xcodebuildmcp setup
+```
+
 Minimal example:
 
 ```yaml
@@ -61,6 +67,7 @@ incrementalBuildsEnabled: false
 
 # Debugging
 debug: false
+sentryDisabled: false
 debuggerBackend: "dap"
 dapRequestTimeoutMs: 30000
 dapLogEvents: false
@@ -262,8 +269,13 @@ Default templates:
 By default, only internal XcodeBuildMCP runtime failures are sent to Sentry. User-domain errors (such as project build/test/config failures) are not sent. To disable telemetry entirely:
 
 ```yaml
-# Environment variable only (no config.yaml option)
-# XCODEBUILDMCP_SENTRY_DISABLED=true
+sentryDisabled: true
+```
+
+You can also disable telemetry via environment variable:
+
+```bash
+XCODEBUILDMCP_SENTRY_DISABLED=true
 ```
 
 See [PRIVACY.md](PRIVACY.md) for more information.
@@ -286,6 +298,7 @@ Notes:
 | `sessionDefaults` | object | `{}` |
 | `incrementalBuildsEnabled` | boolean | `false` |
 | `debug` | boolean | `false` |
+| `sentryDisabled` | boolean | `false` |
 | `debuggerBackend` | string | `"dap"` |
 | `dapRequestTimeoutMs` | number | `30000` |
 | `dapLogEvents` | boolean | `false` |
@@ -310,6 +323,7 @@ Environment variables are supported for backwards compatibility but the config f
 | `disableSessionDefaults` | `XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS` |
 | `incrementalBuildsEnabled` | `INCREMENTAL_BUILDS_ENABLED` |
 | `debug` | `XCODEBUILDMCP_DEBUG` |
+| `sentryDisabled` | `XCODEBUILDMCP_SENTRY_DISABLED` |
 | `debuggerBackend` | `XCODEBUILDMCP_DEBUGGER_BACKEND` |
 | `dapRequestTimeoutMs` | `XCODEBUILDMCP_DAP_REQUEST_TIMEOUT_MS` |
 | `dapLogEvents` | `XCODEBUILDMCP_DAP_LOG_EVENTS` |
@@ -320,7 +334,6 @@ Environment variables are supported for backwards compatibility but the config f
 | `iosTemplateVersion` | `XCODEBUILD_MCP_IOS_TEMPLATE_VERSION` |
 | `macosTemplatePath` | `XCODEBUILDMCP_MACOS_TEMPLATE_PATH` |
 | `macosTemplateVersion` | `XCODEBUILD_MCP_MACOS_TEMPLATE_VERSION` |
-| (no config option) | `XCODEBUILDMCP_SENTRY_DISABLED` |
 
 Config file takes precedence over environment variables when both are set.
 

docs/GETTING_STARTED.md

@@ -69,6 +69,12 @@ For deterministic session defaults and runtime configuration, add a config file
 <workspace-root>/.xcodebuildmcp/config.yaml
 ```
 
+Use the setup wizard to create or update this file interactively:
+
+```bash
+xcodebuildmcp setup
+```
+
 See [CONFIGURATION.md](CONFIGURATION.md) for the full schema and examples.
 
 ## Client-specific configuration

example_projects/iOS_Calculator/.xcodebuildmcp/config.yaml

@@ -1,11 +1,11 @@
 schemaVersion: 1
 enabledWorkflows:
+  - debugging
   - simulator
   - ui-automation
-  - debugging
   - xcode-ide
 sessionDefaults:
-  workspacePath: ./CalculatorApp.xcworkspace
+  workspacePath: CalculatorApp.xcworkspace
   scheme: CalculatorApp
   configuration: Debug
   simulatorName: iPhone 17 Pro
@@ -17,3 +17,5 @@ sessionDefaults:
   derivedDataPath: ./iOS_Calculator/.derivedData
   preferXcodebuild: true
   bundleId: io.sentry.calculatorapp
+debug: false
+sentryDisabled: false

package-lock.json

@@ -70,6 +70,7 @@
     "url": "https://github.com/getsentry/XcodeBuildMCP/issues"
   },
   "dependencies": {
+    "@clack/prompts": "^1.0.1",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "@sentry/cli": "^3.1.0",
     "@sentry/node": "^10.38.0",

package.json

@@ -125,7 +125,7 @@ function extractCommandCandidates(content) {
 }
 
 function findInvalidCommands(files, validPairs, validWorkflows) {
-  const validTopLevel = new Set(['mcp', 'tools', 'daemon', 'init']);
+  const validTopLevel = new Set(['mcp', 'tools', 'daemon', 'init', 'setup']);
   const validDaemonActions = new Set(['status', 'start', 'stop', 'restart', 'list']);
   const findings = [];
 

scripts/check-docs-cli-commands.js

@@ -7,6 +7,7 @@ import { startMcpServer } from './server/start-mcp-server.ts';
 import { listCliWorkflowIdsFromManifest } from './runtime/tool-catalog.ts';
 import { flushAndCloseSentry, initSentry, recordBootstrapDurationMetric } from './utils/sentry.ts';
 import { setLogLevel, type LogLevel } from './utils/logger.ts';
+import { hydrateSentryDisabledEnvFromProjectConfig } from './utils/sentry-config.ts';
 
 function findTopLevelCommand(argv: string[]): string | undefined {
   const flagsWithValue = new Set(['--socket', '--log-level', '--style']);
@@ -31,12 +32,11 @@ function findTopLevelCommand(argv: string[]): string | undefined {
   return undefined;
 }
 
-async function runInitCommand(): Promise<void> {
+async function buildLightweightYargsApp(): Promise<ReturnType<typeof import('yargs').default>> {
   const yargs = (await import('yargs')).default;
   const { hideBin } = await import('yargs/helpers');
-  const { registerInitCommand } = await import('./cli/commands/init.ts');
 
-  const app = yargs(hideBin(process.argv))
+  return yargs(hideBin(process.argv))
     .scriptName('')
     .strict()
     .help()
@@ -63,10 +63,22 @@ async function runInitCommand(): Promise<void> {
         setLogLevel(level);
       }
     });
+}
+
+async function runInitCommand(): Promise<void> {
+  const { registerInitCommand } = await import('./cli/commands/init.ts');
+  const app = await buildLightweightYargsApp();
   registerInitCommand(app, { workspaceRoot: process.cwd() });
   await app.parseAsync();
 }
 
+async function runSetupCommand(): Promise<void> {
+  const { registerSetupCommand } = await import('./cli/commands/setup.ts');
+  const app = await buildLightweightYargsApp();
+  registerSetupCommand(app);
+  await app.parseAsync();
+}
+
 async function main(): Promise<void> {
   const cliBootstrapStartedAt = Date.now();
   const earlyCommand = findTopLevelCommand(process.argv.slice(2));
@@ -78,6 +90,12 @@ async function main(): Promise<void> {
     await runInitCommand();
     return;
   }
+  if (earlyCommand === 'setup') {
+    await runSetupCommand();
+    return;
+  }
+
+  await hydrateSentryDisabledEnvFromProjectConfig();
   initSentry({ mode: 'cli' });
 
   // CLI mode uses disableSessionDefaults to show all tool parameters as flags

src/cli.ts

@@ -131,16 +131,36 @@ describe('init command', () => {
       stdoutSpy.mockRestore();
     });
 
+    it('expands ~ in --dest to home directory', async () => {
+      const fakeHome = join(tempDir, 'home');
+      mkdirSync(fakeHome, { recursive: true });
+      mockedHomedir.mockReturnValue(fakeHome);
+
+      const yargs = (await import('yargs')).default;
+      const mod = await loadInitModule();
+
+      const app = yargs(['init', '--dest', '~/skills', '--skill', 'cli']).scriptName('');
+      mod.registerInitCommand(app);
+
+      const stdoutSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+      await app.parseAsync();
+
+      const installed = join(fakeHome, 'skills', 'xcodebuildmcp-cli', 'SKILL.md');
+      expect(existsSync(installed)).toBe(true);
+
+      stdoutSpy.mockRestore();
+    });
+
     it('skips Claude for MCP skill in auto-detect mode', async () => {
       const fakeHome = join(tempDir, 'home-auto-skip-claude');
       mkdirSync(join(fakeHome, '.claude'), { recursive: true });
-      mkdirSync(join(fakeHome, '.cursor'), { recursive: true });
+      mkdirSync(join(fakeHome, '.agents'), { recursive: true });
       mockedHomedir.mockReturnValue(fakeHome);
 
       const yargs = (await import('yargs')).default;
       const mod = await loadInitModule();
 
-      const app = yargs(['init', '--skill', 'mcp']).scriptName('');
+      const app = yargs(['init', '--skill', 'mcp', '--client', 'auto']).scriptName('');
       mod.registerInitCommand(app);
 
       const stdoutSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
@@ -149,7 +169,7 @@ describe('init command', () => {
       expect(existsSync(join(fakeHome, '.claude', 'skills', 'xcodebuildmcp', 'SKILL.md'))).toBe(
         false,
       );
-      expect(existsSync(join(fakeHome, '.cursor', 'skills', 'xcodebuildmcp', 'SKILL.md'))).toBe(
+      expect(existsSync(join(fakeHome, '.agents', 'skills', 'xcodebuildmcp', 'SKILL.md'))).toBe(
         true,
       );
 
@@ -223,7 +243,7 @@ describe('init command', () => {
       const app = yargs(['init', '--dest', dest, '--skill', 'cli']).scriptName('').fail(false);
       mod.registerInitCommand(app);
 
-      await expect(app.parseAsync()).rejects.toThrow('Conflicting skill');
+      await expect(app.parseAsync()).rejects.toThrow('conflicting mcp skill found');
 
       Object.defineProperty(process.stdin, 'isTTY', { value: originalIsTTY, configurable: true });
     });
@@ -369,8 +389,7 @@ describe('init command', () => {
       await app.parseAsync();
 
       expect(existsSync(join(emptyHome, '.claude', 'skills'))).toBe(false);
-      expect(existsSync(join(emptyHome, '.cursor', 'skills'))).toBe(false);
-      expect(existsSync(join(emptyHome, '.codex', 'skills', 'public'))).toBe(false);
+      expect(existsSync(join(emptyHome, '.agents', 'skills'))).toBe(false);
 
       stdoutSpy.mockRestore();
     });
@@ -548,15 +567,41 @@ describe('init command', () => {
       expect(readFileSync(join(conflictDir, 'SKILL.md'), 'utf8')).toBe('existing mcp skill');
     });
 
-    it('errors when no clients detected and no --dest or --print', async () => {
+    it('errors in non-interactive mode without --client or --dest', async () => {
+      const originalStdinIsTTY = process.stdin.isTTY;
+      const originalStdoutIsTTY = process.stdout.isTTY;
+      Object.defineProperty(process.stdin, 'isTTY', { value: false, configurable: true });
+      Object.defineProperty(process.stdout, 'isTTY', { value: false, configurable: true });
+
+      const yargs = (await import('yargs')).default;
+      const mod = await loadInitModule();
+
+      const app = yargs(['init', '--skill', 'cli']).scriptName('').fail(false);
+      mod.registerInitCommand(app);
+
+      await expect(app.parseAsync()).rejects.toThrow(
+        'Non-interactive mode requires --client or --dest for init',
+      );
+
+      Object.defineProperty(process.stdin, 'isTTY', {
+        value: originalStdinIsTTY,
+        configurable: true,
+      });
+      Object.defineProperty(process.stdout, 'isTTY', {
+        value: originalStdoutIsTTY,
+        configurable: true,
+      });
+    });
+
+    it('errors when no clients detected with --client=auto and no --dest or --print', async () => {
       const emptyHome = join(tempDir, 'empty-home');
       mkdirSync(emptyHome, { recursive: true });
       mockedHomedir.mockReturnValue(emptyHome);
 
       const yargs = (await import('yargs')).default;
       const mod = await loadInitModule();
 
-      const app = yargs(['init', '--skill', 'cli']).scriptName('').fail(false);
+      const app = yargs(['init', '--skill', 'cli', '--client', 'auto']).scriptName('').fail(false);
       mod.registerInitCommand(app);
 
       await expect(app.parseAsync()).rejects.toThrow('No supported AI clients detected');