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

# Configuration as Code

> Manage platform resources as version-controlled MDX with the 2501 CLI

The `2501` CLI syncs a directory of MDX files with your platform. Reviewable diffs, pull requests, reproducible source of truth. For the per-resource frontmatter schema, see the **Resource Reference** pages below.

## Authentication

```bash theme={null}
2501 login           # email + password, interactive
2501 status          # confirm which instance + user
```

## How it works

Each resource is one MDX file. YAML frontmatter holds the fields; the body (when the kind has one) holds long-form text — the specialty prompt, the rule text, the host knowledge, the gateway's routing prompt.

| Kind             | Subdirectory         | Body                     | Reference                                                      |
| ---------------- | -------------------- | ------------------------ | -------------------------------------------------------------- |
| Agent            | `agents/`            | —                        | [Agent](/0.7/configure/resources/agents)                       |
| Host             | `hosts/`             | Host knowledge           | [Host](/0.7/configure/resources/hosts)                         |
| Specialty        | `specialties/`       | Specialty prompt         | [Specialty](/0.7/configure/resources/specialties)              |
| Operational Rule | `operational_rules/` | Rule text                | [Operational Rule](/0.7/configure/resources/operational-rules) |
| Credential       | `credentials/`       | — (secrets via `${ENV}`) | [Credential](/0.7/configure/resources/credentials)             |
| Gateway          | `gateways/`          | Routing prompt           | [Gateway](/0.7/configure/resources/gateways)                   |
| Blacklist        | `blacklist/`         | —                        | [Blacklist](/0.7/configure/resources/blacklist)                |

## Workflow

```bash theme={null}
# Snapshot the live platform into your repo
2501 resources pull -d ./config

# Apply the repo back to the platform
2501 resources sync -d ./config
```

`pull` is a true mirror — existing `.mdx` files in each kind folder are removed before writing, so deletes on the platform also disappear from your repo. Credential secret values are **never** exported.

`sync` diffs each resource, prints a plan (create / update / delete / unchanged), and applies in dependency-safe order. An agent can reference a host declared in the same directory, even before the host exists on the platform. Sync stops on the first failure; already-applied resources stay applied — re-run to continue.

For CI, `--dry-run` prints the plan without applying and `--auto-approve` skips the y/N prompt.

## Deletes are opt-in

By default, `sync` never deletes. Resources on the platform that aren't in your directory are **reported, not removed**. To prune them, pass `--prune`:

```bash theme={null}
2501 resources sync -d ./config --prune
```

A prune that would orphan dependents is flagged **BLOCKED** and skipped:

* A **host** is blocked while it has active tasks or attached agents.
* A **specialty** is blocked while agents or rules still reference it.
* A **gateway** is blocked while webhooks or tickets still reference it (jobs never block).

To override, add `--force`:

```bash theme={null}
2501 resources sync -d ./config --prune --force
```

<Warning>
  `--prune --force` removes resources even when they have dependents. Review the printed plan carefully before approving.
</Warning>

## Scoping to one organization

```bash theme={null}
2501 resources pull -d ./config --org platform-team
2501 resources sync -d ./config --org platform-team
```

On `pull`, only that org's resources are exported. On `sync`, files declaring a different org are rejected. Always pair `pull --org` with `sync --org` so the two operations cover the same scope.

## Keeping secrets out of git

Credential `value` fields reference environment variables with `${ENV_VAR}`:

```mdx theme={null}
value: ${PROD_DB_PASSWORD}
```

At sync time, the placeholder is resolved from the shell or CI secret store. See [Credential](/0.7/configure/resources/credentials) for the full credential file format.

## Tag validation

Host and operational-rule tags are validated against the platform's [tag vocabulary](/0.7/configure/operational-rules#tag-axes) at plan time. **Only tags introduced by a create or update are checked** — resources already carrying an out-of-vocab tag on the platform round-trip untouched, so adopting Configuration as Code never forces a tag cleanup first.

* `app:<name>` open-namespace tags are accepted on both hosts and rules.
* `procedure:*` tags are valid on operational rules only — never on hosts.