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
Untracked file conflicts with remote during sync	a file in skills/ or mcp/ matches by name a file from remote	rename the file, publish it via aiman push, or use --force (the conflicting file will be deleted)
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 removes untracked files in skills/ and mcp/ that conflict by name with remote files, then applies the published state. Files without conflicts are always preserved.

Use this flag only if the conflicting files can be safely deleted. The deletion is permanent.