pbakaus/impeccable · error

Unknown update scope: {v}. Use --project or --user.

Error message

Unknown update scope: {v}. Use --project or --user.

What it means

During `update`, the --user/--project scope value is normalized via normalize_install_scope. If the provided scope string is not recognized, update exits 1 with 'Unknown update scope: {v}. Use --project or --user.' Only --project and --user are valid scope values.

Source

Thrown at crates/skills/src/commands.rs:741

        out(io, &format!("Installed hooks into: {}", hook_targets.join(", ")));
    }
    out(io, "\nDone! Now type /impeccable init in your AI coding agent's chat (not in this terminal) to set up design context.\n");
    Ok(())
}

// ─── update ──────────────────────────────────────────────────────────────────

/// JS: update(flags)
fn update(flags: &[String], io: &mut Io) -> R<()> {
    let (sys, mut prompt) = ctx(io);
    let yes = has_flag(flags, "-y") || has_flag(flags, "--yes");
    let force = has_flag(flags, "--force");
    let install_hooks = !has_flag(flags, "--no-hooks");
    let scope_value = get_install_scope_value(flags);
    let explicit_scope = scope_value.as_deref().and_then(normalize_install_scope);
    if let Some(v) = &scope_value {
        if explicit_scope.is_none() {
            err(io, &format!("Unknown update scope: {v}. Use --project or --user."));
            return Err(Flow::Exit(1));
        }
    }

    let project_root = sys.find_project_root();
    let home = sys.home.clone();

    let target = sys.resolve_update_target(&project_root, explicit_scope);
    let Some(target) = target else {
        match explicit_scope {
            Some(scope) => {
                let where_ = if scope == Scope::User {
                    format!("user level ({})", sys.format_path_for_display(&home))
                } else {
                    format!("this project ({project_root})")
                };
                out(io, &format!("No impeccable skill folders found at the {where_}."));
            }

View on GitHub (pinned to 2bc2879276)

Solutions

1. Use exactly `--project` or `--user` for the scope.
2. Omit the scope flag entirely to use the auto-detected default scope.
3. Fix the shell script/alias that interpolates an invalid scope value.

Example fix

// before
impeccable update --scope=global
// after
impeccable update --user

SCOPE="--user"   # only --project or --user are valid
impeccable update "$SCOPE"

case "$SCOPE" in --project|--user) impeccable update "$SCOPE";; *) echo "invalid scope";; esac

When it happens

Trigger: Running `impeccable update` with a scope flag whose value does not normalize to project/user, e.g. `--scope=global`, `--scope=local`, or a malformed `--project=yes` style value caught by get_install_scope_value.

Common situations: Users guessing at scope names ('global', 'local', 'repo'); copying flags from the install command where a different form is accepted; shell scripts with templated scope values.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

• Error: --scope requires a value. Valid scopes: {scopes_valid
• Error: unknown --scope value(s): {}. Valid scopes: {scopes_v
• concept-seed: --candidate-count must be an integer from 5 to
• Unknown ignore-rule flag: ${arg}
• Pass a rule id, e.g. ${IMPECCABLE_COMMAND} hooks ignore-rule

AI-assisted analysis of pbakaus/impeccable@2bc2879276 (2026-09-08). Data as JSON: /api/errors/0e54f9e44597b261. Report an issue: GitHub.