CLI Overview

The shift-cli binary wraps all platform services into a single command-line interface. It communicates with the Shift gateway over HTTP and exposes both platform-level commands and service-specific subcommands.

Output Modes

Every command supports three output modes:

Mode	Flag	Description
Human-readable	(default)	Chalk-colored, formatted for terminals
JSON	--json	Structured output for agent and programmatic consumption
Quiet	--quiet	Exit codes only, no stdout

Configuration Files

File	Purpose
~/.shift/config.json	CLI configuration (gateway URL, defaults)
~/.shift/auth.json	Authentication tokens

Both files are created with restrictive permissions (mode 0o600).

Command Shape

Platform commands live at the top level:

shift-cli status
shift-cli login
shift-cli create-app my-app
shift-cli token create --session <id>
shift-cli test bootstrap --session <id>

Service commands follow a consistent pattern:

shift-cli <service> <subcommand> [arguments] [flags]

For example:

shift-cli yp services list --json
shift-cli pulse events track "deploy" --quiet
shift-cli stage new --json
shift-cli stage repo status --json

How It Works

The CLI sends HTTP requests to the Shift gateway, which routes them to the appropriate service API. Some commands, such as shift-cli create-app, also write local project files or inspect local git state.

App Workspace Commands

The shift-cli app command suite manages app-local workspace state, syncing platform context into your project:

shift-cli app sync-context          # Pull dynamic service context into .shift/state
shift-cli app refresh-skills        # Refresh CLAUDE/AGENTS and bundled skills
shift-cli app push ./src /app       # Sync context, push to Stage, refresh snapshots

These commands work with the .shift/ directory in your project root:

Path	Purpose
.shift/stage-app.config.json	Session and app tracking
.shift/state/manifest.json	App state manifest with service context
.shift/state/services/<name>.json	Per-service snapshots
.shift/compute/config.json	Compute module configuration

Sandbox Commands

The shift-cli sandbox commands manage isolated multi-agent sessions:

shift-cli sandbox create --name my-session
shift-cli sandbox list
shift-cli sandbox push <session-id> ./workspace
shift-cli sandbox auth <session-id> claude
shift-cli sandbox exec <session-id> --cmd "bun test" --timeout 5m
shift-cli sandbox rm <session-id>

Each sandbox session provides isolated workspace, home, and tmp directories for shared agent work.

Local Testing Helpers

Two top-level commands support delegated local test flows:

• shift-cli token creates and revokes short-lived delegated grants
• shift-cli test bootstrap turns a delegated grant into a one-time browser bootstrap artifact

These commands are primarily used with Stage sessions, @the-shift/sdk/testing, and Playwright-based app checks.

Exit Codes

Commands use semantic exit codes to indicate results:

Code	Name	Meaning
0	EXIT_SUCCESS	Operation completed
1	EXIT_ERROR	General error
2	EXIT_USER_ERROR	Invalid input or missing arguments
3	EXIT_NOT_INITIALIZED	No store directory or config found
4	EXIT_NOT_FOUND	Resource not found
5	EXIT_CONNECTION	Server unreachable