flexkit deployments

Browses the schema deployment history of a project. Every flexkit deploy, and every schema change the Flexkit Agent applies, creates a deployment that records who started it, what it changed, the stages it went through and how it ended. Use these commands to find a failed deployment and read its errors, to see what a deployment changed, or to wait for a deployment started elsewhere.

Synopsis

flexkit deployments <subcommand> [arguments] [options]

Running flexkit deployments without a subcommand runs flexkit deployments ls.

The subcommands act on the project selected by --project, the FLEXKIT_PROJECT_ID environment variable, the folder’s flexkit link, or the only project in flexkit.config.ts, in that order. You need to be a member of the project, or an owner of its team.

deployments ls

Lists deployments, newest first: id, state, entity and attribute counts, author (with via cli or via agent), creation time and duration. The deployment whose schema is live is marked ● live. Alias: list.

The API returns 25 deployments per page. --limit fetches as many pages as needed; when more deployments remain, the command prints a --cursor value to continue from.

flexkit deployments ls [--state <state>] [--mine] [--limit <n>] [--cursor <cursor>] [--json]

--state accepts running (any state that has not finished), queued, validating, building, uploading, activating, completed, failed or all (the default).

Examples

# List recent deployments
flexkit deployments ls
 
# List your failed deployments
flexkit deployments ls --state failed --mine
 
# List the last 100 deployments of another project
flexkit deployments ls -p k3m9x2q7wd --limit 100
 
# Print the id of the deployment that is live
flexkit deployments ls --json | jq -r .activeDeploymentId

With --json, the output is { items, nextCursor, hasActive, activeDeploymentId }; hasActive is true while a deployment is running.

deployments inspect

Shows one deployment: state, author, timings, entity and attribute counts, the deploy options it used (--force, --allow-breaking-changes), the error with its code, path and hint when it failed, warnings, and the stage history. With --diff, it also prints what the deployment changed compared with the schema that was live before it, in the same format as flexkit schema diff. Alias: get.

flexkit deployments inspect <id> [--diff] [--json]

Examples

# Inspect a deployment
flexkit deployments inspect 0b6f1c52-8a43-4d7e-9a51-3f2e8c1d4b90
 
# See what a deployment changed
flexkit deployments inspect 0b6f1c52-8a43-4d7e-9a51-3f2e8c1d4b90 --diff
 
# Print the error of the latest failed deployment
flexkit deployments inspect $(flexkit deployments ls --state failed --json | jq -r '.items[0].id') --json | jq .error

With --json, the output includes the deployed snapshot and the previous baseline (schema, scopes, spaces, studioConfig, schemaHash).

deployments logs

Prints the progress of a deployment: its stage history so far, then each state change as it happens until the deployment completes or fails. The command exits with code 1 when the deployment failed, so a script can wait on a deployment started by another job or by the Flexkit Agent.

flexkit deployments logs <id> [--no-follow] [--json]

Examples

# Follow a running deployment
flexkit deployments logs 0b6f1c52-8a43-4d7e-9a51-3f2e8c1d4b90
 
# Wait for the running deployment and fail the job if it fails
flexkit deployments logs $(flexkit deployments ls --state running --json | jq -r '.items[0].id')
 
# Print the stages of a finished deployment as JSON
flexkit deployments logs 0b6f1c52-8a43-4d7e-9a51-3f2e8c1d4b90 --no-follow --json

With --json, nothing is printed until the deployment finishes; then the command prints { id, state, stageHistory, events, error }.

Options

See also the global options.

Common workflows

Find out why a deploy failed

# The latest failed deployment, with its error, hint and stages
flexkit deployments ls --state failed --limit 1
flexkit deployments inspect <id>

Compatibility errors link to their page under Schema Deploy Errors.

Audit schema changes

# Who changed the schema recently, and what changed
flexkit deployments ls --state completed --limit 10
flexkit deployments inspect <id> --diff

Wait for a deployment in CI

flexkit deploy already waits for its own deployment. To wait for one started elsewhere (another job, or the Flexkit Agent in a project whose schema is managed in the app), follow it with logs:

id=$(flexkit deployments ls --state running --json | jq -r '.items[0].id // empty')
[ -n "$id" ] && flexkit deployments logs "$id"