xcaffold status
Show compilation state and check for drift across all providers.
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 reads .xcaffold/project.xcaf.state (the default). With --blueprint <name>, it reads .xcaffold/<name>.xcaf.state.
Usage:
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/). Mutually exclusive with --blueprint. |
--no-color | — | bool | false | Disable ANSI color and UTF-8 glyphs. Also honoured via the NO_COLOR environment variable. |
--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.
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. |
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
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
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, 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:
xcaffold status
Check drift for a specific provider:
xcaffold status --target claude
List all tracked files for a provider, including clean ones:
xcaffold status --target claude --all
List all tracked files across every provider in one command:
xcaffold status --all
Check status for a named blueprint:
xcaffold status --blueprint backend
Disable color output (useful in CI):
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>.