cratis extension restore: fill the extension cache from screenplay.lock
cratis extension restore makes a model compile: it fills the digest-keyed cache the compiler reads with the contract of every
package screenplay.lock pins. It is the command behind PLAY1108 (“the contract is not restored”) and, without --locked,
PLAY1107 (“a reference is not in the lock”). Read Manage extension packages for references, credentials and
trust, and the lock reference for the file itself.
cratis extension restore [--locked] [--root <PATH>] [--source <FOLDER|oci://HOST/PREFIX>]What it does
Section titled “What it does”For every extension line in the model’s systems:
- The lock pins it for the same range. The cache is checked by the pinned digest and contract hash. A hit is reported as
cached. A miss fetches exactly the pinned release: first from theextensionsfolder beside the lock, then from--source, then from the registry. The package must still have the pinned digest and contract hash, and must pass the trust checks. It is then stored in the cache and reported asrestored. A range is never looked at. - The lock does not pin it, or pins it for another range. The reference is resolved to the newest release in its range
(the newest release when the line names no version), checked, stored, and a lock entry is written with the version, digest,
contract hash and publisher. It is reported as
pinned.
The lock is written when entries changed, and only then, and the file keeps its canonical order so a diff shows real changes. Lock entries no model line refers to are left alone. References that fail do not stop the others: every reference gets an outcome, the lock keeps the entries that succeeded, and the exit code reports the failure.
Restoring in CI
Section titled “Restoring in CI”cratis extension restore --locked--locked never resolves a range and never changes screenplay.lock, not even its formatting. A reference the lock does not
pin, or pins for another range, fails with NotLocked (exit 5); a pinned package that has changed fails with Mismatched.
The cache is still filled for pinned references, so the compiler step that follows finds every contract.
Options
Section titled “Options”| Option | Meaning |
|---|---|
--locked |
Fail instead of resolving a reference the lock does not pin; never write the lock. |
--root <PATH> |
The model root. See shared options. |
--source <FOLDER|oci://HOST/PREFIX> |
Fetch from a vendored folder or a private mirror. |
Example
Section titled “Example”$ cratis extension restorepinned cratis/stripe 2.4.0 sha256:5b0c…e1restored npm:@acme/charts 1.2.0 sha256:91af…07Wrote screenplay.lock.$ cratis extension restore --lockedfailed cratis/ledger NotLocked: 'cratis/ledger' is not pinned for version 'latest' in screenplay.lock; run 'cratis extension restore' and commit the lock.Outcomes and exit codes
Section titled “Outcomes and exit codes”Each reference ends as cached, restored, pinned or failed. A failure names its kind (Unresolvable, NotSigned,
SignatureInvalid, Unallowed, Mismatched, NotLocked, Unreachable, Unauthorized) and the exit codes
are shared by every extension command.
Related
Section titled “Related”cratis extension updatemoves a pin to a newer release.cratis extension vendorcopies the locked packages for offline restores.- Extension contracts and the Screenplay tool’s restore.