xcaffold registry

Manage the global project registry — list, add, remove, prune, and inspect registered projects.

Manage the global project registry at ~/.xcaffold/registry.xcaf. The registry tracks all xcaffold-managed projects by name, path, targets, and timestamps.

Projects are registered automatically by xcaffold init and xcaffold apply. The registry command provides explicit management: listing, adding, removing, pruning stale entries, and inspecting project metadata.

Usage:

Shell

xcaffold registry [command]

Running xcaffold registry with no subcommand defaults to registry list.

Subcommands

Subcommand	Description
`list`	List all registered projects
`add`	Register a new project by path
`remove`	Unregister a project by name or path
`prune`	Remove entries for deleted directories
`info`	Show detailed metadata for a project

registry list

Display all registered projects in tabular format.

Shell

xcaffold registry list [flags]

Flags

Flag	Short	Type	Default	Description
`--json`	—	`bool`	`false`	Output as a JSON array of project objects.
`--verbose`	`-v`	`bool`	`false`	Include registration timestamp and config directory.

Output Columns

Column	Description
NAME	Project name (from `project.xcaf` or directory basename)
PATH	Absolute path to the project
TARGETS	Compilation targets or count (expanded in verbose mode)
LAST APPLIED	Timestamp of last `xcaffold apply`, or "never"
STATUS	`ok`, `stale` (path missing), or `orphan` (no xcaf files)

Projects are sorted alphabetically by name.

Examples

Shell


xcaffold registry list

xcaffold registry list --json

xcaffold registry list -v

registry add

Explicitly register a project at the given filesystem path.

Shell

xcaffold registry add PATH

Behavior

Resolves PATH to an absolute path.
Verifies the path exists on disk. Returns an error if not.
Reads project.xcaf at the path to detect the project name and targets. Falls back to the directory basename if no project.xcaf is found.
If the path is already registered, updates the existing entry.
If a different project with the same name exists, appends a parent-directory suffix to avoid collision.

Examples

Shell


xcaffold registry add ~/projects/my-app

xcaffold registry add .

registry remove

Remove a project from the registry by name or path. Does not delete any files on disk.

Shell

xcaffold registry remove NAME_OR_PATH

Behavior

Matches by name first, then by absolute path.
Returns an error if no match is found.
Prints a confirmation with the removed project's name and path.

Examples

Shell


xcaffold registry remove my-app

xcaffold registry remove ~/projects/my-app

registry prune

Remove all registry entries whose paths no longer exist on disk.

Shell

xcaffold registry prune [flags]

Flags

Flag	Short	Type	Default	Description
`--dry-run`	—	`bool`	`false`	Show what would be removed without modifying the registry.

Output Format

Pruned: "old-project" (/path/to/deleted) — path does not exist
Pruned 1 of 5 projects.

When nothing needs pruning:

Registry is clean. 0 stale entries found.

Examples

Shell


xcaffold registry prune --dry-run

xcaffold registry prune

registry info

Display detailed metadata and filesystem status for a single registered project.

Shell

xcaffold registry info NAME_OR_PATH [flags]

Flags

Flag	Short	Type	Default	Description
`--json`	—	`bool`	`false`	Output as a JSON object.

Output Fields

Field	Description
Name	Registered project name
Path	Absolute path
Registered	ISO timestamp of initial registration
Last Applied	ISO timestamp of last apply, or "never"
Targets	Compilation targets (comma-separated) or "none"
Config Dir	Relative path to xcaf config within the project
Exists	Whether the path exists on disk
Has xcaf/	Whether an `xcaf/` directory is present
Has project.xcaf	Whether a `project.xcaf` file is present

Examples

Shell


xcaffold registry info my-app

xcaffold registry info my-app --json

xcaffold registry info ~/projects/my-app

Registry File

The registry is stored at ~/.xcaffold/registry.xcaf as a kind: registry YAML document. This file is managed by xcaffold — do not edit it manually unless recovering from corruption.

.xcaf

kind: registry
projects:
  - name: my-app
    path: /Users/dev/projects/my-app
    registered: 2026-05-01T10:00:00Z
    last_applied: 2026-05-20T14:30:00Z
    targets:
      - claude
      - gemini

If the registry file becomes corrupt, xcaffold registry prune or manual editing of ~/.xcaffold/registry.xcaf can restore it.

Global Flags

All subcommands inherit the root-level persistent flags:

Flag	Default	Description
`--config <path>`	`""`	Path to `project.xcaf` (not typically used with registry commands).
`--no-color`	`false`	Disable ANSI color and UTF-8 glyphs.
`--verbose`	`false`	Show fidelity notes and policy warnings.

Notes

The registry is project-agnostic. All subcommands work from any directory, not just inside an xcaffold project.
Auto-registration on init and apply is preserved. Use registry add only for manual registration.
prune is explicit, not automatic. Entries for temporarily unmounted volumes are not silently removed.

Previous← xcaffold help NextModel Resolution →

xcaffold registry

Manage the global project registry — list, add, remove, prune, and inspect registered projects.

Manage the global project registry at ~/.xcaffold/registry.xcaf. The registry tracks all xcaffold-managed projects by name, path, targets, and timestamps.

Usage:

Shell

xcaffold registry [command]

Running xcaffold registry with no subcommand defaults to registry list.

Subcommands

Subcommand	Description
`list`	List all registered projects
`add`	Register a new project by path
`remove`	Unregister a project by name or path
`prune`	Remove entries for deleted directories
`info`	Show detailed metadata for a project

registry list

Display all registered projects in tabular format.

Shell

xcaffold registry list [flags]

Flags

Flag	Short	Type	Default	Description
`--json`	—	`bool`	`false`	Output as a JSON array of project objects.
`--verbose`	`-v`	`bool`	`false`	Include registration timestamp and config directory.

Output Columns

Column	Description
NAME	Project name (from `project.xcaf` or directory basename)
PATH	Absolute path to the project
TARGETS	Compilation targets or count (expanded in verbose mode)
LAST APPLIED	Timestamp of last `xcaffold apply`, or "never"
STATUS	`ok`, `stale` (path missing), or `orphan` (no xcaf files)

Projects are sorted alphabetically by name.

Examples

Shell


xcaffold registry list

xcaffold registry list --json

xcaffold registry list -v

registry add

Explicitly register a project at the given filesystem path.

Shell

xcaffold registry add PATH

Behavior

Resolves PATH to an absolute path.
Verifies the path exists on disk. Returns an error if not.
Reads project.xcaf at the path to detect the project name and targets. Falls back to the directory basename if no project.xcaf is found.
If the path is already registered, updates the existing entry.
If a different project with the same name exists, appends a parent-directory suffix to avoid collision.

Examples

Shell


xcaffold registry add ~/projects/my-app

xcaffold registry add .

registry remove

Remove a project from the registry by name or path. Does not delete any files on disk.

Shell

xcaffold registry remove NAME_OR_PATH

Behavior

Matches by name first, then by absolute path.
Returns an error if no match is found.
Prints a confirmation with the removed project's name and path.

Examples

Shell


xcaffold registry remove my-app

xcaffold registry remove ~/projects/my-app

registry prune

Remove all registry entries whose paths no longer exist on disk.

Shell

xcaffold registry prune [flags]

Flags

Flag	Short	Type	Default	Description
`--dry-run`	—	`bool`	`false`	Show what would be removed without modifying the registry.

Output Format

Pruned: "old-project" (/path/to/deleted) — path does not exist
Pruned 1 of 5 projects.

When nothing needs pruning:

Registry is clean. 0 stale entries found.

Examples

Shell


xcaffold registry prune --dry-run

xcaffold registry prune

registry info

Display detailed metadata and filesystem status for a single registered project.

Shell

xcaffold registry info NAME_OR_PATH [flags]

Flags

Flag	Short	Type	Default	Description
`--json`	—	`bool`	`false`	Output as a JSON object.

Output Fields

Field	Description
Name	Registered project name
Path	Absolute path
Registered	ISO timestamp of initial registration
Last Applied	ISO timestamp of last apply, or "never"
Targets	Compilation targets (comma-separated) or "none"
Config Dir	Relative path to xcaf config within the project
Exists	Whether the path exists on disk
Has xcaf/	Whether an `xcaf/` directory is present
Has project.xcaf	Whether a `project.xcaf` file is present

Examples

Shell


xcaffold registry info my-app

xcaffold registry info my-app --json

xcaffold registry info ~/projects/my-app

Registry File

The registry is stored at ~/.xcaffold/registry.xcaf as a kind: registry YAML document. This file is managed by xcaffold — do not edit it manually unless recovering from corruption.

.xcaf

kind: registry
projects:
  - name: my-app
    path: /Users/dev/projects/my-app
    registered: 2026-05-01T10:00:00Z
    last_applied: 2026-05-20T14:30:00Z
    targets:
      - claude
      - gemini

If the registry file becomes corrupt, xcaffold registry prune or manual editing of ~/.xcaffold/registry.xcaf can restore it.

Global Flags

All subcommands inherit the root-level persistent flags:

Flag	Default	Description
`--config <path>`	`""`	Path to `project.xcaf` (not typically used with registry commands).
`--no-color`	`false`	Disable ANSI color and UTF-8 glyphs.
`--verbose`	`false`	Show fidelity notes and policy warnings.

Notes

The registry is project-agnostic. All subcommands work from any directory, not just inside an xcaffold project.
Auto-registration on init and apply is preserved. Use registry add only for manual registration.
prune is explicit, not automatic. Entries for temporarily unmounted volumes are not silently removed.

Previous← xcaffold help NextModel Resolution →