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, keeps your edits in a temp file, and exits without saving (see Conflict recovery).

Authentication follows the CLI auth resolution rules.

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 value may contain arguments, for example code --wait; the temp file path is appended as the last argument.

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 --file <path> or sky state public patch

Unchanged-save behavior

If the edited document is equal to the original (key order and whitespace do not count), no new version is written and the command 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: <path>

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 modified while you were editing.
Your edits are preserved at: <path>
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. See Environments.
--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 command prints a confirmation line and the new version metadata to stderr:

Saved development
Environment: development
Version: v4
Created: 2026-04-25 12:34 UTC
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 modified while you were editing.
No login and no API key	1	Not authenticated. Run: sky login