> ## 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, and a reproducible definition of your configuration. 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 inbound prompt.

| Kind | Subdirectory | Body | Reference |
| - | - | - | - |
| Agent | `agents/` | - | [Agent](/0.16/configure/resources/agents) |
| Host | `hosts/` | Host knowledge | [Host](/0.16/configure/resources/hosts) |
| Specialty | `specialties/` | Specialty prompt | [Specialty](/0.16/configure/resources/specialties) |
| Operational Rule | `operational_rules/` | Rule text | [Operational Rule](/0.16/configure/resources/operational-rules) |
| Credential | `credentials/` | - (secrets via `${ENV}`) | [Credential](/0.16/configure/resources/credentials) |
| Gateway | `gateways/` | Inbound prompt | [Gateway](/0.16/configure/resources/gateways) |
| Blacklist | `blacklist/` | - | [Blacklist](/0.16/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.16/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.16/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.