OpenCode plugin is global-only. Use: rtk init -g --opencode

Error message

OpenCode plugin is global-only. Use: rtk init -g --opencode

What it means

rtk's `rtk init` requires agent integrations like the OpenCode plugin to be installed globally. Running `rtk init --opencode` without the -g/--global flag is refused because the plugin must live in the user-level config, not a per-project one. The error message tells the exact command to run instead.

Solutions

Add the -g flag: `rtk init -g --opencode`
If a per-project install was intended, note that the OpenCode plugin does not support it; install globally once instead
Remove --opencode if the global requirement is unacceptable and rely on the default hook setup

Example fix

// before
rtk init --opencode
// after
rtk init -g --opencode

Defensive patterns

Strategy: validation

Validate before calling

const opencode = args.includes("--opencode");
const global = args.includes("-g") || args.includes("--global");
if (opencode && !global) throw new Error("OpenCode plugin is global-only; add -g");

Prevention

Always pass -g when installing agent plugins like --opencode or cursor hooks
Treat plugin integrations as user-level (one-time global) setup, distinct from per-project hook init
Read the error message hint: rtk prints the exact corrected command to run

When it happens

Trigger: Running `rtk init --opencode` (or any variant where `install_opencode` is true and `global` is false) in the non-codex branch of HooksInit::run. Fires before any files are written.

Common situations: A developer initializes hooks per-project as a habit and adds --opencode the same way. Following older docs that did not mark the plugin as global-only. Copying a setup script run in a project directory without the -g flag.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at src/hooks/init.rs:416

            anyhow::bail!("--codex cannot be combined with --opencode");
        }
        if claude_md {
            anyhow::bail!("--codex cannot be combined with --claude-md");
        }
        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)?,

View on GitHub (pinned to 0924356b4c)