skystate diff

Show differences between two environments.

Synopsis

skystate diff --from <env> --to <env> [--keys <keys>] [--format <format>]

Description

Compares the latest config versions of two environments for the linked project and outputs the differences. If the configs are identical, the command exits silently with code 0. If differences are found, they are printed and the command exits with code 1.

This non-zero exit on differences makes diff suitable for use in CI pipelines that should fail when environments are out of sync.

The repo must already be linked via skystate init.

Options

Option	Description
--from <env>	(Required) Source environment. Accepts development, staging, production, or aliases dev, stg, prod.
--to <env>	(Required) Target environment. Accepts the same values as --from.
--keys <keys>	Comma-separated list of top-level keys to compare. Other keys are ignored.
--format <format>	Output format. json outputs raw hunk data to stdout. Default is ANSI-coloured diff to stdout.

Global options (--verbose, --api-url) are also accepted. See global options.

Environment aliases

Alias	Full name
dev	development
stg	staging
prod	production

Exit codes

Code	Meaning
0	No differences found (environments are identical)
1	Differences found (or an error occurred)

Examples

# Compare development to staging
skystate diff --from development --to staging

# Use environment aliases
skystate diff --from dev --to prod

# Compare only specific keys
skystate diff --from dev --to prod --keys featureFlags,limits

# JSON output for scripting
skystate diff --from dev --to staging --format json

# Use in CI — fail if dev and staging differ
skystate diff --from dev --to staging && echo "In sync" || echo "Out of sync"

Output (default ANSI format)

Each changed key is shown as a numbered hunk:

[1/2] featureFlags (replace)
  source (development v1.2.0):
    darkMode: false
    newCheckout: false
  target (staging v1.1.0):
    darkMode: true
    newCheckout: false

[2/2] limits.maxRetries (replace)
  source (development v1.2.0): 5
  target (staging v1.1.0): 3

Hunk types:

Type	Meaning
add	Key exists in source, missing in target
remove	Key exists in target, missing in source
replace	Key exists in both but values differ

If there are no differences, the command produces no output and exits with code 0.

Output (JSON format, --format json)

[
  {
    "key": "featureFlags",
    "type": "replace",
    "sourceValue": { "darkMode": false, "newCheckout": false },
    "targetValue": { "darkMode": true, "newCheckout": false }
  },
  {
    "key": "limits.maxRetries",
    "type": "replace",
    "sourceValue": 5,
    "targetValue": 3
  }
]

--keys filtering

When --keys is provided, only the listed top-level keys appear in the diff. Keys in --keys that are not present in the diff produce a warning on stderr:

Warning: key "nonexistent" not found in diff.

Errors

Situation	Exit Code	Message
--from not specified	error	Commander required option error
--to not specified	error	Commander required option error
Invalid source environment	1	Error: Invalid source environment "xyz". Must be one of: dev, stg, prod (or development, staging, production)
Invalid target environment	1	Error: Invalid target environment "xyz". Must be one of: ...
--from and --to are the same	1	Error: Source and target environments must be different.
Source has no config	1	Error: No config found in source environment "development". with hint Push config to development first via the dashboard.
No project linked	1	Error: No project linked. with hint Run: skystate init
Not authenticated	2	Not authenticated. Run: skystate login
Network error	1	Error: Network error -- check your connection and try again

Note: if the target environment has no config, it is treated as an empty object {}. All source keys appear as add hunks.

Dashboard equivalent

The Remote Config tab in the dashboard at https://app.skystate.io includes a visual diff view that compares environments side by side.