Gemini support is global-only. Use: rtk init -g --gemini

Error message

Gemini support is global-only. Use: rtk init -g --gemini

What it means

rtk's Gemini integration can only be installed at the user/global level (~/.gemini), never per-project. setup_gemini checks the `global` flag and bails with anyhow before touching the filesystem if it was not set. The message tells the exact command to rerun with.

Solutions

Rerun with the global flag: `rtk init -g --gemini`
If per-project Gemini hooks were the goal, note they are unsupported; install globally and rely on shared config
Check `rtk init --help` for current flag layout (--agent vs --gemini)

Example fix

// before
rtk init --gemini
// after
rtk init -g --gemini

Defensive patterns

Strategy: validation

Validate before calling

// shell check before invoking
if ! [[ "$*" == *" -g"* || "$*" == *" --global"* ]]; then echo "Gemini requires global: rtk init -g --gemini" >&2; exit 2; fi

Try / catch

// treat bail as exit code 1 with this message; detect and rewrite the command
rtk init --gemini || { echo "retrying globally"; rtk init -g --gemini; }

Prevention

Always pair --gemini with -g in scripts and docs
Check `rtk init --help` before scripting against init flags
Remember rtk's agent integrations differ in scoping: Claude is project-local, Gemini/Vibe are global

When it happens

Trigger: Running `rtk init --gemini` (or programmatically calling setup_gemini with global=false). Any invocation that requests Gemini hooks without the -g flag hits this bail immediately.

Common situations: Developer wants Gemini integration for a single project and omits -g; scripts/CI generated from older rtk docs before the global-only policy; muscle memory from other agents (like Claude) where rtk init supports project-local hooks.

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

Appendix: source

Thrown at src/hooks/init.rs:5887

/// Gemini hook wrapper script — delegates to `rtk hook gemini`
const GEMINI_HOOK_SCRIPT: &str = r#"#!/bin/bash
exec rtk hook gemini
"#;

fn resolve_gemini_dir() -> Result<PathBuf> {
    resolve_home_subdir(GEMINI_DIR)
}

/// Entry point for `rtk init --gemini`
pub fn run_gemini(
    global: bool,
    hook_only: bool,
    patch_mode: PatchMode,
    ctx: InitContext,
) -> Result<()> {
    let InitContext { dry_run, .. } = ctx;
    if !global {
        anyhow::bail!("Gemini support is global-only. Use: rtk init -g --gemini");
    }

    let gemini_dir = resolve_gemini_dir()?;
    if !dry_run {
        fs::create_dir_all(&gemini_dir).with_context(|| {
            format!(
                "Failed to create Gemini config dir: {}",
                gemini_dir.display()
            )
        })?;
    }

    // 1. Install hook script
    let hook_dir = gemini_dir.join("hooks");
    if !dry_run {
        fs::create_dir_all(&hook_dir)
            .with_context(|| format!("Failed to create hook dir: {}", hook_dir.display()))?;
    }

View on GitHub (pinned to 0924356b4c)