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 the part that lands in a committed file.

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]

The selectable resources are roles, policies, flows, dashboards, settings, folders, users, and translations; access, permissions, operations, and panels ride along with their parents (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 snapshot points at something you omitted (a relation target, a group parent, a many-to-any collection). Pushing that snapshot 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 snapshot (usually a typo) is named in a warning. The partial snapshot still lands, 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 export 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 only rewrites what it fetched. Everything it did not fetch keeps its committed state, untouched.
2. A push only applies what is in the files. Work that never entered them cannot ship.

Refreshed means the file is rewritten from the source; because writes are deterministic, an unchanged resource produces no git diff. Preserved means the file is not touched at all.

Push modes

A mirror push deletes only within what the committed files cover: a snapshot scoped to some collections can delete fields inside those collections, never a collection it doesn't contain. An export the source itself left incomplete (hidden permission rows) 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 data rows absent from the import set; pass --dangerously-allow-delete to consent, or use --mode merge.

Record identity

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

The map is keyed internally by source and target instance URL, so one committed 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 snapshot's Directus version 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 export the source cut short.

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 committed files and the instance disagree: version mismatch, changed target schema, incomplete export), 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 data 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.