Exit codes

skillmirror ends with one of five codes. They are the same for every command, so a script can branch on them without knowing which command it ran.

A failure in one project never stops the others and never leaves a half-written skill folder. The ones that worked are written, the ones that failed are named with a hint, and the code is 4.

Exit 1: something differsCopy Anchor Link

Only the commands that ask a question exit 1.

A folder that a project has and the vault has no skill for is shown by status with a ?, and it is not a difference: nothing a sync does could fix it. sync --dry-run exits 0 even when it would change something, because a dry run only shows the plan. Use --check when the script needs the answer.

Exit 2: the request cannot be carried outCopy Anchor Link

The command was understood, and it will not run as given. Nothing was written.

• A syntax error: an unknown command, a missing argument, a value that is not allowed. The message comes with the usage line.
• A write without a person to ask: error: refusing to write without confirmation, and the same for link, delete, replace and undo. Pass --yes or --dry-run.
• --json without --yes or --dry-run: error: --json cannot ask for confirmation.
• A folder with several projects below it, for changes and promote: error: 4 projects are below ~: .... Name one with --project DIR.
• skillmirror web while the web view is off, or in a build that lacks it.
• The interface in a script, where there is no terminal.
• skillmirror undo RUN with a run that does not exist: error: no backup run named "...".
• skillmirror alone, in a script: it prints the help.

Exit 3: the command could not runCopy Anchor Link

Something stands in the way that the command cannot fix. Read the message, and the hint under it.

• The configuration: an unknown key in config.yaml, a profile that extends one that does not exist, error: no vault configured, error: no scan root configured, a root that does not exist, an exclude_paths entry that matches nothing, the variables or the pointer file of the old tool.
• A name that does not exist: a skill, a group or a profile the vault does not have, a project that has no .agents/skills folder.
• A refused request: init into a folder that is not empty, new with a name that is taken, promote of a skill that was not edited, push of a skill that is not mandatory, a vault skill with changes that are not staged.
• doctor, when it finds an error.

Troubleshooting goes through the messages you are most likely to see.

Exit 4: some targets failedCopy Anchor Link

The command ran, and some of what it was asked to do did not work. It wrote what it could.

• sync, push, add, init, delete, undo: a project folder changed between the plan and the write, a skill is not tracked in the vault, a folder could not be replaced. Each failure is listed with its reason, and the others are written.
• bridge: .claude/skills is a real folder or file, so no link is made there.
• agents sync and agents add: a block that was edited by hand (--force replaces it), or a file that cannot be used.
• promote: a skill could not be replaced, or the sync after --sync had failures.
• new and adopt: a file was written, but git did not take it because the vault's .gitignore says so. The skill is not whole yet.
• init: the scaffold script of the doc-start skill failed. The skills stay, and the message names the command to run again.

Branch on itCopy Anchor Link

skillmirror sync --yes
case $? in
  0) echo "every project is in step" ;;
  4) echo "some projects failed; the others were written" ;;
  *) echo "skillmirror could not run" ;;
esac

The code tells you what happened, and the output says where. A script that has to act on the details reads --json (Scripts and CI).