Programmatically Disabling Onboarding in Desktop Commander MCP

The --no-onboarding CLI flag is the sole programmatic switch to disable onboarding in Desktop Commander MCP, setting a global flag that short-circuits the welcome flow before any UI renders.

Desktop Commander MCP displays a welcome page for new users by default, but automation scenarios and headless deployments often require skipping this flow entirely. The application provides a definitive mechanism to programmatically disable onboarding through command-line arguments and configuration overrides. Understanding these entry points requires examining how the server initializes in src/index.ts and evaluates feature flags in src/utils/usageTracker.ts.

How Onboarding is Controlled in Desktop Commander MCP

The onboarding flow is gated by three coordinated mechanisms in the codebase. The server first checks for a global flag set via command-line arguments, then evaluates feature flags tied to experiments, and finally respects local configuration overrides stored in user settings. These layers converge in src/utils/usageTracker.ts, where the final decision to show or skip the welcome page is made.

Using the Command-Line Flag to Disable Onboarding

The most direct way to programmatically disable onboarding is passing the --no-onboarding argument when starting the server. In src/index.ts (lines 44-52), the startup code parses process.argv and sets a global property:

const DISABLE_ONBOARDING = process.argv.includes('--no-onboarding');
if (DISABLE_ONBOARDING) {
  logToStderr('info', 'Onboarding disabled via --no-onboarding flag');
}
(global as any).disableOnboarding = DISABLE_ONBOARDING;

This flag persists for the entire process lifetime and is checked by downstream components before any welcome UI renders.

To start Desktop Commander MCP without onboarding:

desktop-commander-mcp --no-onboarding

Global Flag Propagation and Runtime Checks

Once set, the disableOnboarding property on the global object serves as the source of truth. The isOnboardingEnabled function in src/utils/usageTracker.ts checks this flag early in its evaluation logic:

if ((global as any).disableOnboarding) {
  return false;               // Disables onboarding programmatically
}

If this check returns false, the handleWelcomePageOnboarding function in src/utils/welcome-onboarding.ts returns early, preventing the welcome page from opening and suppressing related telemetry emissions.

Custom plugins or extensions can detect this state:

if ((global as any).disableOnboarding) {
  // Adjust plugin behavior for headless mode
}

Alternative Configuration Method

As an alternative to CLI arguments, users can disable onboarding via the configuration file. The configManager reads the onboarding_injection setting, and when set to false, the application treats this equivalently to the global flag being set. This is defined in src/utils/usageTracker.ts (lines 39-43).

Create or edit your config file:

{
  "onboarding_injection": false
}

This approach is useful when you cannot modify startup scripts but have write access to user configuration.

Summary

• The --no-onboarding CLI argument is the definitive programmatic method to disable onboarding, implemented in src/index.ts.
• This flag sets (global as any).disableOnboarding, which src/utils/usageTracker.ts checks before rendering any welcome UI.
• When the flag is active, handleWelcomePageOnboarding exits early and telemetry is suppressed.
• Users can alternatively set "onboarding_injection": false in config files to achieve the same effect without command-line modifications.

Frequently Asked Questions

How do I permanently disable onboarding in Desktop Commander MCP?

Set the onboarding_injection property to false in your user configuration file. This persists across restarts without requiring the --no-onboarding flag. The configuration is read at startup by the configManager in src/utils/usageTracker.ts.

Can I disable onboarding when running Desktop Commander MCP programmatically from another application?

Yes. Pass the --no-onboarding argument when spawning the process from your application. The startup code in src/index.ts detects this and sets global.disableOnboarding, which prevents the welcome page from ever loading.

Where is the onboarding disable flag stored during runtime?

The flag is stored as disableOnboarding on the global object, as defined in src/types.ts. This allows any module to check (global as any).disableOnboarding to determine if the onboarding flow has been suppressed.

Does disabling onboarding affect telemetry collection?

Yes. When onboarding is disabled via the global flag or configuration, the application skips telemetry emissions related to the onboarding flow. The check in src/utils/usageTracker.ts short-circuits both the UI and associated analytics.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}