> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formae.io/llms.txt
> Use this file to discover all available pages before exploring further.

# formae extract

> Pull existing resources into a forma file. Reference for formae extract and its flags.

Extract resources that formae knows about into a forma file, so you can bring
existing infrastructure under management as code. Select the resources with a
query and give a target file to write.

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
formae extract [flags] <target file>
```

## Examples

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
formae extract --query 'type:AWS::S3::Bucket' ./buckets.pkl
formae extract --query 'type:GCP::Compute::* managed:false' ./gcp-unmanaged.pkl
formae extract --query 'stack:prod target:eu target:us' ./prod.pkl
```

## Flags

| Flag                                | Default  | Description                                                                                                                                                                                                                                                    |
| ----------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--query <query>`                   |          | Find resources by their attributes. `*` works as a wildcard.                                                                                                                                                                                                   |
| `--output-schema <pkl>`             | `pkl`    | Output schema. Only `pkl` is currently supported.                                                                                                                                                                                                              |
| `--schema-location <remote\|local>` | `remote` | How plugin PKL schemas are referenced in the generated PklProject. `remote` emits `package://` URIs fetched from the hub. `local` emits local file imports against the agent's on-disk PklProject paths, and requires the CLI and agent to share a filesystem. |
| `--yes`                             | `false`  | Overwrite existing files without prompting.                                                                                                                                                                                                                    |
| `--config <path>`                   |          | Path to a config file.                                                                                                                                                                                                                                         |
| `--profile <name>`                  |          | Named profile to use.                                                                                                                                                                                                                                          |

## Plugin dependencies

The extracted file needs every plugin whose resources it declares to be a
dependency of the `PklProject` that covers it. When you extract into a directory
that already has a `PklProject`, extract adds any plugin namespace the resources
need but the project is missing and re-resolves the project — silently, as part
of extracting. Only the missing entries are added; your existing dependencies
(including your pinned formae version) are preserved.

If a resource needs a plugin the agent does not report as installed, extract
fails with an actionable message instead of producing a file that can't be
generated:

```text theme={"languages":{"custom":["/languages/pkl.json"]}}
resource type "AZURE::Network::Subnet" requires plugin namespace "azure", but the agent does not report it installed. Install it with `formae plugin install azure` and retry
```

<Note>
  Missing **plugin** dependencies are added automatically, because the extracted
  file cannot be generated without them. The **formae core** schema version is
  handled differently: extract only notifies you (see below) and never rewrites it.
</Note>

## Schema version compatibility

Extracted forma files use `extends "@formae/forma.pkl"` (see
[Properties](/documentation/concepts/properties)), a shape introduced in formae
`0.88.0`. A `PklProject` pinning an older formae cannot evaluate a freshly
extracted file, because the Pkl evaluator fails to resolve the `extends`.

When you extract into a directory already covered by a `PklProject`, formae
checks the formae version it pins:

| Pinned formae version                    | Result                                                    |
| ---------------------------------------- | --------------------------------------------------------- |
| `< 0.88.0`                               | The file is written, then extract prints the notice below |
| `>= 0.88.0`                              | No notice                                                 |
| No `PklProject`, or no formae dependency | No notice                                                 |

The extracted `.pkl` is **always written**. The notice is advisory: extract
never rewrites your `PklProject`, so it introduces no surprise diff into your
working tree.

```text theme={"languages":{"custom":["/languages/pkl.json"]}}
'<dir>/PklProject' is using formae version 0.87.0, however CLI is at version 0.88.0. Please update to 0.88.0 or greater and run 'pkl project resolve', in order to ensure extracted file evaluates.
```

To resolve it, bump the formae dependency in your `PklProject` to `0.88.0` or
greater, then run:

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
pkl project resolve
```

The extracted file then evaluates correctly.