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. Use public state for application config, feature flags, public settings, and client-visible catalog or inventory values.

Installation

npm install -g skystate

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

Global Options

These options are accepted by every command:

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 bearer session in ~/.config/skystate/token.json.

Public-state commands also accept a project API key from SKYSTATE_API_KEY or .env.local. API-key auth is project-scoped; developer bearer auth uses --project <slug> to select a project.

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 state user	List, show, and delete end-user state as a developer
sky examples	Print stack-specific snippets
sky config	Manage global CLI settings

Advanced Commands

sky provision scans source files for provisionable public-state declarations and writes missing top-level keys into an environment.

sky provision --project <slug> --env <env> [--path <dir>] [--dry-run] [--yes]

Use --dry-run first to review discovered keys. The command requires --project; --env can be provided directly or resolved from SKYSTATE_ENV / default_env.

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.

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)
78	Quota or plan limit exceeded
80	Service unavailable (API returned 503)

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