Skip to main content

Synchronization

Basic Workflow​

Pull​

npx directus-sync pull

Retrieves the current schema and collections from Directus and stores them locally. This command does not modify the database.

It also retrieves the specifications (GraphQL & OpenAPI) and stores them locally. It gets specifications from the /server/specs/* endpoints:

Available Options

Options:
  --dump-path <dumpPath>                          the base path for the dump (default "./directus-config")
  --collections-path <collectionPath>             the path for the collections dump, relative to the dump path (default "collections")
  -x, --exclude-collections <excludeCollections>  comma separated list of collections to exclude from the process (default to none)
  -o, --only-collections <onlyCollections>        comma separated list of collections to include in the process (default to all)
  --preserve-ids <preserveIds>                    comma separated list of collections that preserve their original ids (default to none). Use "*" or "all" to preserve all ids, if applicable.
  --snapshot-path <snapshotPath>                  the path for the schema snapshot dump, relative to the dump path (default "snapshot")
  --no-snapshot                                   should pull and push the Directus schema (default "true")
  --no-split                                      should split the schema snapshot into multiple files (default "true")
  --specs-path <specsPath>                        the path for the specifications dump (GraphQL & OpenAPI), relative to the dump path (default "specs")
  --no-specs                                      should dump the GraphQL & OpenAPI specifications (default "true")
  -h, --help                                      display help for command

Diff​

npx directus-sync diff

Analyzes and describes the difference (diff) between your local schema and collections and the state of the Directus instance. This command is non-destructive and does not apply any changes to the database.

Available Options

Options:
  --dump-path <dumpPath>                          the base path for the dump (default "./directus-config")
  --collections-path <collectionPath>             the path for the collections dump, relative to the dump path (default "collections")
  -x, --exclude-collections <excludeCollections>  comma separated list of collections to exclude from the process (default to none)
  -o, --only-collections <onlyCollections>        comma separated list of collections to include in the process (default to all)
  --snapshot-path <snapshotPath>                  the path for the schema snapshot dump, relative to the dump path (default "snapshot")
  --no-snapshot                                   should pull and push the Directus schema (default "true")
  --no-split                                      should split the schema snapshot into multiple files (default "true")
  -f, --force                                     force the diff of schema, even if the Directus version is different (default "false")
  -h, --help                                      display help for command

Push​

npx directus-sync push

Applies the changes from your local environment to the Directus instance. This command pushes your local schema and collection configurations to Directus, updating the instance to reflect your local state.

Available Options

Options:
  --dump-path <dumpPath>                          the base path for the dump (default "./directus-config")
  --collections-path <collectionPath>             the path for the collections dump, relative to the dump path (default "collections")
  -x, --exclude-collections <excludeCollections>  comma separated list of collections to exclude from the process (default to none)
  -o, --only-collections <onlyCollections>        comma separated list of collections to include in the process (default to all)
  --preserve-ids <preserveIds>                    comma separated list of collections that preserve their original ids (default to none). Use "*" or "all" to preserve all ids, if applicable.
  --snapshot-path <snapshotPath>                  the path for the schema snapshot dump, relative to the dump path (default "snapshot")
  --no-snapshot                                   should pull and push the Directus schema (default "true")
  --no-split                                      should split the schema snapshot into multiple files (default "true")
  -f, --force                                     force the diff of schema, even if the Directus version is different (default "false")
  --max-push-retries <maxPushRetries>             the number of retries for the push operation (default "20")
  -h, --help                                      display help for command

Common Options​

Collection Management​

Include/Exclude Collections​

Include only specific collections

npx directus-sync pull --only-collections roles,permissions

Exclude specific collections

npx directus-sync pull --exclude-collections settings

ID Preservation​

Preserve IDs for specific collections

npx directus-sync pull --preserve-ids roles,panels

Preserve all possible IDs

npx directus-sync pull --preserve-ids all

Schema Options​

Skip schema operations

npx directus-sync pull --no-snapshot

Keep schema in single file

npx directus-sync pull --no-split

Skip API specs

npx directus-sync pull --no-specs

Advanced Usage​

Force diff even with version mismatch

npx directus-sync diff --force

Retry Configuration​

Set maximum push retries. Retries occur when a dependency between collections could not be resolved.

npx directus-sync push --max-push-retries 30

Environment Variables​

Instead of command-line options, you can use environment variables for authentication:

DIRECTUS_URL=https://directus.example.com
DIRECTUS_TOKEN=your-token

OR

DIRECTUS_ADMIN_EMAIL=admin@example.com
DIRECTUS_ADMIN_PASSWORD=your-password
tip

You can check the configuration options for more information.