Uninstall only works with --global flag. For local…

Error message

Uninstall only works with --global flag. For local projects, manually remove RTK from CLAUDE.md

What it means

Thrown by uninstall_with_patch_mode when `uninstall` is invoked without `--global`. RTK's uninstaller only removes global (user-level) installations; it refuses to touch project-local files. For local setups the user is instructed to manually delete the RTK block from the project's CLAUDE.md.

Solutions

Re-run with the global flag: `rtk uninstall -g`.
For local installs, manually open the project's CLAUDE.md and delete the RTK block (text between the RTK block markers).
Search the repo for the RTK block markers (e.g. grep for 'rtk' in CLAUDE.md) to locate what to remove.

Defensive patterns

Strategy: try-catch

Validate before calling

# add -g for plain uninstall; local cleanup is manual
if rtk uninstall 2>err.txt; then :; else
  grep -q 'only works with --global' err.txt && rtk uninstall -g
fi

Try / catch

if ! rtk uninstall 2>err.txt; then
  grep -q 'only works with --global' err.txt && rtk uninstall -g || echo "remove RTK block from CLAUDE.md manually"
fi

Prevention

Default to `rtk uninstall -g` in cleanup scripts.
For local installs, document that removal is manual (delete the RTK block in CLAUDE.md).
Prefer global installs to keep uninstall automated.

When it happens

Trigger: Calling `rtk uninstall` (or `rtk uninstall --claude-md`-style variants) with global=false. The bail fires in uninstall_with_patch_mode at src/hooks/init.rs:955-958 right after the omp/cursor early-returns and before resolve_claude_dir().

Common situations: Trying to remove RTK from a single repo after having installed it locally via `rtk init --claude-md`; automated cleanup scripts that assume uninstall works everywhere; users who installed locally and later forgot that uninstall is global-only.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at src/hooks/init.rs:956

        }
        if dry_run {
            print_dry_run_footer();
        }
        return Ok(());
    }

    if pi {
        uninstall_pi_with_patch_mode(global, patch_mode, ctx)?;
        return Ok(());
    }

    if omp {
        uninstall_omp_with_patch_mode(global, patch_mode, ctx)?;
        return Ok(());
    }

    if !global {
        anyhow::bail!(
            "Uninstall only works with --global flag. For local projects, manually remove RTK from CLAUDE.md"
        );
    }

    let claude_dir = resolve_claude_dir()?;
    let mut removed = Vec::new();

    // Also uninstall Gemini artifacts if --gemini or always (clean everything)
    if gemini {
        let gemini_removed = uninstall_gemini(ctx)?;
        removed.extend(gemini_removed);
        if !removed.is_empty() {
            let header = if dry_run {
                "[dry-run] would uninstall RTK (Gemini):"
            } else {
                "RTK uninstalled (Gemini):"
            };
            println!("{}", header);

View on GitHub (pinned to 0924356b4c)