Commands - 2501.ai

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

Command	Purpose
set	Configure CLI settings
config	View available configurations
init	Initialize a new agent
agents	Manage and list agents
query	Execute tasks with agents
jobs	Monitor 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:

Option	Description	Default
`--name <name>`	Agent name	Auto-generated
`--workspace <path>`	Workspace directory path	Current directory
`--config <configKey>`	Specialty configuration key	`SYSOPS`
`--remote-exec <connection>`	Enable remote execution (user@host:port)	None (local)
`--remote-exec-type <type>`	Remote connection type: `ssh` or `winrm`	`ssh`
`--remote-private-key <key>`	SSH private key for authentication	`~/.ssh/id_rsa`
`--remote-exec-password <password>`	Password for remote authentication	None

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:

Option	Description
`--workspace <path>`	List agents in specific workspace
`--all`	List all agents on the machine
`--flush`	Clear 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]

@2501 query <query> [options]

Options:

Option	Description	Default
`--workspace <path>`	Execute in specific workspace	Current directory
`--agentId <id>`	Target specific agent by ID	Workspace 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:

Option	Description
`--workspace <path>`	Monitor jobs for specific workspace
`--subscribe`	Receive continuous updates every minute
`--unsubscribe`	Stop receiving updates
`--listen`	Listen 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 Command Center 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

​Command Overview

​set

​config

​init

​Local Execution

​Remote Execution

​agents

​query

​jobs

​Best Practices

​Common Workflows

​Troubleshooting

​Next Steps

Command Overview

set

config

init

Local Execution

Remote Execution

agents

query

jobs

Best Practices

Common Workflows

Troubleshooting

Next Steps