Exit codes

What each alis exit code means and the error codes that accompany it. For scripts and agents that branch on the result of a command.

Codes

Code	Meaning	What accompanies it
0	Success.	The result on stdout.
1	Failure: invalid usage, or the remote operation failed.	Under --json, stdout still holds a structured failure: the final operation with error, or an error envelope.
3	Confirmation required. The command refused to proceed without explicit approval.	An envelope with code PRODUCTION_CONFIRMATION_REQUIRED (production deploy, or changing or revealing a production deployment environment's variables) or APPROVAL_REQUIRED (the user's automation tier gates this command). retry holds the exact re-run command. alis skills publish and alis skills improve also exit 3 with remote_changed.
4	Unauthenticated.	Run alis login, then retry.
5	No change. A wait reached its --timeout with nothing new.	reply_timeout from alis specialist wait. Not a failure.
130	alis run was interrupted with Ctrl-C.
other	An external kill, or the exit status of the program alis run started.	Treat as code 1.

Error envelope

Pre-flight failures (before an operation exists) and refusals print one JSON envelope on stdout under --json:

JSON

{
  "error": {
    "code": "ENVIRONMENT_SELECTION_REQUIRED",
    "message": "…",
    "retry": "alis deploy acme.shop.orders.v1 --json -e <env-id>",
    "retryArgv": ["alis", "deploy", "acme.shop.orders.v1", "--json", "-e", "<env-id>"],
    "retryCwd": "/home/me/alis.build/acme/build/shop/orders/v1",
    "agent": "…",
    "details": {}
  }
}

Field	Meaning
code	A stable, upper-case or snake_case error code.
message	Human-readable explanation.
retry	The readable recovery command, when there is one.
retryArgv, retryCwd	The recovery command's arguments and working directory, when present.
agent	Instructions for a coding agent on what to do next.
details	Optional structured data, for example the deployment environments to choose between.

Without --json, stdout is a human summary of the same failure.

Error codes by exit code

Exit 1

Code	Meaning	Recovery
ERROR	Unclassified failure.	Read message.
TIMEOUT	A headless invocation (--json, or stdin/stdout not a terminal) overran its budget, usually a prompt nobody could answer. details.phase names the step.	Run retry once. If it repeats, alis doctor --json carries the command log. ALIS_COMMAND_TIMEOUT=<duration> overrides the budget.
TTY_REQUIRED	Bare alis (the TUI) was run without a terminal on both stdin and stdout.	Use subcommands with --json; retry is alis setup status --json.
LOGIN_CODE_REQUIRED	Bare alis login was run headless.	Print the URL with alis login --json, then alis login <code> --json.
ACTIVE_BUILD_ACCOUNT_REQUIRED	The session carries no active account.	alis accounts list --json, ask the user which account should own Build usage, then alis accounts select accounts/<id> --json.
ENVIRONMENT_SELECTION_REQUIRED	-e omitted and the product has more than one environment.	Choose from details; ids also come from alis context view --json.
ENV_NOT_FOUND	alis run: the product has no .alis/.env.	alis environment refresh <org>.<product>.<env> --output <product>/.alis/.env.
NETWORK_UNAVAILABLE, network_unreachable	This environment cannot reach the platform. Nothing was sent.	Retry once with network access; do not infer an outage.
product_exists, service_exists	A creation was repeated.	Follow agent instead of repeating the mutation.
backend_outdated	The backend predates this feature.	Retry later; for skills, use the MCP skills tools.
no_answer	alis ask found nothing to cite.	Rephrase as a fuller question.
CONFIG_REQUIRED, INVALID_CONFIG	alis blocks install for a dedicated-service block without, or with a malformed, --config.	Load the block's skill for the schema.
workstation_not_found, workstation_ambiguous, workstation_failed, workstation_wait_timeout, herdr_missing, herdr_outdated	Workstation commands.	See alis workstation.
recipient_not_found, recipient_ambiguous, recipient_not_member, recipient_is_self, recipient_invalid, product_required, product_not_found, send_denied, ticket_resolved, message_too_large, message_not_utf8, message_file_unreadable, message_changed, unsupported_backend	Specialist messaging. Every envelope says whether the message was sent.	See alis specialist.
skill_exists, not_editable, nothing_to_apply, inputs_missing, invalid_generator, no_workspace, no_cases, harness_not_found, unmanaged_target, not_installed, domain_share_refused, not_curator, last_owner, not_owner, builder_not_found, github_not_connected, improve_timeout, improve_failed	Skills.	See alis skills.

Exit 3

Code	Lifted by
PRODUCTION_CONFIRMATION_REQUIRED	Re-running with --confirm-production after explicit human approval. --approve and --yes never lift it.
APPROVAL_REQUIRED	Re-running the envelope's retry, which carries --approve, after the user approves.
remote_changed	alis skills publish --force, or alis skills edit --refresh to rebase.

Exit 4

Code	Recovery
signed_out	The user runs alis login.

Exit 5

Code	Meaning
reply_timeout	alis specialist wait saw no new reply before --timeout.

Related: Output contract, Diagnose problems.