SkyState CLI Reference

The SkyState CLI (sky) manages developer login, projects, public state, project API keys, end-user auth settings, account terms, examples, and local CLI configuration. See what public state is for and what not to store.

Installation

npm install -g skystate

This provides both the sky and skystate binaries. View the package on npm.

Global Options

These options are accepted on every command. --format only changes output where a command documents it; other commands ignore it.

Option	Description
--format <format>	Output format: table, json, or plain. Some commands support only a subset.
--quiet	Suppress informational output.
--verbose	Print HTTP request/response debug info to stderr.
--api-url <url>	Override the API base URL for this invocation. Hidden from normal help.
--auth-url <url>	Override the hosted auth URL for this invocation. Hidden from normal help.
-v, --version	Print the CLI version and exit.
-h, --help	Print help for any command.

Auth Resolution

sky login stores a developer session locally.

Public-state commands (sky state public show, push, edit, diff, promote, patch, remove, and sky provision) accept a project API key. When a key is present it is used; otherwise the developer session is used. Provide a key with the SKYSTATE_API_KEY environment variable, or keep one in a .env.local file in the directory you run sky from; SKYSTATE_API_KEY takes precedence. Everything else (projects, user state, API key management, hosted auth settings, and account terms) uses the developer session only; sky status reports both credentials. --project <slug> selects the project for all of these commands.

Environments

Commands that read or write public state or user state accept --env <slug>. <slug> is the full name (development, staging, production) or the alias (dev, stg, prod). See Environments for what an environment is and how they relate to each other.

When --env is omitted, it resolves in this order: the SKYSTATE_ENV environment variable, then default_env from CLI config.

Command Tree

Command	Purpose
sky login	Start the hosted developer login flow
sky logout	Clear the local developer session
sky terms	View current Terms of Service acceptance
sky terms accept	Accept the current Terms of Service
sky onboarding	Interactive project and starter-snippet wizard
sky status	Show account, API key, project, and usage status
sky project	List, create, show, and delete projects
sky project keys	Create, list, and revoke project API keys
sky project auth	Manage end-user auth settings and callback URLs
sky state public show	Read the latest public state for an environment
sky state public push	Replace public state with JSON from a file, inline string, or stdin
sky state public edit	Edit public state in $VISUAL or $EDITOR
sky state public diff	Diff public state between two environments
sky state public promote	Promote public-state changes from one environment to another
sky state public patch	Patch a single public-state path or replace the root object
sky state public remove	Remove one public-state path idempotently
sky provision	Add public-state keys discovered by scanning source code
sky state user	List, show, and delete end-user state as a developer
sky examples	Print stack-specific snippets
sky config	Manage global CLI settings

Output Formats

--format affects list and detail output commands such as project list and status:

• table - human-readable aligned table
• json - machine-readable JSON to stdout
• plain - tab-separated or compact output where supported

Not all commands support all formats. show supports json and plain. diff, promote, patch, and remove support plain and json; promote writes JSON only with --dry-run (see sky state public promote).

Exit Codes

Code	Meaning
0	Success
1	General error, validation error, network failure, or API failure
2	Authentication error (no token, expired, or 401)
3	Differences found (sky state public diff)
77	Forbidden (authenticated but not authorized for this project)
78	Quota or plan limit exceeded
80	Service unavailable (API returned 503)

Commands print diagnostics to stderr. Machine-readable output goes to stdout.