Documentation Index
Fetch the complete documentation index at: https://docs.2501.ai/llms.txt
Use this file to discover all available pages before exploring further.
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.
api_key
Set your API key for authentication:
@2501 set api_key YOUR_API_KEY
config
Fetch and display available agent configurations from the API, including specialties and operational settings.
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.
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
@2501 init --remote-exec user@server.com:22 --remote-private-key "$(cat ./custom-key.pem)"
@2501 init --remote-exec user@server.com:22 --remote-exec-password yourpassword
@2501 init --remote-exec user@windows-server.com:5985 --remote-exec-type winrm --remote-exec-password yourpassword
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)"
agents
List and manage agents in the current workspace or across your machine.
Options:
| Option | Description |
|---|
--workspace <path> | List agents in specific workspace |
--all | List all agents on the machine |
--flush | Clear cached agent data |
# Current workspace
@2501 agents
# All agents on machine
@2501 agents --all
# Specific workspace
@2501 agents --workspace ~/projects/backend
# Clear cache
@2501 agents --flush
query
Execute tasks by sending natural language instructions to agents. This is the primary command for assigning work.
or
@2501 query <query> [options]
| Option | Description | Default |
|---|
--workspace <path> | Execute in specific workspace | Current directory |
--agentId <id> | Target specific agent by ID | Workspace agent |
# 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
jobs
Monitor and manage jobs—coordinated multi-task operations created by gateways or manual orchestration.
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 |
# 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
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
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
@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
@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
