--project requires a workspace config

Error message

--project requires a workspace config ({} is the user-global document)

What it means

A bundle operation was invoked with `--project` scope, but the config file the command targets is the user-global document, not a workspace-scoped one. `validate_scope_target` checks `config_path_is_workspace_scoped` and refuses project-scope operations against the global config, since project bundles can only be applied to a workspace config.

Solutions

Create a workspace config in the project (or run the command from a directory that has one) and retry with `--project`.
Drop `--project` and let the operation run in the default (global) scope.
Fix the `--config` path so it points at the workspace config file instead of the user-global document.

Example fix

// before
codewhale config bundle import --project ~/codewhale/config.json bundle.zip
// after
codewhale config bundle import --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!("--project requires a workspace config; {} is the user-global document", config_path.display());
    std::process::exit(2);
}

Type guard

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

Prevention

Run project-scope bundle commands from a directory that contains a workspace config.
Wrap common invocations in a script that picks scope based on the config path.
Double-check any explicit `--config` path before combining it with `--project`.

When it happens

Trigger: Running `codewhale config bundle import --project` (or export) while the resolved config path is the user-global config — e.g. no workspace config exists in the project or the command was run outside a workspace with an explicit global config path.

Common situations: Running the command in a directory without a `.codewhale` workspace config; passing the global config path explicitly; a typo in `--config` pointing at the user-global file.

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

Appendix: source

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

    Global,
    /// The workspace-scoped config (`<repo>/.codewhale/config.toml`).
    Project,
}

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

View on GitHub (pinned to 73e0f67d83)