---
title: 'flexkit schema'
description: 'Reference and usage guidance for flexkit schema.'
---

# `flexkit schema`

Inspects the schema deployed to a project and compares it with your local `flexkit.config.ts`. Use it to see what the Studio and the GraphQL API currently serve, to save a snapshot of the deployed schema, and to preview what the next [`flexkit deploy`](/docs/cli/deploy) will change before you run it.

`flexkit schema` only reads. To change the deployed schema, edit `flexkit.config.ts` and run `flexkit deploy`.

## Synopsis

```bash
flexkit schema <subcommand> [arguments] [options]
```

Running `flexkit schema` without a subcommand runs `flexkit schema show`.

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.

Reading the deployed schema works with your [`flexkit login`](/docs/cli/login) session or with a project [API token](/docs/api/tokens) of any role, so the commands also run in CI.

## `schema pull`

Downloads the deployed schema as JSON: the entities, scopes, spaces, Studio title, menu groups and the schema hash. Reserved entities (`_asset`, `_tag`) are not included. Without a file, the JSON is printed on stdout so it can be piped. When the file already exists, the CLI asks before overwriting it; pass `--yes` to overwrite without asking.

```bash
flexkit schema pull [file] [--schema-only] [--yes]
```

### Examples

```bash
# Save the deployed schema to a file
flexkit schema pull deployed-schema.json

# Print the deployed schema of another project
flexkit schema pull -p k3m9x2q7wd

# List the deployed entity names
flexkit schema pull --schema-only | jq -r '.[].name'

# Refresh a committed snapshot without a prompt
flexkit schema pull schema.snapshot.json --yes
```

The full output has this shape:

```json
{
  "projectId": "k3m9x2q7wd",
  "title": "Acme Store",
  "schema": [{ "name": "product", "plural": "products", "attributes": [] }],
  "scopes": [{ "name": "default", "label": "Default", "isDefault": true }],
  "spaces": [{ "code": "retail", "label": "Retail" }],
  "menuGroups": [],
  "schemaHash": "v9-4f1c…"
}
```

## `schema show`

Summarizes the deployed schema: one row per entity with its plural, attribute count, relationship count, menu group and spaces, followed by the scopes, spaces and menu groups. With `--entity`, lists the attributes of one entity with their label, data type, scope, input type, relationship target, flags (`required`, `unique`, `searchable`, `hidden`, `read-only`) and spaces. `--local` reads `flexkit.config.ts` instead of the deployed schema.

```bash
flexkit schema show [--entity <name>] [--local] [--json]
```

### Examples

```bash
# Summarize the deployed schema
flexkit schema show

# List the attributes of the product entity (name or plural)
flexkit schema show --entity product

# Summarize the local config before deploying it
flexkit schema show --local

# Print the names of the required attributes of an entity
flexkit schema show -e order --json | jq -r '.attributes[] | select(.isRequired) | .name'
```

## `schema diff`

Compares the schema in the local `flexkit.config.ts` with the deployed one and shows what a deploy would change:

- entities and attributes that are added (`+`), removed (`-`) or changed (`~`), with every changed field shown as `old → new`;
- scopes, spaces and menu groups that are added, removed or changed, and the Studio title when the config sets one;
- a change in the order of entities or attributes (it changes the sidebar and form order).

Changes are classified like the deploy compatibility check:

| Change                         | Severity     | What `flexkit deploy` does                                                                                       |
| ------------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------- |
| Entity removed                 | **breaking** | Refuses unless you pass `--allow-breaking-changes`. See [Entity removed](/docs/errors/schema/entity-removed).     |
| Attribute removed              | **breaking** | Refuses unless you pass `--allow-breaking-changes`. See [Attribute removed](/docs/errors/schema/attribute-removed). |
| Attribute data type changed    | **blocking** | Always refuses. See [Attribute data type changed](/docs/errors/schema/attribute-data-type-changed).              |
| Attribute scope changed        | warning      | Deploys, with a warning.                                                                                         |
| Space removed                  | warning      | Deploys when the space is unused; refuses without `--allow-breaking-changes` while it has members or automations. |

Without `--project` (or `FLEXKIT_PROJECT_ID`), every project in the config is compared.

```bash
flexkit schema diff [--exit-code] [--fail-on-breaking] [--json]
```

### Examples

```bash
# Preview what the next deploy changes
flexkit schema diff

# Compare one project of a multi-project config
flexkit schema diff -p k3m9x2q7wd

# Exit with code 1 when the config and the deployed schema differ
flexkit schema diff --exit-code

# Exit with code 1 only for breaking or blocking changes
flexkit schema diff --fail-on-breaking

# List the compatibility issues as JSON
flexkit schema diff --json | jq '.[].diff.issues'
```

Example output:

```text
k3m9x2q7wd deployed → flexkit.config.ts

Entities
  + order (6 attributes)
  ~ product
      + sku string, global
      - legacyCode BREAKING
      ~ price BLOCKING
          dataType: "int" → "float"
      ~ name
          label: "Name" → "Product name"

Compatibility
  blocking Attribute "product.price" changes data type from "int" to "float". …
  breaking Attribute "product.legacyCode" is removed. …

  Entities: 1 added, 1 changed. 1 blocking, 1 breaking.
```

With `--json`, the command prints an array with one object per project: `{ projectId, schemaHash, diff }`, where `diff` holds `hasChanges`, `entities`, `scopes`, `spaces`, `menuGroups`, `entitiesReordered`, `title` and `issues` (each with `severity`, `path` and `message`).

## Options

| Option                 | Subcommands | Description                                                                         |
| ---------------------- | ----------- | ----------------------------------------------------------------------------------- |
| `--schema-only`        | `pull`      | Write only the entities array instead of the full response.                         |
| `--entity, -e <name>`  | `show`      | Show the attributes of one entity, by name or plural.                               |
| `--local`              | `show`      | Summarize the local `flexkit.config.ts` instead of the deployed schema.             |
| `--exit-code`          | `diff`      | Exit with code 1 when there are differences.                                        |
| `--fail-on-breaking`   | `diff`      | Exit with code 1 only when a difference is breaking or blocking.                    |
| `--json`               | all         | Print JSON on stdout (`pull` always prints JSON).                                   |
| `--yes, -y`            | `pull`      | Overwrite the output file without asking.                                           |
| `--project, -p <id>`   | 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), such as `--local-config` to point at a config file in another folder.

## Common workflows

### Review a schema change before deploying

```bash
# See the change, then deploy it
flexkit schema diff
flexkit deploy

# A removal you intend to make
flexkit schema diff            # shows the BREAKING removal
flexkit deploy --allow-breaking-changes
```

### Guard pull requests

Run the diff in a pull request job to fail it when the change would be refused, or to make any schema drift visible. Exit codes: `0` no (relevant) differences, `1` differences found or the command failed.

```bash
# Fail the job on removals and data type changes
flexkit schema diff --fail-on-breaking

# Fail the job whenever flexkit.config.ts is not deployed yet
flexkit schema diff --exit-code
```

In CI, set `FLEXKIT_TOKEN` to a project API token; a Viewer token is enough to read the schema.

### Keep a snapshot of the deployed schema

```bash
# Commit the deployed schema next to the config to review it over time
flexkit schema pull schema.snapshot.json --yes
git diff --stat schema.snapshot.json
```


---

[View full sitemap](/docs/sitemap.md)