---
title: schema push
description: Loads the schema exported from an entry file, fetches the current remote state of a Storyblok space, prints a diff, and applies the changes through the Management API.
url: https://www.storyblok.com/docs/tooling/cli/schema-push
---

# schema push

Loads the schema exported from `<entry-file>`, fetches the current remote state of a Storyblok space, prints a diff, and applies the changes through the Management API. Each successful run saves a changeset file under the configured base path so the push can be reverted later with [`schema rollback`](/docs/tooling/cli/schema-rollback).

The entry file must export a `schema` object of the shape `{ blocks, folders?, datasources?, fieldPlugins? }`, identical to the shape consumed by `defineSchema()` and the `Schema<typeof schema>` type in [`@storyblok/schema`](/docs/libraries/js/schema):

```ts
import { defineSchema } from "@storyblok/schema";
import type { Schema as InferSchema } from "@storyblok/schema";
import { pageBlock, heroBlock } from "./blocks";
import { layoutFolder } from "./folders";
import { colorsDatasource } from "./datasources";

export const schema = defineSchema({
  blocks: { pageBlock, heroBlock },
  folders: { layoutFolder },
  datasources: { colorsDatasource },
});

export type Schema = InferSchema<typeof schema>;
```

## Prerequisites

-   An entry file that exports a `schema` object authored with [`@storyblok/schema`](/docs/libraries/js/schema).

## Breaking changes and migrations

When a push contains breaking changes (field removals, type changes, or renames), the command analyzes them and, unless `--no-migrations` is set, generates scaffold migration files. The command confirms detected renames interactively. The generated migrations are scaffolds: review them before running [`migrations run`](/docs/tooling/cli/migrations-run).

With `--dry-run`, the command prints the analysis but does not write migration files.

## Changesets

Every non-dry-run push writes a changeset file capturing the diff and the pre-push remote state. The changeset is the input consumed by [`schema rollback`](/docs/tooling/cli/schema-rollback).

## Local component files

With `--write-components` (the default), `schema push` writes each component schema to disk after a successful push, even when nothing changed. This keeps a fresh checkout in sync without requiring an extra [`components pull`](/docs/tooling/cli/components-pull) step. Pair the flag with `--delete` to also remove the local files of stale components — those removed from the local schema and deleted from the space by `--delete`.

## Datasources and entries

`schema push` owns datasource definitions: it creates, updates, and (with `--delete`) removes datasources in the space. Use [`datasources push`](/docs/tooling/cli/datasources-push) to sync entries after the datasource definition exists.

## Usage

```bash
storyblok schema push <entry-file> [flags]
```

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| Entry file | string | _Required._ Path to the TypeScript file that exports the `schema` object. |

## Flags

| Flag | Type | Description |
| --- | --- | --- |
| `--space`, `-s` | integer | _Required._ The ID of the Storyblok space to push the schema to. |
| `--path`, `-p` | string | _Optional._ Base path for changeset and migration files. |
| `--dry-run` | boolean | _Optional._ Show diffs without applying changes. |
| `--delete` | boolean | _Optional._ Delete remote entities that are not present in the local schema. Stories using deleted components will end up with out-of-schema content. |
| `--migrations` | boolean | _Optional._ Generate scaffold migration files for breaking changes. Enabled by default. Pass `--no-migrations` to skip. |
| `--write-components` | boolean | _Optional._ Write component schemas as local JSON files after push, and remove the files of components deleted via `--delete`. Enabled by default. Pass `--no-write-components` to skip. |

## Examples

The following examples assume that a `space` has been defined in a configuration file.

```bash
# Push the local schema to a space
storyblok schema push src/schema/schema.ts
# Preview the diff without applying changes
storyblok schema push src/schema/schema.ts --dry-run
# Push and delete remote entities not present locally
storyblok schema push src/schema/schema.ts --delete
```

## Pagination

-   [Previous: schema init](/docs/tooling/cli/schema-init)
-   [Next: schema rollback](/docs/tooling/cli/schema-rollback)