Windsurf support is global-only. Use: rtk init -g --agent…

Error message

Windsurf support is global-only. Use: rtk init -g --agent windsurf

What it means

rtk's `init` command throws this when `--agent windsurf` (install_windsurf=true) is passed without `-g/--global`. Like Cursor, Windsurf integration is global-only: it configures the user-level Windsurf setup, and a local-project mode is not implemented. The message includes the exact command to use.

Solutions

Re-run with the global flag: `rtk init -g --agent windsurf`.
Remove `--agent windsurf` if you only want local project integration via CLAUDE.md (`rtk init --claude-md`).
Consult `rtk init --help` to confirm windsurf is global-only before scripting.

Example fix

// before (shell)
rtk init --agent windsurf
// after (shell)
rtk init -g --agent windsurf

Defensive patterns

Strategy: validation

Validate before calling

// shell check before invoking rtk init with windsurf
if [[ "$*" == *"--agent windsurf"* && "$*" != *"-g"* && "$*" != *"--global"* ]]; then
  echo "refusing: windsurf install requires -g"; exit 1;
fi
rtk init -g --agent windsurf

Prevention

Treat windsurf like cursor: global-only, always use `-g`.
For project-scoped token filtering, prefer `rtk init --claude-md` instead.
Keep a canonical setup script reviewed for global vs local flags.

When it happens

Trigger: Calling `rtk init --agent windsurf` (install_windsurf=true, global=false). The bail fires in run() at src/hooks/init.rs:423-425 in the global-only validation block before run_windsurf_mode is dispatched.

Common situations: Trying to scope Windsurf hooks to a single project; copy-pasting a setup script that omits `-g`; setting up multiple AI editors where claude/claude-md modes work locally but windsurf/cursor do not.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

AI-assisted analysis of rtk-ai/rtk@0924356b4c (2026-09-19). Data as JSON: /api/errors/0872be38ac6f819d. Report an issue: GitHub.

Appendix: source

Thrown at src/hooks/init.rs:424

        if matches!(patch_mode, PatchMode::Auto) {
            anyhow::bail!("--codex cannot be combined with --auto-patch");
        }
        if matches!(patch_mode, PatchMode::Skip) {
            anyhow::bail!("--codex cannot be combined with --no-patch");
        }
        run_codex_mode(global, ctx)?;
    } else {
        // Validation: Global-only features
        if install_opencode && !global {
            anyhow::bail!("OpenCode plugin is global-only. Use: rtk init -g --opencode");
        }

        if install_cursor && !global {
            anyhow::bail!("Cursor hooks are global-only. Use: rtk init -g --agent cursor");
        }

        if install_windsurf && !global {
            anyhow::bail!("Windsurf support is global-only. Use: rtk init -g --agent windsurf");
        }

        if install_windsurf {
            run_windsurf_mode(ctx)?;
        } else if install_cline {
            run_cline_mode(ctx)?;
        } else {
            // Mode selection (Claude Code / OpenCode)
            match (install_claude, install_opencode, claude_md, hook_only) {
                (false, true, _, _) => run_opencode_only_mode(ctx)?,
                (true, opencode, true, _) => run_claude_md_mode(global, opencode, ctx)?,
                (true, opencode, false, true) => {
                    run_hook_only_mode(global, patch_mode, opencode, ctx)?
                }
                (true, opencode, false, false) => {
                    run_default_mode(global, patch_mode, opencode, ctx)?
                }
                (false, false, _, _) => {

View on GitHub (pinned to 0924356b4c)