Skip to main content
The 2501 CLI provides commands for managing agents, running assigned tasks, and interacting with your infrastructure. All commands use the @2501 prefix and work from any directory.
The commands below belong to the @2501 agent CLI. Managing platform configuration (agents, hosts, specialties, rules, and more) as version-controlled files uses a separate administrative 2501 CLI with its own resources commands. See Configuration as Code.

​
Command Overview

CommandPurpose
setConfigure CLI settings
configView available configurations
initInitialize a new agent
agentsManage and list agents
tasksFetch, subscribe to, and auto-execute assigned tasks
start-taskRun a specific task by ID

​
set

Configure essential CLI settings, primarily for authentication. 
@2501 set <key> <value>
api_key Set your API key for authentication: 
@2501 set api_key YOUR_API_KEY
Retrieve your API key from accounts.2501.ai. See Authentication for details.

​
config

Fetch and display available agent configurations from the API, including specialties and operational settings. 
@2501 config
Shows available specialties, engine configurations, and organization settings. Use this to verify authentication and explore configurations before initializing agents.

​
init

Initialize a new agent in the current or specified workspace. Agents can execute tasks locally or remotely. 
@2501 init [options]
Options:
OptionDescriptionDefault
--name <name>Agent nameAuto-generated
--workspace <path>Workspace directory pathCurrent directory
--config <configKey>Specialty configuration keySYSOPS
--remote-exec <connection>Enable remote execution (user@host:port)None (local)
--remote-exec-type <type>Remote connection type: ssh or winrmssh
--remote-private-key <privateKey>Path to the SSH private key for authentication~/.ssh/id_rsa
--remote-exec-password <password>Password for remote authenticationNone

​
Local Execution

Initialize an agent for local execution (requires CLI installed on the target machine): 
@2501 init --name dev-agent --config TYPESCRIPT_SPECIALIST

​
Remote Execution

Initialize an agent for remote execution via SSH or WinRM. The agent runs in the 2501 agent swarm and connects to target machines remotely. SSH with Default Key: 
@2501 init --name prod-ops --remote-exec user@server.com:22
Without --remote-private-key, the CLI uses ~/.ssh/id_rsa if it is present. SSH with Custom Private Key: 
@2501 init --remote-exec user@server.com:22 --remote-private-key ./custom-key.pem
SSH with Password: 
@2501 init --remote-exec user@server.com:22 --remote-exec-password yourpassword
Key-based authentication is recommended over passwords. WinRM for Windows: 
@2501 init --remote-exec user@windows-server.com:5985 --remote-exec-type winrm --remote-exec-password yourpassword
WinRM typically uses port 5985 (HTTP) or 5986 (HTTPS). Complete Remote Example: 
@2501 init \
  --name aws-prod-manager \
  --workspace ~/projects/infrastructure \
  --config AWS_SPECIALIST \
  --remote-exec ubuntu@ec2-instance.amazonaws.com:22 \
  --remote-private-key ~/.ssh/aws-prod.pem
When initializing via CLI, the host is automatically registered in your account under the appropriate organization based on your API key’s scope.

​
agents

List and manage agents in the current workspace or across your machine. 
@2501 agents [options]
Options:
OptionDescription
--workspace <path>List agents in specific workspace
--allList all agents on the machine
--flushClear cached agent data
Examples: 
# Current workspace
@2501 agents

# All agents on machine
@2501 agents --all

# Specific workspace
@2501 agents --workspace ~/projects/backend

# Clear cache
@2501 agents --flush
Shows agent names and IDs, associated workspaces, configuration details, and status.

​
tasks

Fetch the tasks assigned to your agents, and optionally execute new ones as they arrive. Tasks are created in Command Center, through gateways, or via the API, and the CLI runs them on the agent’s host. 
@2501 tasks [options]
Options:
OptionDescription
--workspace <path>Use a specific workspace
--subscribeReceive continuous updates every minute
--unsubscribeStop receiving updates
--listenListen for new tasks from the API and execute them automatically
Examples: 
# View current tasks
@2501 tasks

# Listen for and auto-execute new tasks
@2501 tasks --listen

# Subscribe to updates, then stop
@2501 tasks --subscribe
@2501 tasks --unsubscribe
--listen is the unattended mode for CI/CD and fleet automation: the agent picks up tasks created by gateways or the API and runs them as they arrive.

​
start-task

Run a specific task by its ID. Useful for manually triggering or re-running a task created elsewhere. 
@2501 start-task <taskId> [options]
Options:
OptionDescriptionDefault
--workspace <path>Use a specific workspaceCurrent directory
--agent-id <agentId>Run as a specific agentWorkspace agent
--streamStream task output to the terminalEnabled
The agent’s secondary engine analyzes the task and creates an execution plan, the main engine executes it on the target system, and progress streams to the terminal until completion.

​
Best Practices

Workspace Management: Initialize agents in project directories for automatic workspace association. Use --workspace to switch between projects without changing directories. Keep one agent per project for better context isolation. Remote Execution: Prefer key-based auth over passwords. Test SSH/WinRM access manually before initializing agents. Use descriptive names based on target system and role. Check firewall rules to ensure agent swarm can reach remote hosts. Agent Organization: Create specialized agents for different tasks or environments. Use naming conventions like {environment}-{role}-{system} (e.g., prod-deploy-api). List agents regularly and flush cache if experiencing stale data. Task Monitoring: Use --subscribe for active monitoring during deployments. Use --listen for unattended automation. Unsubscribe when done to reduce API calls.

​
Common Workflows

Initial Setup: 
npm install -g @2501-ai/cli
@2501 set api_key YOUR_API_KEY
@2501 config

cd ~/projects/my-app
@2501 init --name my-app-agent --config TYPESCRIPT_SPECIALIST
Remote Agent Setup: 
@2501 init \
  --name prod-monitor \
  --remote-exec ubuntu@prod-server.com:22 \
  --remote-private-key ~/.ssh/prod.pem \
  --config SYSOPS
Running Assigned Tasks: 
# Execute tasks as they are created by gateways or the API
@2501 tasks --listen &

# Or run a single task by ID
@2501 start-task task_abc123

​
Troubleshooting

Command Not Found: Verify CLI is installed with npm list -g @2501-ai/cli. Check PATH includes npm global bin directory. Reinstall if necessary. Authentication Errors: Verify API key with @2501 config. Re-set with @2501 set api_key YOUR_API_KEY. Check key hasn’t expired. See Authentication for detailed troubleshooting. Agent Not Found: List agents with @2501 agents --all. Verify you’re in the correct workspace. Initialize if needed. Clear cache with @2501 agents --flush. Remote Execution Failures: Test manual SSH/WinRM connection. Verify host accessibility (firewall, network). Check credentials. Ensure private key has correct permissions (SSH requires 600). Confirm port numbers (SSH: 22, WinRM: 5985/5986). Task Not Executing: Check agent status with @2501 agents. Verify the workspace has an initialized agent. Review the task in Command Center for detailed errors. Task Subscription Not Working: Verify the agent is initialized. Check API authentication. Ensure the workspace path is correct. Try unsubscribing and resubscribing. For additional support, contact hello@2501.ai.