pbakaus/impeccable · error

Unknown command: {}

Error message

Unknown command: {}

What it means

The `pin` helper command validates that the command argument names a known command before pinning or unpinning it. If the command string is not in VALID_COMMANDS, it prints the unknown command name plus the list of available commands and exits with status 1. This guards the pinned-commands metadata file from containing garbage entries.

Source

Thrown at crates/context/src/pin.rs:227

        }
    }
    serde_json::from_str(COMMAND_METADATA_JSON).unwrap_or(serde_json::Value::Object(Default::default()))
}

pub fn run(args: &[String], io: &mut Io) -> i32 {
    let action = args.first().cloned();
    let command = args.get(1).cloned();
    let (Some(action), Some(command)) = (action.filter(|a| !a.is_empty()), command.filter(|c| !c.is_empty())) else {
        io.out("Usage: impeccable pin <pin|unpin> <command>\n");
        io.out(&format!("\nAvailable commands: {}\n", VALID_COMMANDS.join(", ")));
        return 1;
    };
    if action != "pin" && action != "unpin" {
        io.err(&format!("Unknown action: {}. Use 'pin' or 'unpin'.\n", action));
        return 1;
    }
    if !VALID_COMMANDS.contains(&command.as_str()) {
        io.err(&format!("Unknown command: {}\n", command));
        io.err(&format!("Available commands: {}\n", VALID_COMMANDS.join(", ")));
        return 1;
    }
    let cwd = io.cwd.to_string_lossy().into_owned();
    let root = find_project_root(&cwd);
    if action == "pin" {
        let metadata = load_metadata(io);
        let harness_dirs = find_harness_dirs(&root);
        let opencode_commands_dirs = find_opencode_commands_dirs(&root, io, false);
        if harness_dirs.is_empty() && opencode_commands_dirs.is_empty() {
            io.out("No harness directories with impeccable installed found.\n");
            return 0;
        }
        let mut created = 0;
        // OpenCode is handled separately below because its shortcut format is
        // a slash command, not a SKILL.md. Excluding it from the skill loop
        // prevents a duplicate `.opencode/skills/<cmd>/SKILL.md` that OpenCode
        // would never surface as `/<cmd>`.

View on GitHub (pinned to 2bc2879276)

Solutions

1. Check the printed 'Available commands:' list and re-run with an exact valid command name.
2. Verify the command is actually supported by this version of the tool (renames happen between versions).
3. If pinning from a script, validate the command name against VALID_COMMANDS before invoking.

Example fix

// before
pin 'serach-files'
// after
pin 'search-files'  # name taken from the 'Available commands:' output

const VALID_COMMANDS = require('./crates/context/src/pin').VALID_COMMANDS; // or hardcode the printed list
if (!VALID_COMMANDS.includes(cmd)) {
  throw new Error(`pin: unknown command '${cmd}'. Valid: ${VALID_COMMANDS.join(', ')}`);
}

const isValidCommand = (cmd) => typeof cmd === 'string' && VALID_COMMANDS.includes(cmd);

const code = run(io); // inspect io.err output for 'Unknown command:'
if (code === 1 && io.errBuffer.includes('Unknown command:')) {
  // re-parse the 'Available commands:' line and retry with a corrected name
}

When it happens

Trigger: Running the pin subcommand (action pin/unpin) with a command argument that is not in the VALID_COMMANDS list, e.g. a typo like `pin 'searchk'` or a command from a different tool.

Common situations: Typo in the command name; passing a command that exists in another crate but is not pin-aware; scripting the pin command with a variable that is empty or stale; version drift where a command was renamed or removed.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• invalid session id: ${id}
• build-phase: finish --disposition ship|fix|rebuild|recapture
• comp-spec: cannot read regions {rf}: {e}
• embed-prompt: malformed PNG
• Available commands: {}

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