The 2501 CLI provides commands for managing agents, executing tasks, and interacting with your infrastructure. All commands use the @2501 prefix and work from any directory.

​
Command Overview

CommandPurpose
setConfigure CLI settings
configView available configurations
initInitialize a new agent
agentsManage and list agents
queryExecute tasks with agents
jobsMonitor and manage jobs

​
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 <key>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
SSH with Custom Private Key: 
@2501 init --remote-exec user@server.com:22 --remote-private-key "$(cat ./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 "$(cat ~/.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.

​
query

Execute tasks by sending natural language instructions to agents. This is the primary command for assigning work. 
@2501 <query> [options]
or 
@2501 query <query> [options]
Options:
OptionDescriptionDefault
--workspace <path>Execute in specific workspaceCurrent directory
--agentId <id>Target specific agent by IDWorkspace agent
Examples: 
# Basic usage
@2501 check disk space on all servers
@2501 implement authentication in my express app
@2501 analyze recent errors in application logs

# Explicit query command
@2501 query "deploy latest version to staging" --workspace ~/projects/api

# Target specific agent
@2501 "restart nginx service" --agentId agent_abc123

# File operations
@2501 find all TypeScript files with unused imports

# System administration
@2501 check if nginx is running and restart if needed

# Development tasks
@2501 add error handling to the user authentication function

# Infrastructure
@2501 verify all containers are healthy and report any issues

# Debugging
@2501 investigate why the API is responding slowly
How it works: The query is sent to the specified agent. The secondary engine analyzes the task and creates an execution plan. The main engine executes on the target system. Real-time progress displays in the terminal with results shown upon completion. Tips: Be specific about what you want. Include relevant context like file paths or service names. Reference previous tasks when following up. Use natural language—the agent understands intent.

​
jobs

Monitor and manage jobs—coordinated multi-task operations created by gateways or manual orchestration. 
@2501 jobs [options]
Options:
OptionDescription
--workspace <path>Monitor jobs for specific workspace
--subscribeReceive continuous updates every minute
--unsubscribeStop receiving updates
--listenListen for and auto-execute new jobs from API
Examples: 
# View current jobs
@2501 jobs

# Monitor specific workspace
@2501 jobs --workspace ~/projects/infrastructure

# Subscribe to updates
@2501 jobs --subscribe

# Stop subscription
@2501 jobs --unsubscribe

# Auto-execute jobs
@2501 jobs --listen
Shows job ID and status, associated tasks and their states, progress information, and completion or failure details. Use for monitoring gateway-generated jobs, tracking multi-agent workflows, automating job execution in CI/CD pipelines, and observing fleet operations.

​
Best Practices

Query Construction: Be specific—“Restart nginx and verify it’s serving traffic” beats “fix nginx”. Include context like file paths and service names. Write queries as you would ask a colleague. Reference previous tasks when following up. 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. Job Monitoring: Use --subscribe for active monitoring during deployments. Use --listen for unattended automation. Check jobs regularly to track gateway-initiated workflows. 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
Development: 
cd ~/projects/backend

@2501 add input validation to the user registration endpoint
@2501 write unit tests for the new validation logic
@2501 check for any TypeScript errors in the codebase
Production Operations: 
@2501 init \
  --name prod-monitor \
  --remote-exec ubuntu@prod-server.com:22 \
  --remote-private-key "$(cat ~/.ssh/prod.pem)" \
  --config SYSOPS

@2501 check disk usage and alert if above 80%
@2501 verify all services are running correctly
@2501 analyze recent application errors
CI/CD Integration: 
@2501 jobs --listen &
# Agent automatically processes jobs from gateway integrations

​
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). Query Not Executing: Check agent status with @2501 agents. Verify workspace has an initialized agent. Try with explicit agent ID. Review task in Accounts for detailed errors. Job Subscription Not Working: Verify agent is initialized. Check API authentication. Ensure workspace path is correct. Try unsubscribing and resubscribing. For additional support, visit our Discord community or contact hello@2501.ai.

​
Next Steps

  • Learn about Agents configuration and management
  • Explore Tasks for execution details
  • Review Specialties for domain-specific configurations
  • Set up Gateways for automated task creation