sky state public edit

Open the current state in your editor and save changes back to the remote environment.

Synopsis

sky state public edit --project <slug> [--env <slug>] [--comment <message>]

Description

Fetches the current state for the specified project and environment, opens it in your configured editor, and saves the result if anything changed.

The command uses optimistic concurrency: the current version is recorded when the state is fetched. If another write modifies the state while you are in the editor, the command reports a conflict and exits without saving. Re-run edit to start fresh with the latest state.

You can authenticate with a developer bearer session from sky login or a project API key from SKYSTATE_API_KEY / .env.local.

Editor resolution

The command checks $VISUAL first, then $EDITOR. Whitespace-only values are treated as unset. If neither variable is set, the command exits with an error and a hint to set $EDITOR.

The editor command is parsed into an executable plus arguments and launched directly with the temp file path appended. Multi-word editor strings like code --wait work correctly. If the editor executable path itself contains spaces, quote it inside the environment variable, for example EDITOR='"/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" --wait'.

Non-TTY refusal

edit requires an interactive terminal. Running it from a script or piped context exits with:

Error: edit requires an interactive terminal.

Hint: For non-interactive use, try: sky state public push --project <slug> --file <path> or sky state public patch --project <slug>

Unchanged-save behavior

After you close the editor, the command compares the edited content to the original using a deep semantic comparison. Key reordering and whitespace reformatting count as unchanged. If no values differ, the command skips the PUT request and prints:

No changes.

Invalid JSON recovery

If the editor produces invalid JSON, the temp file is preserved and the error message includes the path:

Error: Invalid JSON after editing. Your edits are preserved at: /tmp/skystate-edit-XXXXX/state.json

Copy the path, fix the JSON in another editor, then push it with sky state public push --project <slug> --file <path>.

Conflict recovery

If the state was updated by another client while you were editing:

Conflict: state was updated to v5 while you were editing.
Re-run: sky state public edit to start fresh with the latest state.

Re-running edit fetches the current state again and opens a fresh session.

FLAGS

Option	Description
--project <slug>	(Required) Project slug.
--env <slug>	Target environment. Accepts development, staging, production, or aliases dev, stg, prod. Resolved from SKYSTATE_ENV or default_env config if not specified.
--comment <message>	Commit message attached to the new version.

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

EXAMPLES

# Edit development state in the default $EDITOR
$ sky state public edit --project my-app --env development

# Edit production state with a version comment
$ sky state public edit --project my-app --env production --comment "release v2"

# Use nano for this session only
$ EDITOR=nano sky state public edit --project my-app --env staging

Output (success)

On a successful save, the new version metadata is written to stderr:

development v4
created: 2026-04-25T12:34:56.000Z
comment: Release flags

The comment line is omitted when no comment was provided.

Errors

Situation	Exit Code	Message
Not run in a TTY	1	Error: edit requires an interactive terminal.
$VISUAL and $EDITOR both unset	1	Error: No editor configured. with hint Set $EDITOR (e.g. export EDITOR=vim) and re-run.
--env not specified and not resolvable	1	Error: Missing required option: --env
Invalid environment	1	Error: Invalid environment "xyz". Must be one of: dev, stg, prod (or development, staging, production)
Project or environment not found	1	Error: Project 'slug' or environment 'env' not found.
Invalid JSON saved	1	Error: Invalid JSON after editing. Your edits are preserved at: <path>
State is not a JSON object	1	Error: State must be a JSON object, not an array or primitive.
Conflict (concurrent update)	1	Conflict: state was updated to vN while you were editing.
Not authenticated	2	Not authenticated. Run: sky onboarding

LEARN MORE

• sky state public push - push a full state file non-interactively
• sky state public show - display current state without editing
• sky state public promote - copy state between environments