2501 administrative CLI lets you manage your platform configuration as code. Instead of clicking through the Command Center, you keep a git-tracked directory of MDX files that describes your agents, hosts, specialties, and other resources, then sync that directory to the platform. This gives you reviewable diffs, pull requests, and a reproducible source of truth for your configuration.
There are two separate CLIs. The
@2501 agent CLI (npm i -g @2501-ai/cli) runs tasks and is authenticated with an API key, documented under CLI. The 2501 admin CLI described on this page is a standalone binary that logs in with email and password and manages platform resources. They are different tools with different commands.Authentication
Sign in to your Command Center instance:2501 status to confirm which instance you are pointed at and who you are signed in as.
How it works
Your configuration lives in a directory, with one subdirectory per resource kind and one.mdx file per resource:
| Kind | Subdirectory | Notes |
|---|---|---|
| Agents | agents/ | |
| Hosts | hosts/ | |
| Specialties | specialties/ | |
| Operational rules | operational_rules/ | |
| Credentials | credentials/ | Secret values are never exported |
| Gateways | gateways/ | Update-only from the CLI |
| Blacklist | blacklist/ | Command blacklist patterns |
pull and sync.
Pulling current state
pull exports the platform’s current configuration into your directory:
pull removes the existing .mdx files in each kind folder, so resources you deleted on the platform also disappear from your repo. Commit the result and you have an exact snapshot of the live configuration.
Syncing your changes
sync applies your directory to the platform:
sync diffs the resource against the platform, prints a plan classifying it as create, update, delete, or unchanged, and then applies the changes in dependency-safe order (dependencies exist before the things that need them). Host and operational-rule tags are validated against the platform’s fixed tag vocabulary at plan time. Sync stops on the first failure; resources applied before the failure stay applied, so re-run sync after fixing the problem to continue.
For CI, --dry-run prints the plan without applying and --auto-approve skips the confirmation.
Deletes are opt-in
By default,sync never deletes anything. Resources that exist on the platform but are not declared in your directory are only reported, so you can adopt configuration as code gradually without risking your live setup.
To enable Terraform-style pruning, pass --prune:
--prune, undeclared resources are deleted, but a delete that would orphan dependents is flagged BLOCKED and skipped rather than applied. For example:
- A host is blocked while it has active tasks or attached agents.
- A specialty is blocked while agents or rules still reference it.
--force:
Scoping to one organization
Use--org <nameOrId> to scope a command to a single organization:
pull, only that organization’s resources are exported. On sync, resources in other organizations are ignored, and a file that declares a different organization is rejected. Always pair pull --org with sync --org so the two operations cover the same scope.
Keeping secrets out of git
Credential files can reference environment variables in their value field with the${ENV_VAR} syntax:
sync resolves each placeholder from the environment, so you can commit credential definitions to git while supplying the actual secrets from your CI secret store or local shell. See Credentials for what each credential field means.