Errors and Failure Modes

General format

User-facing CLI errors are written to stderr in the format:

error: <message>

The command exits with a non-zero exit code.

Common blocking situations

Situation	What it means	What to do
Local changes during sync	sync may overwrite the working tree	run aiman push, save changes manually, or use --force
Remote is ahead during push	the published state has moved forward	run aiman sync
Git history has diverged	AIM cannot safely choose a state	restore Git manually
AI environment not found	adapter could not find the base dir	set the path in aim.local.yaml
MCP env not set	a required variable is missing	enter during sync or add to aim.local.yaml
Invalid Skill	missing name, filename mismatch, or empty body	fix skills/<name>.md
Invalid MCP Item	missing required field or invalid YAML	fix mcp/<name>.yaml
No access to remote	Git cannot read or write the repository	check network, credentials, and permissions

--dry-run

For potentially destructive operations, run dry-run first:

aiman push --dry-run
aiman sync --dry-run
aiman apply --dry-run

Dry-run shows the plan without writing to Git, the inventory repository, or AI environments.

--force

aiman sync --force allows local changes to be overwritten when applying the published state.

Use this flag only if the local working tree can be safely discarded or restored.