---
title: Use an extension in a Screenplay model
editUrl: https://github.com/Cratis/Screenplay/edit/main/Documentation/screenplay/using-an-extension.md
description: 'Add an extension package to a Screenplay model: reference it from a system, restore the lock, configure settings, invoke abilities and place components.'
lastUpdated: 2026-11-14T00:00:00.000Z
---

This guide adds an extension package to a model, uses what it provides and keeps it current. For what the pieces are, read the [extensions overview](/screenplay/extensions/) first.

The examples use a payment package. Replace the name with the package you use.

## 1. Add a system that references the package

A `system` names the business system. Its `extension` line names the package:

```screenplay
secret StripeSecretKey
  description "The key the payment provider issues"

system Payments
  description "The card payment provider"
  extension "cratis/stripe" version 2
  setting secretKey from secret StripeSecretKey
  setting statementDescriptor = "Acme Shop"
  activation on demand idle after 10 minutes
```

- With no `version`, the reference means the latest release. `version 2` means the latest 2.x, `version 2.3.1` exactly that release. All forms are listed in [Referencing a package](/screenplay/extension-contracts/#referencing-a-package).
- A system that names an extension declares no abilities of its own. Declaring one is `PLAY1106`.
- The reference is a catalog short name (`"cratis/stripe"`), a full OCI reference (`"ghcr.io/acme/extension-ledger"`) or an `npm:` package for a frontend-only package.

## 2. Restore it

The compiler never fetches a package. It reads each contract from `screenplay.lock` and a digest-keyed cache, so pin and restore first:

```bash
cratis extension restore
```

A reference the lock does not have yet is resolved to the newest release in its range, checked, stored in the cache and written to `screenplay.lock`. Commit the lock. Until you restore, the compiler reports `PLAY1107` (not in the lock) or `PLAY1108` (not restored). The language server and MCP server only warn and restore for you when `SCREENPLAY_EXTENSION_SOURCE` names a package source.

In CI, use `cratis extension restore --locked`. It never changes the lock and fails for a reference the lock does not pin or pins for another range. For a model folder without network access, `screenplay restore` reads packages from a directory; see [Restore extensions](/screenplay/tool/#restore-extensions). The CLI reference is [`cratis extension restore`](https://github.com/Cratis/cli/blob/main/Documentation/reference/extension-restore.md).

Naming a package is not trusting it. Restore refuses a package whose publisher is not on the allow-list in `.cratis/extensions.json`; in an interactive terminal it asks once. The rules are in the CLI's [trust section](https://github.com/Cratis/cli/blob/main/Documentation/reference/extension.md#trust).

## 3. Configure settings and secrets

Each setting the contract declares is mapped in the model to a literal (for settings that are not secret) or to a named secret. A setting the model does not mention is read from configuration under `systems.<System>.<setting>`. The model never holds a secret's value. See [System settings and named secrets](/screenplay/environments/#system-settings-and-named-secrets).

Give the values to the environment, then list what is missing:

```bash
cratis config --requires ./model
cratis config set secrets.StripeSecretKey
```

`cratis config set` reads the secret from standard input or a prompt. The CLI documents environments in [Environments](https://github.com/Cratis/cli/blob/main/Documentation/environments/index.md#extension-settings-and-secrets).

## 4. Invoke abilities

The abilities of the package are now abilities of `Payments`. Invoke one from a reaction, a workflow action or a state's `entering` line, and handle each way it can end:

```play
reaction TakePayment
  runs as system
  when OrderPlaced
    orderId
    total
    invokes Payments.CreatePaymentIntent
      amount = total
      orderId = orderId
      on returned
        produces PaymentRequested
          clientSecret = $result.clientSecret
      on failed
        produces PaymentFailed
          reason = $failure.reason
```

Every input the ability declares is mapped once, and `on <Outcome>` handles an outcome the contract declares. The rules and diagnostics are in [Invoke an ability](/screenplay/systems/#invoke-an-ability). The effect class of the ability decides retries: a `once` ability is never retried after an attempt that may have reached the provider. See [Choose the effect class](/screenplay/systems/#choose-the-effect-class).

A contract can also declare triggers. They become triggers of the system, so a reaction can start with `when Payments.PaymentSucceeded`.

## 5. Place components on screens

A screen places a component by naming the system and the component, never the package, and handles the signals the contract says it raises:

```play
component Payments.PaymentForm payment
  property amount = "10"
  on succeeded
    execute ConfirmPayment
      with paymentIntentId from signal.paymentIntentId
  on failed
    notify warning "The payment failed"
```

The component, its properties, the signals handled with `on` and the values read as `signal.<value>` are checked against the contract. See [Extension components](/screenplay/screens/#extension-components).

## 6. Specify it

A reaction specification scripts what an ability answers while the reaction runs, so nothing external is called. The lines are `given <System>.<Ability>` followed by `returns`, `answers <Outcome>` or `fails "<reason>"`:

```play
given Carrier.BookPickup returns
  trackingNumber = "TRK-1"
given Carrier.BookPickup answers NoCapacity
given Carrier.BookPickup fails "carrier unavailable"
```

Each line is checked against the system's declared ability, outcomes and returned fields (`PLAY1017`). `then invokes <System>.<Ability>` asserts the call. See [Ability answers](/screenplay/specifications/#ability-answers).

## 7. Run it

```bash
cratis run ./model -e development
```

Before Docker starts, `cratis run` checks that every `extension` line is pinned in the lock, that the publisher is allowed, that the contracts are in the cache and that the environment holds every setting and secret. Nothing starts when one is refused. Stage then fetches each package itself from the lock, verifies it again, and starts each backend in its tier when it is first needed. See [`cratis run`](https://github.com/Cratis/cli/blob/main/Documentation/reference/run.md#extensions) and Stage's [Extension packages](https://github.com/Cratis/Stage/blob/main/Documentation/extensions/packages.md).

## 8. Update it later

```bash
cratis extension update --dry-run
cratis extension update
```

`update` moves each reference to the newest release in its range and shows how the contract changes: what it adds, what it no longer offers and every use in your model that the new contract does not offer. When a use would break, the lock is left alone unless you pass `--allow-incompatible`. To update one extension, name its system: `cratis extension update Payments`. See [`cratis extension update`](https://github.com/Cratis/cli/blob/main/Documentation/reference/extension-update.md) and [Provider compatibility](/screenplay/extension-contracts/#provider-compatibility).

To work offline or from a private mirror, copy the locked packages with [`cratis extension vendor`](https://github.com/Cratis/cli/blob/main/Documentation/reference/extension-vendor.md); the vendored `extensions` folder beside the lock is read before the user cache.

## Next

- [Building an extension](/screenplay/building-an-extension/) creates a package of your own.
- [Systems and abilities](/screenplay/systems/) and [Extension contracts](/screenplay/extension-contracts/) are the references.
