skystate promote

Promote config changes from one environment to another.

Synopsis

skystate promote --from <env> --to <env> [--yes] [--keys <keys>] [--dry-run]

Description

Compares the source and target environments, presents the differences as hunks, and lets you selectively stage which changes to apply. Staged changes are written to the target environment as a new config version.

promote uses optimistic concurrency: the target config version is recorded when the diff is fetched. If another push modifies the target between fetching the diff and applying it, the API returns a 409 Conflict and you are asked to run promote again.

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. Same values as --from.
--yes	Stage all changes without prompting. Required in non-interactive (non-TTY) mode.
--keys <keys>	Comma-separated list of top-level keys to include in the promotion. Other keys are ignored.
--dry-run	Show the diff without applying any changes. Exits after printing the diff.

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

Environment aliases

Alias	Full name
dev	development
stg	staging
prod	production

Interactive mode (default)

Without --yes, promote enters an interactive hunk-by-hunk review:

[1/3] featureFlags (replace)
  source (development v1.5.0):
    darkMode: true
    newCheckout: true
  target (staging v1.3.0):
    darkMode: false
    newCheckout: false

Stage this change? [y/n/d/a/q]

Hunk review keys

Key	Action
y	Stage this hunk (include in promotion)
n or Enter	Skip this hunk (keep the target value)
d	Enter a custom value for the target key
a	Stage this hunk and all remaining hunks
q	Abort the entire promotion without applying any changes

After reviewing all hunks, a confirmation summary is shown:

Staged changes:
  featureFlags  replace  -> { darkMode: true, newCheckout: true }
  limits        add      -> { maxRetries: 5 }

Apply these changes? [y/N]

Non-interactive mode (--yes)

All hunks are staged without prompting. The confirmation summary is skipped. Use this in CI pipelines.

skystate promote --from staging --to production --yes

Running without --yes in a non-TTY environment raises an error:

Error: Non-interactive mode requires --yes flag.

--dry-run mode

Prints the diff (identical to skystate diff output) without applying any changes. Exits with code 0 even if differences exist.

Default output:

[1/2] featureFlags (replace)
  source (development v1.5.0):
    darkMode: true
  target (staging v1.3.0):
    darkMode: false

[2/2] limits (add)
  source (development v1.5.0): { maxRetries: 5 }

With --format json:

[
  {
    "key": "featureFlags",
    "type": "replace",
    "sourceValue": { "darkMode": true },
    "targetValue": { "darkMode": false }
  }
]

--keys filtering

When --keys is provided, only the listed top-level keys are included in the diff and promotion. Keys not present in the diff produce a warning:

Warning: key "nonexistent" not found in diff.

Examples

# Interactive promotion from development to staging
skystate promote --from development --to staging

# Promote all changes non-interactively (CI)
skystate promote --from staging --to production --yes

# Preview what would be promoted
skystate promote --from dev --to prod --dry-run

# Promote only specific keys
skystate promote --from dev --to staging --keys featureFlags,limits

# Non-interactive partial promotion
skystate promote --from dev --to prod --keys featureFlags --yes

# Dry-run with JSON output
skystate promote --from dev --to staging --dry-run --format json

Output (success)

Promoted 2 change(s) to staging (v1.4.0).

Errors

Situation	Exit Code	Message
--from or --to not specified	error	Commander required option error
Invalid environment value	1	Error: Invalid source/target environment "xyz". Must be one of: dev, stg, prod (or development, staging, production)
--from equals --to	1	Error: Source and target environments must be different.
Non-TTY without --yes	1	Error: Non-interactive mode requires --yes flag. with hint Run: skystate promote --from dev --to prod --yes
Source environment has no config	1	Error: No config found in source environment "development". with hint Push config to development first via the dashboard.
No differences found	—	No differences found between development and staging. (exits 0)
Nothing staged	—	Nothing staged. No changes applied. (exits 0)
Conflict (target modified concurrently)	1	Conflict: the target environment was modified since you fetched the diff. Run promote again to get a fresh diff.
Aborted by user	—	Aborted. (exits 0)
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

Troubleshooting

• Conflict error — another push happened between your diff and your apply. Run promote again to fetch a fresh diff.
• Nothing staged — you skipped all hunks. No changes were made.
• Target missing — if the target environment has never had config pushed, promote treats it as an empty config ({}), so all source keys appear as add hunks.

Dashboard equivalent

The Remote Config tab in the dashboard at https://app.skystate.io includes a visual promote workflow with per-key selection.