global bundle operations cannot target workspace config

Error message

global bundle operations cannot target workspace config {}; rerun with --project or select the user-global config

What it means

A bundle operation with global (default) scope was pointed at a workspace-scoped config file. `validate_scope_target` refuses global operations against workspace configs and tells the caller to either use `--project` or select the user-global config. This keeps bundle scope and target document in agreement.

Solutions

Re-run with `--project` if you intend to operate on the workspace config.
Otherwise re-run targeting the user-global config (omit the workspace `--config` path).
Update the calling script to pass `--project` whenever its config path is workspace-scoped.

Example fix

// before
codewhale config bundle export .codewhale/config.json bundle.zip
// after
codewhale config bundle export --project .codewhale/config.json bundle.zip

Defensive patterns

Strategy: validation

Validate before calling

if !args.project && codewhale_config::config_path_is_workspace_scoped(&config_path) {
    eprintln!("global scope cannot target workspace config {}; add --project", config_path.display());
    std::process::exit(2);
}

Type guard

fn requires_project_flag(p: &std::path::Path) -> bool {
    codewhale_config::config_path_is_workspace_scoped(p)
}

Prevention

Add `--project` whenever the target config lives under the workspace.
Keep scripts explicit about which config document they target.
Avoid hardcoding the global config path in project scripts.

When it happens

Trigger: Running `codewhale config bundle import` or `export` without `--project` while the targeted config path is workspace-scoped (e.g. `--config .codewhale/config.json` was passed).

Common situations: Explicitly passing a workspace config path but forgetting `--project`; scripts that default to a workspace config path for all commands; running an export intended for the global profile but resolving to the workspace config.

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 Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/075837d9e18c2b29. Report an issue: GitHub.

Appendix: source

Thrown at crates/cli/src/config_bundles.rs:688

impl BundleScope {
    #[must_use]
    pub fn label(self) -> &'static str {
        match self {
            Self::Global => "global",
            Self::Project => "project",
        }
    }
}

fn validate_scope_target(scope: BundleScope, target: &Path) -> Result<()> {
    let workspace_scoped = codewhale_config::config_path_is_workspace_scoped(target);
    match (scope, workspace_scoped) {
        (BundleScope::Project, false) => bail!(
            "--project requires a workspace config ({} is the user-global document)",
            target.display()
        ),
        (BundleScope::Global, true) => bail!(
            "global bundle operations cannot target workspace config {}; rerun with --project or select the user-global config",
            target.display()
        ),
        _ => {}
    }
    Ok(())
}

// ---------------------------------------------------------------------------
// Path safety
// ---------------------------------------------------------------------------

/// Resolve `candidate` inside `base_dir`, refusing traversal and symlink
/// escapes. Returns the resolved path or an error naming the refusal — the
/// candidate string itself is safe to echo (it is config data, not a secret).
/// Resolve `candidate` inside `base_dir`, refusing traversal and symlink
/// escapes. Returns the joined path or an error naming the refusal.
/// Reserved for path-carrying bundle sections (none shipped yet); exercised

View on GitHub (pinned to 73e0f67d83)