> ## 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.

# Commands

> Discover all the available commands in 2501 CLI

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](#set)       | Configure CLI settings        |
| [config](#config) | View available configurations |
| [init](#init)     | Initialize a new agent        |
| [agents](#agents) | Manage and list agents        |
| [query](#query)   | Execute tasks with agents     |
| [jobs](#jobs)     | Monitor and manage jobs       |

## set

Configure essential CLI settings, primarily for authentication.

```bash theme={null}
@2501 set <key> <value>
```

**api\_key**

Set your API key for authentication:

```bash theme={null}
@2501 set api_key YOUR_API_KEY
```

Retrieve your API key from [accounts.2501.ai](https://accounts.2501.ai). See [Authentication](/0.4/cli/authentication) for details.

***

## config

Fetch and display available agent configurations from the API, including specialties and operational settings.

```bash theme={null}
@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.

```bash theme={null}
@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):

```bash theme={null}
@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:**

```bash theme={null}
@2501 init --name prod-ops --remote-exec user@server.com:22
```

**SSH with Custom Private Key:**

```bash theme={null}
@2501 init --remote-exec user@server.com:22 --remote-private-key "$(cat ./custom-key.pem)"
```

**SSH with Password:**

```bash theme={null}
@2501 init --remote-exec user@server.com:22 --remote-exec-password yourpassword
```

Key-based authentication is recommended over passwords.

**WinRM for Windows:**

```bash theme={null}
@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:**

```bash theme={null}
@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.

```bash theme={null}
@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:**

```bash theme={null}
# 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.

```bash theme={null}
@2501 <query> [options]
```

or

```bash theme={null}
@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:**

```bash theme={null}
# 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](../core-concepts/gateways) or manual orchestration.

```bash theme={null}
@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:**

```bash theme={null}
# 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:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
@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:**

```bash theme={null}
@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](/0.4/cli/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](https://discord.gg/DYC8ryeC7e) or contact [hello@2501.ai](mailto:hello@2501.ai).

## Next Steps

* Learn about [Agents](../core-concepts/agents) configuration and management
* Explore [Tasks](../core-concepts/tasks) for execution details
* Review [Specialties](../configure/specialties) for domain-specific configurations
* Set up [Gateways](../core-concepts/gateways) for automated task creation