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 will change before you run it.

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

Synopsis

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, or the only project in flexkit.config.ts, in that order.

Reading the deployed schema works with your flexkit login session or with a project API token 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.

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

Examples

# 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:

{
  "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.

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

Examples

# 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:

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

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

Examples

# 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:

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

See also the global options, such as --local-config to point at a config file in another folder.

Common workflows

Review a schema change before deploying

# 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.

# 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

# 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