rtk-ai/rtk · error · anyhow::Error

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

Error message

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

What it means

rtk installs Windsurf support only by editing the user's global Windsurf config, so run_init rejects a project-scoped install before touching any file. The bail embeds the corrected command. Nothing has been written when this error appears, so re-running with -g is safe.

Source

Thrown at src/hooks/init.rs:306

        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 d977e1c316)

Solutions

Run `rtk init -g --agent windsurf`
If global writes are forbidden in your environment, use a project-scoped agent instead (plain `rtk init` for Claude Code)
Check each agent's scope in `rtk init --help` before scripting init

Example fix

# before
rtk init --agent windsurf   # error: global-only

# after
rtk init -g --agent windsurf

Defensive patterns

Strategy: validation

Validate before calling

# bash: pair global-only agents with -g before invoking rtk
case "$AGENT" in windsurf|cursor|opencode|gemini|vibe) GLOBAL_FLAG='-g';; esac
rtk init $GLOBAL_FLAG --agent "$AGENT"

Prevention

Memorize the split: windsurf/cursor/opencode/gemini/vibe are global-only (-g); kilocode/antigravity/kimi are project-only (no -g)
Wrap rtk init in a script that whitelists (agent, scope) pairs and fails fast on mismatches
Use --dry-run first: `rtk init -g --agent windsurf --dry-run` shows every write without the flag error risk

When it happens

Trigger: Running `rtk init --agent windsurf` (or any flag combination that sets install_windsurf) without `--global`/`-g` — the check at src/hooks/init.rs:308.

Common situations: Copying a project-scoped `rtk init` line used for Claude Code and swapping the agent name; wrapper scripts that deliberately never pass -g (CI sandboxes, shared machines, dotfile repos).

Related errors

AI-assisted analysis of rtk-ai/rtk@d977e1c316 (2026-08-16). Data as JSON: /api/errors/0872be38ac6f819d. Report an issue: GitHub.