Reference

Everything on this page is lookup material. If you're learning the tool, start with the Quickstart and How It Works instead.

Commands

The CLI installs as directus-cli with d6s as an equivalent short alias.

Global flags, available on every command:

d6s profile add

d6s profile add [name] [--url <url>] [--token <token>] [--yes]

Adding is an upsert: an existing name is updated. Run without arguments for prompts, which also offer to save a credential (paste a static token, or log in with email and password to save a session; saved sessions refresh themselves before they expire). Profile names use letters, numbers, and underscores. URLs with embedded credentials, query strings, or fragments are refused because the URL is stored in project configuration.

d6s profile test

d6s profile test <name>

Connects and prints who the credential authenticates as:

◇ Authenticated to https://cms.example.com as Admin User (Administrator).

d6s sync pull

d6s sync pull --from <profile> [scope flags]

A bare pull includes every selectable resource except users. This means translations sync by default. Pass --no-translations to exclude them, or --translations to pull only translations.

The selectable resources are roles, policies, flows, dashboards, settings, folders, users, and translations. The CLI automatically includes access, permissions, operations, and panels with their parent resources (see the dependency table). Positive selection (--flows) cannot be combined with --all or with --no- flags. Resource selection never narrows the schema; the two axes are scoped independently.

Two warnings a scoped pull can raise, neither of which widens the scope for you:

• Out-of-scope references. The scoped sync files point at something you omitted (a relation target, a group parent, a many-to-any collection). Pushing those files to a fresh target can fail; add the missing collections to --collections yourself.
• A name the server didn't return. A --collections name absent from the returned Schema (usually a typo) is named in a warning. The partial sync files are still written, but never silently.

d6s sync diff

d6s sync diff --to <profile> [--mode <mode>] [--allow-version-drift]

Applies nothing, and exits 0 whether or not differences exist; automation reads the report's changes field.

d6s sync push

d6s sync push --to <profile> [--mode <mode>] [--yes] [--dangerously-allow-delete] [--allow-version-drift]

directus.config.json

Created and updated by d6s profile add; found by walking up from the current directory, like git finds .git. It never contains credentials, so commit it. The full shape:

{
  "profiles": {
    "staging": { "url": "https://staging.example.com" },
    "production": { "url": "https://cms.example.com" }
  },
  "directory": "directus",
  "projects": {
    "default": {
      "schema": true,
      "collections": ["pages", "posts"],
      "resources": ["flows", "settings"],
      "mode": "merge"
    }
  }
}

Top-level keys:

Per-project keys, all optional. A project is a named slice of the sync with its own subdirectory (<directory>/<project>/); the default project exists without being declared. Flags on the command line override these per run:

"schema": false combined with a collections scope is refused as a contradiction, as is setting both an include and an exclude list for the same axis. Project names use letters, numbers, hyphens, and underscores.

Credentials

When a command authenticates a profile, the token resolves in order:

1. A --token flag, on the two profile commands that accept one. The sync commands take no token flag.
2. The DIRECTUS_<PROFILE>_TOKEN environment variable: the profile name uppercased, so production reads DIRECTUS_PRODUCTION_TOKEN. A .env file next to directus.config.json is loaded automatically without overriding real environment variables.
3. The credential store at ~/.directus/credentials.json, written readable only by you (mode 0600). Never consulted when the CI environment variable is set.

Use an admin credential. The Schema endpoints and the batch import the CLI relies on are admin-only on the server; the CLI does not check privileges up front, so a non-admin token fails with an authentication error or produces an incomplete pull that the completeness checks then flag.

Configuration resources

Resource selection follows a dependency graph: selecting a resource pulls in what it needs (unless --no-deps).

What a pull touches

Two rules govern every pull, scoped or not:

1. A pull writes sync files only for what it fetched. Sync files for anything it did not fetch stay unchanged.
2. A push only applies what is in the sync files. Work that never entered them cannot ship.

Written in this pull means the CLI fetched the current source state and wrote it to the corresponding sync files. Because writes are deterministic, an identical source state produces no git diff. Not written means the pull left those sync files unchanged on disk.

Push modes

A mirror push deletes only within what the sync files cover: a pull scoped to some collections can delete fields inside those collections, never a collection it doesn't contain. A pull the source itself left incomplete (hidden permission records) is refused at mirror push outright.

Deletion gates

Only mirror deletes, and deleting always requires its own explicit consent:

--yes skips the ordinary confirmation prompt, but it never authorizes a deletion; that holds even if a supposedly additive push unexpectedly carries one. A mirror push in CI without --dangerously-allow-delete refuses before changing anything:

✖ Refusing mirror mode in a non-interactive context without --dangerously-allow-delete.
  mirror can delete schema and configuration records absent from the commit-ready files; pass --dangerously-allow-delete to consent, or use --mode merge.

Record identity

Records are matched across instances first by the ID map (<directory>/<project>/id_map.json), then by an identifying field:

The ID map is keyed internally by source and target instance URL, so one file serves any number of targets without conflicts. Commit it whenever a push changes it. An ambiguous match (two candidates) prompts interactively and refuses non-interactively:

✖ Ambiguous target matches:
  directus_roles source "Editor" — sr1 → one of t1, t2
  Run d6s sync push interactively once to choose, then commit the updated ID map.

The version rule

Schema changes require the Directus version recorded in the sync files and the target's version to match exactly, patch release included; the mismatch error names both versions. --allow-version-drift proceeds anyway with a warning; the CLI never translates schema between versions. Projects with "schema": false skip the check entirely, and a target whose version cannot be read is left to the server's own gate rather than refused.

JSON reports

With --json, stdout carries exactly one report per command; warnings still go to stderr so logs keep them while stdout stays parseable. Reports are emitted as a single line; they're formatted here for readability.

d6s sync pull --from staging --json:

{
  "kind": "PullReport",
  "formatVersion": 1,
  "ok": true,
  "source": "https://staging.example.com",
  "profile": "staging",
  "project": "default",
  "schemaSkipped": false,
  "dir": "directus/default/schema",
  "collections": 12,
  "fields": 87,
  "systemFields": 2,
  "relations": 14,
  "files": 13,
  "removed": [],
  "scope": null,
  "data": {
    "resources": ["directus_flows", "directus_roles"],
    "collections": 10,
    "records": 57,
    "files": 10,
    "removed": [],
    "incomplete": []
  }
}

The Schema counters (collections through files) are null when the Schema phase is skipped; scope echoes a --collections/--exclude-collections scope; data.incomplete names resources whose pull the source cut short. The JSON API keeps data as its compatibility field name; it contains the Configuration report.

d6s sync diff --to production --json:

{
  "kind": "DiffReport",
  "formatVersion": 1,
  "ok": true,
  "target": "https://cms.example.com",
  "profile": "production",
  "project": "default",
  "mode": "merge",
  "changes": true,
  "unresolved": 0,
  "schemaSkipped": false,
  "added": 1,
  "modified": 1,
  "deleted": 0,
  "data": {
    "mode": "merge",
    "source": "https://staging.example.com",
    "collections": {
      "directus_flows": {
        "existing": [],
        "new": ["f1"],
        "deleted": [],
        "mapped": {}
      }
    },
    "matched": 1,
    "ambiguous": 0,
    "unmatched": 1,
    "unchanged": 0,
    "incomplete": [],
    "skipped": false
  }
}

changes is true when a push would do anything, including when records are unresolved; added/modified/deleted count Schema items; data.collections is the target server's own per-collection dry-run answer.

d6s sync push --to production --yes --json reports the same shape as a diff, with applied (true when the push changed the target) in place of unresolved, and data.collections reflecting what the import actually did.

Failures put an error report on stdout:

{
  "kind": "ErrorReport",
  "formatVersion": 1,
  "error": {
    "code": "STATE",
    "message": "Version mismatch: the snapshot was pulled from Directus 11.2.0, but the target runs 11.2.5.",
    "hint": "..."
  }
}

The code is one of a small set of failure classes: USAGE (the command line needs fixing: a missing flag or missing consent), CONFIG (directus.config.json missing or invalid), AUTH (the credential was rejected), HTTP (the instance could not be reached or returned an error), STATE (the sync files and the instance disagree: version mismatch, changed target Schema, incomplete pull), or UNKNOWN. Exit codes are 0 for success and 1 for every failure; the code string is the finer-grained signal.

Output conventions

Human-readable status lines go to stderr, prefixed ● (info), ◇ (success), ▲ (warning), or ✖ (error, with its hint indented beneath). Plan lines go to stdout: + marks an addition, ~ a modification, and ✖ DELETE a deletion, with Configuration plans summarized per collection as +N new ~N updated ✖N deleted. --no-color disables coloring; --json replaces stdout output with the report while warnings stay on stderr.