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

# bt observability

> Export and apply portable JSON configuration for facets and Loop automations.

export const feature_0 = "Observability templates"

export const verb_0 = "are"

`bt observability template pull` exports a project's facets and Loop automations into a portable JSON template. `bt observability template push` applies a template to a project. Use these commands to store and reuse active observability configuration.

<Warning>
  {feature_0} {verb_0} in [public preview](/docs/feature-lifecycle) and can change before reaching general availability.
</Warning>

All `bt observability` subcommands accept the shared [`bt` global flags](/docs/reference/cli/overview#global-flags).

## bt observability template pull

Pull facets and Loop automations from a project:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt observability template pull --output observability-template.json
```

In an interactive terminal, `bt` lets you select the facets and Loop automations to include. It preselects facets connected to a Topics automation and Loop automations that are not paused. With `--no-input` or `--json`, the template includes only those resources.

Without `--output`, the command writes the template to stdout. Use `--output -` to request stdout explicitly. If the output file already exists, pass `--force` to replace it.

### Pull flags

| Flag                           | Env var                                 | Description                                                        |
| ------------------------------ | --------------------------------------- | ------------------------------------------------------------------ |
| `--output <PATH>`, `-O <PATH>` | `BT_OBSERVABILITY_TEMPLATE_PULL_OUTPUT` | Write the template to a file instead of stdout. Use `-` for stdout |
| `--force`                      | `BT_OBSERVABILITY_TEMPLATE_PULL_FORCE`  | Replace an existing output file                                    |

## bt observability template push

Push a template to a project from a local file, a public URL, or stdin:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt observability template push observability-template.json --project target-project
bt observability template push https://example.com/observability-template.json --project target-project
bt observability template pull | bt observability template push - --project target-project
```

In an interactive terminal, `bt` displays the number of facets and Loop automations in the template and asks for confirmation before making changes. Pass `--yes` to skip the prompt.

If a facet, preprocessor, topic map, or Loop automation conflicts with a matching resource in the destination project, the command stops unless you pass `--force` to replace it.

When applying the template, `bt` handles related configuration as follows:

* **Facets:** The template preserves each facet's relationship with its Topics automation. By default, `bt` uses the Topics automation named by the template, creating one if needed. If a facet does not name an automation, `bt` uses the destination project's only Topics automation. The command stops when it cannot infer one because the project has zero or multiple Topics automations. Pass `--topics-automation <NAME_OR_ID>` to connect every imported facet to one existing Topics automation instead.
* **Loop automations:** Destination settings such as Slack channels and webhooks are not included in the template. When replacing an existing Loop automation, `bt` preserves its destination settings. A new Loop automation has no destinations until you configure them in the target project.

### Push flags

| Flag                               | Env var                                            | Description                                                                                 |
| ---------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `--file <SOURCE>`, `-f <SOURCE>`   | `BT_OBSERVABILITY_TEMPLATE_PUSH_FILE`              | Read from a local path, public URL, or `-` for stdin instead of using the positional source |
| `--topics-automation <NAME_OR_ID>` | `BT_OBSERVABILITY_TEMPLATE_PUSH_TOPICS_AUTOMATION` | Connect every imported facet to an existing Topics automation                               |
| `--force`                          | `BT_OBSERVABILITY_TEMPLATE_PUSH_FORCE`             | Replace matching resources                                                                  |
| `--yes`, `-y`                      | `BT_OBSERVABILITY_TEMPLATE_PUSH_YES`               | Skip the confirmation prompt                                                                |

## Template format

An observability template is a JSON object with a schema version, facets, and Loop automations:

```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "kind": "active_observability_template",
  "schema_version": 1,
  "facets": [],
  "automations": []
}
```

Facet entries include their definitions and any bundled preprocessors. Automation entries contain Loop configuration without destination settings. `bt observability template push` validates the template before planning changes to the target project.

## Next steps

* Learn how [facets and Topics](/docs/observe/topics) classify and group traces.
* Configure [Loop automations](/docs/loop/automations).