--- title: 'flexkit deployments' description: 'Reference and usage guidance for flexkit deployments.' --- # `flexkit deployments` Browses the schema deployment history of a project. Every [`flexkit deploy`](/docs/cli/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 ```bash flexkit deployments [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`](/docs/cli/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. ```bash flexkit deployments ls [--state ] [--mine] [--limit ] [--cursor ] [--json] ``` `--state` accepts `running` (any state that has not finished), `queued`, `validating`, `building`, `uploading`, `activating`, `completed`, `failed` or `all` (the default). ### Examples ```bash # 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`](/docs/cli/schema#schema-diff). Alias: `get`. ```bash flexkit deployments inspect [--diff] [--json] ``` ### Examples ```bash # 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. ```bash flexkit deployments logs [--no-follow] [--json] ``` ### Examples ```bash # 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 | Option | Subcommands | Description | | ---------------------- | ----------- | -------------------------------------------------------------------------------------------- | | `--state, -s ` | `ls` | Only deployments in this state, or `running` for any unfinished state. Default: `all`. | | `--mine, -m` | `ls` | Only deployments you started. | | `--limit, -n ` | `ls` | Maximum number of deployments to list. Default: 25. | | `--cursor ` | `ls` | Continue a previous listing from the cursor it printed. | | `--diff` | `inspect` | Print the schema changes of the deployment (previous schema → this deployment). | | `--no-follow` | `logs` | Print what happened so far and exit instead of waiting for the deployment to finish. | | `--json` | all | Print JSON on stdout. | | `--project, -p ` | all | Project to use. Defaults to the linked project or the only project in the config. | See also the [global options](/docs/cli/global-options). ## Common workflows ### Find out why a deploy failed ```bash # The latest failed deployment, with its error, hint and stages flexkit deployments ls --state failed --limit 1 flexkit deployments inspect ``` Compatibility errors link to their page under [Schema Deploy Errors](/docs/errors/schema). ### Audit schema changes ```bash # Who changed the schema recently, and what changed flexkit deployments ls --state completed --limit 10 flexkit deployments inspect --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`: ```bash id=$(flexkit deployments ls --state running --json | jq -r '.items[0].id // empty') [ -n "$id" ] && flexkit deployments logs "$id" ``` --- [View full sitemap](/docs/sitemap.md)