xcaffold status

Show compilation state and check for drift across all providers.

The status command reads the SHA-256 state file generated by xcaffold apply and compares it against both your source .xcaf files and the compiled provider-native output files on disk.

Without --blueprint, it auto-detects the most recently applied state file by scanning all .xcaf.state files in .xcaffold/ and selecting the one with the latest LastApplied timestamp. This means blueprint-scoped applies are visible without explicitly passing --blueprint. With --blueprint <name>, it reads only .xcaffold/<name>.xcaf.state.

When blueprints were applied with --output-dir, their state files include the output directory in the filename (e.g., [email protected]). Passing --blueprint without --output-dir looks up only the default state file for that blueprint name. Run xcaffold status without --blueprint to auto-detect all state files regardless of output directory.

Usage:

Shell

xcaffold status [flags]

Flags

Flag	Short	Type	Default	Description
`--all`	—	`bool`	`false`	Show all tracked files grouped by subdirectory. Works with or without `--target` (default: drifted files only).
`--blueprint <name>`	—	`string`	`""`	Read state from the named blueprint's state file. Mutually exclusive with `--global`.
`--global`	`-g`	`bool`	`false`	Read from the global config state (`~/.xcaffold/xcaf/global.xcaf`). Mutually exclusive with `--blueprint`.
`--json`	—	`bool`	`false`	Output status as a single JSON object. See JSON output below.
`--no-color`	—	`bool`	`false`	Disable ANSI color and UTF-8 glyphs. Also honoured via the `NO_COLOR` environment variable.
`--output-dir <path>`	—	`string`	`""`	Override output directory for drift detection. When omitted, reads the stored output directory from the state manifest.
`--target <name>`	—	`string`	`""`	Focus drift inspection on a single provider (e.g., `claude`, `cursor`, `gemini`).

Behavior

Overview mode (default)

Running xcaffold status without --target prints a breadcrumb header, a PROVIDER / FILES / STATUS table for every compiled provider, a source-files summary line, and — if any drift is found — a grouped list of drifted files showing the relative artifact path and label.

When no state file exists (i.e., xcaffold apply has never run), the command prints No compilation state found. and exits 0.

Single-provider mode (`--target`)

When --target <name> is given, the command prints the breadcrumb header, a one-line summary (N synced · N modified · N sources unchanged), the drifted file list for that provider, and a source-files line.

If --target names a provider with no recorded state, the command prints the list of known providers and exits 1.

Full file listing (`--all`)

--all appends a GROUP / FILES / STATUS sub-table listing every tracked artifact grouped by subdirectory, with drifted entries flagged inline.

When used with --target, the table appears below that provider's drift summary.

When used without --target (overview mode), a per-provider GROUP table is appended for every compiled provider after the overview table and drift block, giving a single-command view of all files across all providers.

Output directory resolution

When xcaffold apply was run with --output-dir, the state manifest records the output directory per target. xcaffold status reads this stored path automatically — no --output-dir flag is needed for status checks.

Use --output-dir on status to override the stored path (e.g., to check drift at a different location).

Flag constraints

--blueprint and --global cannot be combined.

Output labels

Artifact labels

Label	Meaning
`synced`	All tracked files match the recorded hashes.
`modified`	File exists on disk but its content differs from the recorded hash.
`missing`	File is tracked in the state file but does not exist on disk.

Source labels

Label	Meaning
`source changed`	A `.xcaf` source file changed since the last `apply`. Output is stale.
`source removed`	A `.xcaf` file tracked at last apply no longer exists on disk.
`new source`	A `.xcaf` file exists on disk that was not present at the last apply.

JSON output

xcaffold status --json prints a single JSON object to stdout containing the full project status. This is useful for CI pipelines, scripting, and tool integration.

The output includes:

Field	Type	Description
`project`	`string`	Project name (derived from the directory name).
`blueprint`	`string`	Blueprint name, if `--blueprint` was used. Empty string otherwise.
`providers`	`array`	One entry per compiled provider (filtered by `--target` when set).
`sources`	`object`	Source file summary with `total` and `changed` counts.

Each entry in providers contains:

Field	Type	Description
`name`	`string`	Provider identifier (e.g., `claude`, `cursor`).
`displayLabel`	`string`	Human-readable name (e.g., `Claude Code`).
`status`	`string`	Provider status: `active` or `deprecated`.
`deprecatedBy`	`string`	Replacement provider name, if deprecated. Empty otherwise.
`sunsetDate`	`string`	Planned removal date, if deprecated. Empty otherwise.
`fileCount`	`int`	Total tracked artifact files for this provider.
`driftCount`	`int`	Number of files with detected drift (modified or missing).
`outputDir`	`string`	Output directory where artifacts are written.
`lastApplied`	`string`	Timestamp of the last successful apply.

--json is compatible with --target (filter to a single provider) and --blueprint (read a specific blueprint's state).

When --json is set, all human-readable formatting (tables, color, glyphs) is suppressed. Exit codes remain the same.

Shell


xcaffold status --json

xcaffold status --json --target claude

xcaffold status --json --blueprint backend

xcaffold status --json | jq '.providers[] | select(.driftCount > 0)'

Example output:

JSON

{
  "project": "myproject",
  "blueprint": "",
  "providers": [
    {
      "name": "claude",
      "displayLabel": "Claude Code",
      "status": "active",
      "deprecatedBy": "",
      "sunsetDate": "",
      "fileCount": 90,
      "driftCount": 0,
      "outputDir": ".claude",
      "lastApplied": "2026-06-17T10:30:00Z"
    },
    {
      "name": "cursor",
      "displayLabel": "Cursor",
      "status": "active",
      "deprecatedBy": "",
      "sunsetDate": "",
      "fileCount": 54,
      "driftCount": 1,
      "outputDir": ".cursor",
      "lastApplied": "2026-06-17T10:30:00Z"
    }
  ],
  "sources": {
    "total": 52,
    "changed": 0
  }
}

Exit codes

Code	Meaning
`0`	No drift detected. Also returned when no state file exists.
`1`	Drift detected (artifact modified, missing, or source changed), or `--target` names an unknown provider.

Sample output

Overview — all providers in sync

sandbox  ·  last applied 3 days ago

  PROVIDER       FILES   STATUS
  antigravity       28   ✓ synced  (deprecated)
  antigravity2      32   ✓ synced
  claude            90   ✓ synced
  copilot            1   ✓ synced
  cursor            54   ✓ synced
  gemini            55   ✓ synced

  Sources  52 .xcaf files  ·  no changes since last apply

✓ All providers are in sync.

Overview — drift detected

sandbox  ·  last applied 3 days ago

  PROVIDER       FILES   STATUS
  antigravity       28   ✓ synced  (deprecated)
  antigravity2      32   ✓ synced
  claude            90   ✗ 1 modified
  copilot            1   ✓ synced
  cursor            54   ✓ synced
  gemini            55   ✗ 1 modified

  Sources  52 .xcaf files  ·  no changes since last apply

Drift detected in 2 providers:

  claude
    ✗  missing   CLAUDE.md  (root)

  gemini
    ✗  missing   GEMINI.md  (root)

→ Run 'xcaffold apply' to restore.
  Run 'xcaffold status --target <name>' for details.

Single-provider — in sync

sandbox  ·  claude  ·  applied 3 days ago

  90 synced  ·  52 sources unchanged

  Sources  52 .xcaf files  ·  no changes since last apply

✓ Everything in sync.

Single-provider — drift detected

sandbox  ·  claude  ·  applied 3 days ago

  89 synced  ·  1 modified  ·  52 sources unchanged

  ✗  missing   CLAUDE.md  (root)

  Sources  52 .xcaf files  ·  no changes since last apply

→ Run 'xcaffold apply --target claude' to restore.
  Run 'xcaffold status --target claude --all' to see all files.

Overview with `--all`

sandbox  ·  last applied 3 days ago

  PROVIDER       FILES   STATUS
  claude            90   ✓ synced
  cursor            54   ✓ synced

  Sources  52 .xcaf files  ·  no changes since last apply

  claude

  GROUP             FILES   STATUS
  agent-memory/        29   ✓ synced
  agents/              12   ✓ synced
  hooks/                4   ✓ synced
  rules/               20   ✓ synced
  skills/              22   ✓ synced

  cursor

  GROUP             FILES   STATUS
  rules/               54   ✓ synced

✓ All providers are in sync.

Single-provider with `--all`

sandbox  ·  claude  ·  applied 3 days ago

  89 synced  ·  1 modified  ·  52 sources unchanged

  ✗  missing   CLAUDE.md  (root)

  Sources  52 .xcaf files  ·  no changes since last apply

  GROUP             FILES   STATUS
  (root)                3   ✗ 1 modified
    ✗  missing   CLAUDE.md  (root)
  agent-memory/        29   ✓ synced
  agents/              12   ✓ synced
  hooks/                4   ✓ synced
  rules/               20   ✓ synced
  skills/              22   ✓ synced

→ Run 'xcaffold apply --target claude' to restore.

Unknown provider

✗ No state for provider "nonexistent".

  Known providers:  antigravity, antigravity2, claude, copilot, cursor, gemini

→ Run 'xcaffold apply --target nonexistent' to compile it first.

No state file

myproject  ·  never applied

  --  No compilation state found.

→ Run 'xcaffold apply' to compile all providers.

Examples

Show sync status across all providers:

Shell

xcaffold status

Check drift for a specific provider:

Shell

xcaffold status --target claude

List all tracked files for a provider, including clean ones:

Shell

xcaffold status --target claude --all

List all tracked files across every provider in one command:

Shell

xcaffold status --all

Check status after a blueprint apply (auto-detected):

Shell

xcaffold apply --blueprint backend --target claude -y
xcaffold status

Check status for a specific blueprint by name:

Shell

xcaffold status --blueprint backend

Output status as JSON for scripting:

Shell

xcaffold status --json

Check a specific provider as JSON:

Shell

xcaffold status --json --target claude

Disable color output (useful in CI):

Shell

xcaffold status --no-color

NO_COLOR=1 xcaffold status

Notes

State files are machine-local and gitignored. See State Files and Drift Detection for schema details.
The breadcrumb header format is: <project> · [blueprint: <name> · ][global scope · ][<provider> · ]<last-applied context>.

Previous← xcaffold list NextLifecycle →

xcaffold status

Show compilation state and check for drift across all providers.

The status command reads the SHA-256 state file generated by xcaffold apply and compares it against both your source .xcaf files and the compiled provider-native output files on disk.

Usage:

Shell

xcaffold status [flags]

Flags

Flag	Short	Type	Default	Description
`--all`	—	`bool`	`false`	Show all tracked files grouped by subdirectory. Works with or without `--target` (default: drifted files only).
`--blueprint <name>`	—	`string`	`""`	Read state from the named blueprint's state file. Mutually exclusive with `--global`.
`--global`	`-g`	`bool`	`false`	Read from the global config state (`~/.xcaffold/xcaf/global.xcaf`). Mutually exclusive with `--blueprint`.
`--json`	—	`bool`	`false`	Output status as a single JSON object. See JSON output below.
`--no-color`	—	`bool`	`false`	Disable ANSI color and UTF-8 glyphs. Also honoured via the `NO_COLOR` environment variable.
`--output-dir <path>`	—	`string`	`""`	Override output directory for drift detection. When omitted, reads the stored output directory from the state manifest.
`--target <name>`	—	`string`	`""`	Focus drift inspection on a single provider (e.g., `claude`, `cursor`, `gemini`).

Behavior

Overview mode (default)

When no state file exists (i.e., xcaffold apply has never run), the command prints No compilation state found. and exits 0.

Single-provider mode (`--target`)

If --target names a provider with no recorded state, the command prints the list of known providers and exits 1.

Full file listing (`--all`)

--all appends a GROUP / FILES / STATUS sub-table listing every tracked artifact grouped by subdirectory, with drifted entries flagged inline.

When used with --target, the table appears below that provider's drift summary.

Output directory resolution

Use --output-dir on status to override the stored path (e.g., to check drift at a different location).

Flag constraints

--blueprint and --global cannot be combined.

Output labels

Artifact labels

Label	Meaning
`synced`	All tracked files match the recorded hashes.
`modified`	File exists on disk but its content differs from the recorded hash.
`missing`	File is tracked in the state file but does not exist on disk.

Source labels

Label	Meaning
`source changed`	A `.xcaf` source file changed since the last `apply`. Output is stale.
`source removed`	A `.xcaf` file tracked at last apply no longer exists on disk.
`new source`	A `.xcaf` file exists on disk that was not present at the last apply.

JSON output

xcaffold status --json prints a single JSON object to stdout containing the full project status. This is useful for CI pipelines, scripting, and tool integration.

The output includes:

Field	Type	Description
`project`	`string`	Project name (derived from the directory name).
`blueprint`	`string`	Blueprint name, if `--blueprint` was used. Empty string otherwise.
`providers`	`array`	One entry per compiled provider (filtered by `--target` when set).
`sources`	`object`	Source file summary with `total` and `changed` counts.

Each entry in providers contains:

Field	Type	Description
`name`	`string`	Provider identifier (e.g., `claude`, `cursor`).
`displayLabel`	`string`	Human-readable name (e.g., `Claude Code`).
`status`	`string`	Provider status: `active` or `deprecated`.
`deprecatedBy`	`string`	Replacement provider name, if deprecated. Empty otherwise.
`sunsetDate`	`string`	Planned removal date, if deprecated. Empty otherwise.
`fileCount`	`int`	Total tracked artifact files for this provider.
`driftCount`	`int`	Number of files with detected drift (modified or missing).
`outputDir`	`string`	Output directory where artifacts are written.
`lastApplied`	`string`	Timestamp of the last successful apply.

--json is compatible with --target (filter to a single provider) and --blueprint (read a specific blueprint's state).

When --json is set, all human-readable formatting (tables, color, glyphs) is suppressed. Exit codes remain the same.

Shell


xcaffold status --json

xcaffold status --json --target claude

xcaffold status --json --blueprint backend

xcaffold status --json | jq '.providers[] | select(.driftCount > 0)'

Example output:

JSON

{
  "project": "myproject",
  "blueprint": "",
  "providers": [
    {
      "name": "claude",
      "displayLabel": "Claude Code",
      "status": "active",
      "deprecatedBy": "",
      "sunsetDate": "",
      "fileCount": 90,
      "driftCount": 0,
      "outputDir": ".claude",
      "lastApplied": "2026-06-17T10:30:00Z"
    },
    {
      "name": "cursor",
      "displayLabel": "Cursor",
      "status": "active",
      "deprecatedBy": "",
      "sunsetDate": "",
      "fileCount": 54,
      "driftCount": 1,
      "outputDir": ".cursor",
      "lastApplied": "2026-06-17T10:30:00Z"
    }
  ],
  "sources": {
    "total": 52,
    "changed": 0
  }
}

Exit codes

Code	Meaning
`0`	No drift detected. Also returned when no state file exists.
`1`	Drift detected (artifact modified, missing, or source changed), or `--target` names an unknown provider.

Sample output

Overview — all providers in sync

sandbox  ·  last applied 3 days ago

  PROVIDER       FILES   STATUS
  antigravity       28   ✓ synced  (deprecated)
  antigravity2      32   ✓ synced
  claude            90   ✓ synced
  copilot            1   ✓ synced
  cursor            54   ✓ synced
  gemini            55   ✓ synced

  Sources  52 .xcaf files  ·  no changes since last apply

✓ All providers are in sync.

Overview — drift detected

sandbox  ·  last applied 3 days ago

  PROVIDER       FILES   STATUS
  antigravity       28   ✓ synced  (deprecated)
  antigravity2      32   ✓ synced
  claude            90   ✗ 1 modified
  copilot            1   ✓ synced
  cursor            54   ✓ synced
  gemini            55   ✗ 1 modified

  Sources  52 .xcaf files  ·  no changes since last apply

Drift detected in 2 providers:

  claude
    ✗  missing   CLAUDE.md  (root)

  gemini
    ✗  missing   GEMINI.md  (root)

→ Run 'xcaffold apply' to restore.
  Run 'xcaffold status --target <name>' for details.

Single-provider — in sync

sandbox  ·  claude  ·  applied 3 days ago

  90 synced  ·  52 sources unchanged

  Sources  52 .xcaf files  ·  no changes since last apply

✓ Everything in sync.

Single-provider — drift detected

sandbox  ·  claude  ·  applied 3 days ago

  89 synced  ·  1 modified  ·  52 sources unchanged

  ✗  missing   CLAUDE.md  (root)

  Sources  52 .xcaf files  ·  no changes since last apply

→ Run 'xcaffold apply --target claude' to restore.
  Run 'xcaffold status --target claude --all' to see all files.

Overview with `--all`

sandbox  ·  last applied 3 days ago

  PROVIDER       FILES   STATUS
  claude            90   ✓ synced
  cursor            54   ✓ synced

  Sources  52 .xcaf files  ·  no changes since last apply

  claude

  GROUP             FILES   STATUS
  agent-memory/        29   ✓ synced
  agents/              12   ✓ synced
  hooks/                4   ✓ synced
  rules/               20   ✓ synced
  skills/              22   ✓ synced

  cursor

  GROUP             FILES   STATUS
  rules/               54   ✓ synced

✓ All providers are in sync.

Single-provider with `--all`

sandbox  ·  claude  ·  applied 3 days ago

  89 synced  ·  1 modified  ·  52 sources unchanged

  ✗  missing   CLAUDE.md  (root)

  Sources  52 .xcaf files  ·  no changes since last apply

  GROUP             FILES   STATUS
  (root)                3   ✗ 1 modified
    ✗  missing   CLAUDE.md  (root)
  agent-memory/        29   ✓ synced
  agents/              12   ✓ synced
  hooks/                4   ✓ synced
  rules/               20   ✓ synced
  skills/              22   ✓ synced

→ Run 'xcaffold apply --target claude' to restore.

Unknown provider

✗ No state for provider "nonexistent".

  Known providers:  antigravity, antigravity2, claude, copilot, cursor, gemini

→ Run 'xcaffold apply --target nonexistent' to compile it first.

No state file

myproject  ·  never applied

  --  No compilation state found.

→ Run 'xcaffold apply' to compile all providers.

Examples

Show sync status across all providers:

Shell

xcaffold status

Check drift for a specific provider:

Shell

xcaffold status --target claude

List all tracked files for a provider, including clean ones:

Shell

xcaffold status --target claude --all

List all tracked files across every provider in one command:

Shell

xcaffold status --all

Check status after a blueprint apply (auto-detected):

Shell

xcaffold apply --blueprint backend --target claude -y
xcaffold status

Check status for a specific blueprint by name:

Shell

xcaffold status --blueprint backend

Output status as JSON for scripting:

Shell

xcaffold status --json

Check a specific provider as JSON:

Shell

xcaffold status --json --target claude

Disable color output (useful in CI):

Shell

xcaffold status --no-color

NO_COLOR=1 xcaffold status

Notes

State files are machine-local and gitignored. See State Files and Drift Detection for schema details.
The breadcrumb header format is: <project> · [blueprint: <name> · ][global scope · ][<provider> · ]<last-applied context>.

Previous← xcaffold list NextLifecycle →

xcaffold status

Flags

Behavior

Overview mode (default)

Single-provider mode (--target)

Full file listing (--all)

Output directory resolution

Flag constraints

Output labels

Artifact labels

Source labels

JSON output

Exit codes

Sample output

Overview — all providers in sync

Overview — drift detected

Single-provider — in sync

Single-provider — drift detected

Overview with --all

Single-provider with --all

Unknown provider

No state file

Examples

Notes

xcaffold status

Flags

Behavior

Overview mode (default)

Single-provider mode (--target)

Full file listing (--all)

Output directory resolution

Flag constraints

Output labels

Artifact labels

Source labels

JSON output

Exit codes

Sample output

Overview — all providers in sync

Overview — drift detected

Single-provider — in sync

Single-provider — drift detected

Overview with --all

Single-provider with --all

Unknown provider

No state file

Examples

Notes

Single-provider mode (`--target`)

Full file listing (`--all`)

Overview with `--all`

Single-provider with `--all`

Single-provider mode (`--target`)

Full file listing (`--all`)

Overview with `--all`

Single-provider with `--all`