Skip to main content
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

​
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.

​
Workflow

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:
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:
--prune --force removes resources even when they have dependents. Review the printed plan carefully before approving.

​
Scoping to one organization

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}:
At sync time, the placeholder is resolved from the shell or CI secret store. See Credential for the full credential file format.

​
Tag validation

Host and operational-rule tags are validated against the platform’s tag vocabulary 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.