canic-cli
Operator CLI for Canic backup and restore workflows.
The initial command focuses on snapshot capture/download planning and execution for a canister plus its registry-discovered children.
Use --recursive instead of --include-children to include all descendants.
Use --registry-json <file> to plan from a saved canic_subnet_registry
response instead of querying a live root. Non-dry-run captures recompute the
selection topology immediately before snapshot creation and fail if the hash
changed since discovery.
DFX only creates snapshots for stopped canisters. Pass
--stop-before-snapshot --resume-after-snapshot when the CLI should perform
that local lifecycle step around each captured artifact.
Successful non-dry-run captures write the canonical backup layout: manifest,
download journal, and durable artifact directories. Generated manifests include
each durable artifact checksum so verification can detect manifest/journal
drift before restore planning. Download journals also include
operation_metrics counters for target count, snapshot create, snapshot
download, checksum verification, and artifact finalization progress.
Validate a captured manifest before restore planning:
The validation summary includes topology hash inputs, consistency mode, backup unit counts, kind counts, and per-unit topology validation metadata.
Inspect resumable journal status:
--require-complete still writes the JSON status report, then exits with an
error when any artifact has resume work remaining.
Inspect manifest and journal agreement without reading artifact bytes:
--require-ready still writes the JSON inspection report, then exits with an
error when manifest and journal metadata, including topology receipts, are not
ready for full verification.
Emit a provenance report for audit/review workflows:
The report records source/tool metadata, topology receipts, declared backup
units, and each member's snapshot/code/artifact provenance without reading
artifact bytes. --require-consistent still writes the JSON report, then exits
with an error when manifest and journal backup IDs or topology receipts drift.
Verify the backup layout and durable artifact checksums:
Run the standard no-mutation preflight bundle:
Preflight writes manifest-validation.json, backup-status.json,
backup-inspection.json, backup-provenance.json, backup-integrity.json,
restore-plan.json, restore-status.json, and preflight-summary.json.
The summary records the backup ID, source root, environment, topology hash,
readiness statuses, provenance consistency status, topology mismatch count,
journal operation metrics, member counts, restore identity/snapshot/
verification/operation/ordering counts, snapshot provenance readiness booleans,
verification readiness booleans, restore_mapping_supplied,
restore_all_sources_mapped, restore_ready, stable
restore_readiness_reasons, and paths to the generated reports.
--require-restore-ready still writes the full report bundle, then exits with
an error when restore_ready is false.
Restore planning is manifest-driven and performs no mutations:
--require-verified runs the same manifest, journal, durable artifact, and
checksum checks as canic backup verify before emitting the plan.
--require-restore-ready still writes the restore plan, then exits with an
error when readiness_summary.ready is false.
Restore plans include an identity_summary with explicit mapping mode,
all-sources-mapped status, and fixed, relocatable, mapped, in-place, and
remapped member counts. They also include a snapshot_summary with module
hash, wasm hash, code version, and checksum coverage counts and readiness
booleans, plus a verification_summary with post-restore check counts,
verification_required, and all_members_have_checks. A readiness_summary
collapses those signals into a single ready flag and stable reason strings.
Plans also include an operation_summary with planned snapshot loads, code
reinstalls, verification checks, and phases, plus an ordering_summary and
per-member ordering dependency metadata so dry-runs show when parent
relationships are satisfied inside the same restore group or by an earlier
group.
Emit the initial restore execution status from a plan:
Restore status is no-mutation. It copies the plan identity, readiness,
verification, phase, and operation counts, then marks each planned member as
planned with its source/target canister, snapshot ID, and artifact path.
Render the restore execution operations without mutating targets:
Apply dry-run output expands the restore phases into ordered upload, load,
reinstall, and member verification operations. When --backup-dir is supplied,
the dry-run also verifies that referenced artifact paths stay under that backup
directory, exist on disk, and match their expected SHA-256 checksums when the
plan includes checksums. When --journal-out is supplied, the command also
writes an initial apply journal with each operation marked ready or blocked
and stable blocking reasons. The command requires --dry-run; real restore
execution is intentionally not enabled yet.
Summarize a restore apply journal:
Use --require-ready when scripts should stop if the journal still has blocked
restore operations. Use --require-no-pending when scripts should stop if a
restore operation is already claimed and needs inspection or apply-unclaim.
Use --require-no-failed when failed operations should stop the runner before
completion checks. Use --require-complete when scripts should fail until every
apply operation is completed.
Write an operator-focused restore apply report:
Apply reports include one high-level outcome, attention-required status,
operation counts, blocked reasons, the next transitionable operation, and the
pending, failed, and blocked operation rows that need review. Use
--require-no-attention when CI should fail after writing the report if the
journal has pending, failed, or blocked work.
Emit the full next transitionable operation for an external runner:
Preview the dfx command for the next transitionable operation without
executing it:
Use --dfx <path> when the runner should preview a non-default dfx binary.
Use --require-command when scripts should fail after writing the preview if no
executable operation is available.
Claim the next operation before executing it in an external runner:
Claiming marks the next ready operation pending. Pending operations remain the
next transitionable operation until apply-mark records them as completed or
failed, which lets interrupted runners resume from the same journal. Use
--sequence <n> to fail if the next transitionable operation no longer matches
the operation the runner previewed. Use --updated-at <text> to record a
runner-provided state marker; when omitted, the CLI writes unknown.
Release the current pending operation back to ready when a runner stopped before executing it:
Use --sequence <n> with apply-unclaim when recovery scripts should only
release the pending operation they inspected.
Mark one journal operation after an external restore step completes or fails:
Use --state failed --reason <text> to record a failed operation. The command
validates the input journal, refuses to skip earlier ready operations, refreshes
operation counts, and writes the updated journal without executing any restore
mutation. Use --require-pending when runners should only mark operations that
were claimed first.
Example external restore runner loop:
journal=restore-apply-journal.json
network=local
while ; do
if ; then
break
fi
sequence=""
command=""
updated_at=""
done
If the runner stops after claiming work but before executing the previewed
command, inspect restore-apply-status.json and use apply-unclaim --sequence <n> to release the pending operation back to ready.