Exit Codes

Every CLI command in The Shift Platform exits with a semantic exit code. These codes allow agents and scripts to determine exactly what happened without parsing output text.

Exit Code Table

Code	Constant	Meaning
0	EXIT_SUCCESS	Operation completed successfully
1	EXIT_ERROR	General or unexpected error
2	EXIT_USER_ERROR	Invalid input or missing arguments
3	EXIT_NOT_INITIALIZED	No store directory found (e.g., .yellowpages/ missing)
4	EXIT_NOT_FOUND	Requested resource does not exist
5	EXIT_CONNECTION	Server unreachable (gateway or API unavailable)

EXIT_OK is exported as an alias for EXIT_SUCCESS.

Importing Exit Codes

import {
  EXIT_SUCCESS,
  EXIT_ERROR,
  EXIT_USER_ERROR,
  EXIT_NOT_INITIALIZED,
  EXIT_NOT_FOUND,
  EXIT_CONNECTION,
} from "@shift/platform-core/exit-codes";

Using Exit Codes in Commands

Within a CLI command handler, use process.exit() with the appropriate code:

import { EXIT_NOT_FOUND, EXIT_USER_ERROR } from "@shift/platform-core/exit-codes";
import { error } from "@shift/platform-core/output";

// Validate input
if (!name) {
  error("Service name is required");
  process.exit(EXIT_USER_ERROR);
}

// Handle missing resource
const service = await store.findByName(name);
if (!service) {
  error(`Service "${name}" not found`);
  process.exit(EXIT_NOT_FOUND);
}

Agent Control Flow

Agents can use exit codes for programmatic decision-making without parsing stdout. Combined with the Quiet mode, this enables clean conditional logic:

Shell Script Example

# Check if a service exists before creating it
if shift-cli yp services get my-service --quiet 2>/dev/null; then
  echo "Service already exists"
else
  exit_code=$?
  if [ $exit_code -eq 4 ]; then
    echo "Service not found, creating..."
    shift-cli yp services add --name my-service --language TypeScript
  elif [ $exit_code -eq 3 ]; then
    echo "Catalog not initialized, running init..."
    shift-cli yp init
  elif [ $exit_code -eq 5 ]; then
    echo "Server unreachable, retrying later..."
  else
    echo "Unexpected error (exit code: $exit_code)"
  fi
fi

Agent Decision Tree

An AI agent can map exit codes to specific recovery strategies:

Exit Code	Agent Action
0	Proceed with the result
1	Log error, escalate or retry
2	Fix the command arguments and retry
3	Run shift-cli yp init first, then retry
4	Create the missing resource, or adjust the query
5	Wait and retry, or check network configuration

Design Rationale

Numeric exit codes are the most universal interface a CLI can offer. They work across shells, programming languages, and operating systems. By assigning specific meanings to codes 0-5, The Shift Platform gives agents a reliable signal that does not depend on parsing text, language locale, or terminal capabilities.