Configuration

Options are merged from the following sources, in order of precedence:

1. CLI arguments
2. Environment variables
3. Configuration file
4. Default values

CLI and environment variables

These options can be used with any command to configure the operation of directus-sync:

• -c, --config-path <configPath>
  Change the path to the config file. Default paths are: ./directus-sync.config.js, ./directus-sync.config.cjs or ./directus-sync.config.json.

• -d, --debug
  Display additional logging information. Useful for debugging or verifying what directus-sync is doing under the hood.

• -u, --directus-url <directusUrl>
  Specify the Directus instance URL. Alternatively, set the DIRECTUS_URL environment variable.

• -t, --directus-token <directusToken>
  Provide the Directus access token. Alternatively, set the DIRECTUS_TOKEN environment variable. If provided, the directus-email and directus-password options are ignored.

• -e, --directus-email <directusEmail>
  Provide the Directus email. Alternatively, set the DIRECTUS_ADMIN_EMAIL environment variable.

• -p, --directus-password <directusPassword>
  Provide the Directus password. Alternatively, set the DIRECTUS_ADMIN_PASSWORD environment variable.

• --dump-path <dumpPath>
  Set the base path for the dump. This must be an absolute path. The default is "./directus-config".

• --seed-path <seedPath>
  Set the base path for the seed data. This must be an absolute path. The default is "./directus-config/seed".

• --collections-path <collectionPath>
  Specify the path for the collections dump, relative to the dump path. The default is "collections".

• -o, --only-collections <onlyCollections>
  Comma-separated list of directus collections to include during pull push or diff process.

• -x, --exclude-collections <excludeCollections>
  Comma-separated list of directus collections to exclude during pull push or diff. Can be used along with only-collections.

• --preserve-ids <preserveIds>
  Comma-separated list of directus collections to preserve the original ids during the pull or push process.
  Possible collections are: dashboards, operations, panels, policies, roles and translations.
  flows and folders ids are always preserved.
  The value can be * or all to preserve ids of all collections, when applicable.

• --max-push-retries <maxPushRetries>
  The number of retries for the push and seed push operations. The default is 20. Use 0 to disable limit.

• --snapshot-path <snapshotPath>
  Specify the path for the schema snapshot dump, relative to the dump path. The default is "snapshot".

• --no-snapshot
  Do not pull and push the Directus schema. By default, the schema is pulled and pushed.

• --no-split
  Indicates whether the schema snapshot should be split into multiple files. By default, snapshots are split.

• --specs-path <specsPath>
  Specify the path for the specifications dump (GraphQL & OpenAPI), relative to the dump path. The default is "specs".

• --no-specs
  Do not dump the specifications (GraphQL & OpenAPI). By default, specifications are dumped.

• -f, --force
  Force the diff of schema, even if the Directus version is different. The default is false.

• -h, --help
  Display help information for the directus-sync commands.

Configuration file

The directus-sync CLI also supports a configuration file. This file is optional. If it is not provided, the CLI will use the default values for the options.

The default paths for the configuration file are ./directus-sync.config.js, ./directus-sync.config.cjs or ./directus-sync.config.json. You can change this path using the --config-path option.

The configuration file can extend another configuration file using the extends property.

This is an example of a configuration file:

// ./directus-sync.config.js
module.exports = {
  extends: ['./directus-sync.config.base.js'],
  debug: true,
  directusUrl: 'https://directus.example.com',
  directusToken: 'my-directus-token',
  directusEmail: 'admin@example.com', // ignored if directusToken is provided
  directusPassword: 'my-directus-password', // ignored if directusToken is provided
  directusConfig: {
    clientOptions: {},  // see https://docs.directus.io/guides/sdk/getting-started.html#polyfilling
    restConfig: {}, // see https://docs.directus.io/packages/@directus/sdk/rest/interfaces/RestConfig.html
  },
  dumpPath: './directus-config',
  seedPath: './directus-config/seed',
  collectionsPath: 'collections',
  onlyCollections: ['roles', 'policies', 'permissions', 'settings'],
  excludeCollections: ['settings'],
  preserveIds: ['roles', 'panels'], // can be '*' or 'all' to preserve all ids, or an array of collections
  maxPushRetries: 20,
  snapshotPath: 'snapshot',
  snapshot: true,
  split: true,
  specsPath: 'specs',
  specs: true,
};

CLI Options

These options are available for all commands:

Options:
  -V, --version                               output the version number
  -d, --debug                                 display more logging (default "false")
  -u, --directus-url <directusUrl>            Directus URL (env: DIRECTUS_URL)
  -t, --directus-token <directusToken>        Directus access token (env: DIRECTUS_TOKEN)
  -e, --directus-email <directusEmail>        Directus user email (env: DIRECTUS_ADMIN_EMAIL)
  -p, --directus-password <directusPassword>  Directus user password (env: DIRECTUS_ADMIN_PASSWORD)
  -c, --config-path <configPath>              the path to the config file. Required for extended options (default paths: ./directus-sync.config.js, ./directus-sync.config.cjs, ./directus-sync.config.json)
  -h, --help                                  display help for command

Commands:
  pull [options]                              get the schema and collections and store them locally
  diff [options]                              describe the schema and collections diff. Does not modify the database.
  push [options]                              push the schema and collections
  seed                                        seed the custom collections with data
  helpers                                     a set of helper utilities
  help [command]                              display help for command