SkyState CLI Reference

The SkyState CLI (skystate) lets you manage remote config, projects, and account settings directly from your terminal.

Installation

Install globally via npm:

npm install -g @skystate/cli

Global Options

These options are accepted by every command:

Option	Description
--format <format>	Output format: table (default), json, or plain
--quiet	Suppress informational output
--verbose	Print HTTP request/response debug info to stderr
--api-url <url>	Override the API base URL for this invocation
-v, --version	Print the CLI version and exit
-h, --help	Print help for any command

Output Formats

--format affects list and detail output commands (e.g., project list, status):

• table — human-readable aligned table (default)
• json — machine-readable JSON to stdout; suitable for scripting
• plain — space-separated values with no formatting

--format can also be set persistently via skystate config set format <value>.

Verbose Mode

--verbose logs curl-style request/response details to stderr. Auth tokens are redacted automatically. Use this when diagnosing API issues.

Config File Locations

The CLI uses two tiers of configuration:

Global CLI config

Stored at ~/.config/skystate/config.json (or $XDG_CONFIG_HOME/skystate/config.json). Managed with skystate config set/get/unset/list.

Valid keys:

Key	Default	Env Var Override	Description
api_url	https://api.skystate.io	SKYSTATE_API_URL	API base URL
default_project	(empty)	—	Fallback project slug when not in a repo
default_env	(empty)	—	Fallback environment slug
format	table	—	Default output format

Credentials file

Stored at ~/.config/skystate/credentials.json. Written by skystate login. Contains the JWT bearer token. File permissions are set to 0600 on creation.

Repo-local config

Stored at ./skystate.json in the repository root. Written by skystate init. Contains the project_slug field that links this repo to a SkyState project. Commit this file.

.env file

The init command writes SKYSTATE_DEV_KEY=<key> into ./.env at the repo root. Do not commit this file. The init command offers to add .env to .gitignore automatically.

Environment Variables

Variable	Purpose
SKYSTATE_TOKEN	Auth token; takes priority over the credentials file
SKYSTATE_API_URL	API base URL; takes priority over the config file api_url key
SKYSTATE_PROJECT	Project slug; takes priority over skystate.json and default_project

Token Resolution Order

1. SKYSTATE_TOKEN environment variable
2. ~/.config/skystate/credentials.json (written by skystate login)

Project Slug Resolution Order

1. SKYSTATE_PROJECT environment variable
2. project_slug in ./skystate.json (repo-local, set by skystate init)
3. default_project in the global config file (legacy fallback)

Exit Codes

Code	Meaning
0	Success
1	General error (validation, unexpected API error)
2	Authentication error — run skystate login
78	Limit exceeded (plan project or request limit reached)
79	Rate limited — monthly API request limit exceeded
80	Service unavailable — API returned 503

When a network error occurs, the CLI automatically performs a /health diagnostic and prints an additional message to stderr explaining whether the API is reachable.

Commands

Config workflow

Command	Description
skystate init	Link this repository to a SkyState project
skystate push	Push a config file to a remote environment
skystate show	Display the remote config for an environment
skystate diff	Compare configs between two environments
skystate promote	Copy config changes from one environment to another

Project management

Command	Description
skystate project list	List all projects
skystate project create	Create a new project
skystate project show	Show project details
skystate project delete	Delete a project

Auth

Command	Description
skystate login	Authenticate via GitHub OAuth
skystate logout	Clear stored credentials
skystate status	Show account and usage overview
skystate billing	Open the billing page

CLI configuration

Command	Description
skystate config set	Set a global config value
skystate config get	Get a global config value
skystate config list	List all config values and their sources
skystate config unset	Remove a config value (reverts to default)
skystate config path	Print the config file path

Typical Workflow

# 1. Authenticate
skystate login

# 2. Link your repository
cd my-project
skystate init

# 3. Push config to development
skystate push config.json --env development

# 4. Inspect the deployed config
skystate show --env development

# 5. Compare environments
skystate diff --from development --to staging

# 6. Promote changes to staging
skystate promote --from development --to staging