repo:purge
Permanently remove one pushed, tombstoned node that nothing references from both the hosted repository and local history (irreversible; requires --confirm).
Reference for flywheel repo:purge.
Permanently remove one node from both the local repository and its hosted copy. This two-copy purge is irreversible, and --confirm takes the exact node UUID. A tombstone is the reversible step before it: repo:node:restore undoes a tombstone, but nothing undoes a purge. Purge only acts on a node whose tombstone has been pushed and that no relationship in this repository still references, and tombstoning does not remove those relationships. So first inspect and remove the node's lineage links, containment, semantic edges, tags, and attachments; then tombstone it, commit, push, and run repo:purge <node_id> --confirm <node_id>. A refused purge changes nothing and names the missing step: repository_node_purge_requires_tombstone for a live node, repository_purge_dependency for a tombstoned node that relationships still reference, or repository_purge_unpublished_changes for staged or unpushed changes, listing any blocking relationships and the next commands. If a rerun with the same --idempotency-key finds staged or unpushed changes after the hosted service already accepted that purge (for example after a repository_busy failure), it refuses with repository_purge_already_accepted instead, naming the accepted head, and its next steps commit any staged work and run repo:pull to apply the purge. If a node in another repository continues from this one, that link is removed and the removal is recorded for its owner rather than blocking the purge; the node itself is never copied to them, because purging exists to erase it. If a hosted request fails during the purge (the connection is refused or drops, the request times out, the answer can't be read, or HTTP 408, 429, 502, 503 or 504 is still the answer after the CLI's retries), the error keeps its code and adds step, one of purge_receipt_check (checking whether the service already accepted this purge), purge_request (sending the purge; the service may have accepted it) or follow_up_pull (pulling the accepted purge into this checkout; the service has the purge), and next_action, the same command with the same arguments under the --idempotency-key it ran with. Run it once the hosted service can be reached again: the service recognizes a purge it already accepted by its key, so the rerun does not purge the node twice. A hosted repository_busy answer gets a step and this next_action too, and keeps its code repository_busy; when the follow-up pull stays busy, the message says the hosted service accepted the purge. Other recognized hosted refusals keep their HTTP-kind code (http_error, auth_error, transport_error, timeout, response_error or policy_blocked) and refusal-specific next_action, with no step. For example, HTTP 409 repository_head_mismatch prints http_error; its hosted identifier is in server_response.body.detail (or its type field), not error.code.
Command Group
Local Repository
Summary
Permanently remove one pushed, tombstoned node that nothing references from both the hosted repository and local history (irreversible; requires --confirm).
Usage
flywheel repo:purge <FLAGS> <node_id>Arguments
| Argument | Required | Choices | Description |
|---|---|---|---|
<node_id> | Yes | Node UUID. |
Required flags
| Flag | Value | Default | Choices | Description |
|---|---|---|---|---|
--confirm | string | Exact node UUID confirmation. |
Optional flags
| Flag | Value | Default | Choices | Description |
|---|---|---|---|---|
--repo | string | Local repository filesystem path. | ||
--personal | Use the configured personal repository. | |||
--format | FORMAT | json, tsv, csv, table | Output format for command results. | |
--env | PROFILE | Use a configured CLI profile for this invocation. | ||
--out | PATH | Write output to a file path, or use - for stdout. | ||
--open | Open browser-bound URLs when supported. | |||
--no-retry | Disable transient-error retries. | |||
--retry-max | N | Maximum transient-error retry attempts. | ||
--wait | Block on async operations until a terminal state is reached. | |||
--wait-timeout | SECONDS | 600 | Seconds to wait for --wait before timing out. Defaults to 600. | |
--allow-self | Allow mutating the currently active credential. | |||
--timeout | SECONDS | Set the per-request timeout budget in seconds. | ||
--idempotency-key | KEY | Reuse an Idempotency-Key so ambiguous write failures can be retried with the same key. | ||
--force | Force safety-gated operations where supported. | |||
--yes | Skip confirmation prompts for destructive operations. | |||
--debug | Print structured request debugging with secrets masked. | |||
--verbose | Print verbose progress for long-running operations. | |||
-h, --help | Show this help. |
Examples
First remove the relationships that reference the node (a refused purge lists them), then tombstone it, commit and push the tombstone, and purge. Until the purge, repo:node:restore undoes the tombstone; the purge cannot be undone.
flywheel repo:node:tombstone <node_id> --repo <path> && flywheel repo:commit --repo <path> && flywheel repo:push --repo <path> && flywheel repo:purge <node_id> --confirm <node_id> --repo <path>