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

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

The Gemini integration writes ~/.gemini config (settings and prompt files) — user-global state only — so run_gemini rejects a project-scoped install up front. As with the other global-only agents, nothing is written before the bail, so re-running with -g is safe.

Source

Thrown at src/hooks/init.rs:4199

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

Solutions

Run `rtk init -g --gemini`
Preview the writes first: `rtk init -g --gemini --dry-run`

Example fix

# before
rtk init --gemini   # error: global-only

# after
rtk init -g --gemini

Defensive patterns

Strategy: validation

Validate before calling

# bash: gemini is global-only
rtk init -g --gemini --dry-run   # preview, then run without --dry-run

Prevention

Keep a cheat sheet of agent scopes next to your install scripts
Use --dry-run to confirm flag combinations before the real run

When it happens

Trigger: `rtk init --gemini` without `-g`/`--global` — run_gemini at src/hooks/init.rs:4205.

Common situations: Scripts that intentionally avoid -g; docs or notes showing --gemini without the global flag.

Related errors

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