Cursor hooks are global-only. Use: rtk init -g --agent…

Error message

Cursor hooks are global-only. Use: rtk init -g --agent cursor

What it means

rtk's `init` command throws this when `--agent cursor` (or equivalent install_cursor flag) is passed without the `-g/--global` flag. Cursor hook integration writes to the user-level global Cursor configuration only, so a project-local install is unsupported by design. The error tells you the exact remediation command.

Solutions

Re-run with the global flag: `rtk init -g --agent cursor`.
If you truly want project-local Cursor integration, remove `--agent cursor` and integrate RTK into the project's Cursor config manually.
Check `rtk init --help` to confirm which agents are global-only (cursor, windsurf, opencode) vs project-local.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Remember cursor/windsurf/opencode installs are global-only; always pair them with -g.
Wrap team setup scripts to include `-g` for global-only agents.
Check `rtk init --help` when scripting new agent installs.

When it happens

Trigger: Calling `rtk init --agent cursor` (install_cursor=true, global=false). The bail fires in run() at the global-only validation block in src/hooks/init.rs:419-421, before any mode dispatch.

Common situations: Running `rtk init --agent cursor` inside a repo intending project-scoped hooks; forgetting `-g` after upgrading rtk where Cursor support was added as global-only; scripting rtk setup for multiple editors and reusing the non-global invocation pattern used for claude/opencode.

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/07bbfb90669b29e5. Report an issue: GitHub.

Appendix: source

Thrown at src/hooks/init.rs:420

        }
        if hook_only {
            anyhow::bail!("--codex cannot be combined with --hook-only");
        }
        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)?
                }

View on GitHub (pinned to 0924356b4c)