> ## Documentation Index
> Fetch the complete documentation index at: https://docs.run-agent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Overview

> Master the RunAgent command-line interface

The RunAgent CLI is your primary tool for creating, testing, and deploying AI agents. It provides a simple yet powerful interface for managing the entire agent lifecycle.

## Installation

```bash theme={null}
pip install runagent
```

Verify installation:

```bash theme={null}
runagent --version
```

## Global Options

All RunAgent commands support these global options:

| Option      | Description                |
| ----------- | -------------------------- |
| `--help`    | Show help message and exit |
| `--version` | Display RunAgent version   |
| `--verbose` | Enable verbose output      |
| `--quiet`   | Suppress non-error output  |

## Available Commands

<CardGroup cols={2}>
  <Card title="setup" icon="gear" href="/cli/commands/setup">
    Configure authentication and API keys (Coming Soon)
  </Card>

  <Card title="teardown" icon="trash" href="/cli/commands/teardown">
    Remove RunAgent configuration (Coming Soon)
  </Card>

  <Card title="init" icon="sparkles" href="/cli/commands/init">
    Initialize a new agent project
  </Card>

  <Card title="template" icon="copy" href="/cli/commands/template">
    Manage project templates
  </Card>

  <Card title="serve" icon="server" href="/cli/commands/serve">
    Run agent locally for testing
  </Card>

  <Card title="upload" icon="upload" href="/cli/commands/upload">
    Upload agent to remote server (Coming Soon)
  </Card>

  <Card title="start" icon="power-off" href="/cli/commands/start">
    Start uploaded agent on remote server (Coming Soon)
  </Card>

  <Card title="deploy" icon="rocket" href="/cli/commands/deploy">
    Full deployment (upload + start) or local deploy
  </Card>

  <Card title="run" icon="play" href="/cli/commands/run">
    Execute a deployed agent
  </Card>

  <Card title="db-status" icon="database" href="/cli/commands/db-status">
    Show local database status and statistics
  </Card>

  <Card title="delete" icon="x" href="/cli/commands/delete">
    Delete an agent from local database
  </Card>
</CardGroup>

## Command Structure

RunAgent follows a consistent command structure:

```bash theme={null}
runagent [GLOBAL_OPTIONS] COMMAND [COMMAND_OPTIONS] [ARGUMENTS]
```

Examples:

```bash theme={null}
runagent init my-agent --framework langgraph
runagent serve . --port 8080
runagent run --id agent-id --tag main --input '{"query": "Hello"}'
```

*Note: Authentication and remote deployment commands are coming soon*

## Command Categories

### **Setup & Configuration** (Authentication Coming Soon)

* `setup` - Configure authentication with API keys (Coming Soon)
* `teardown` - Remove all RunAgent configuration (Coming Soon)
* `db-status` - Monitor local database and capacity

### **Project Management**

* `init` - Create new agent projects from templates
* `template` - List and manage available templates

### **Local Development**

* `serve` - Start local FastAPI server for testing and deployment
* `delete` - Remove agents from local database

### **Remote Deployment** (Coming Soon)

* `upload` - Upload agent code to remote server
* `start` - Start uploaded agent on remote server
* `deploy` - Full deployment workflow (upload + start)

### **Execution**

* `run` - Execute deployed agents with flexible input options

## Common Workflows

### Development Workflow

<Steps>
  <Step title="Setup Authentication (Coming Soon)">
    ```bash theme={null}
    runagent setup --api-key your-api-key
    ```

    *Note: Authentication features are coming soon*
  </Step>

  <Step title="Create Project">
    ```bash theme={null}
    runagent init my-agent --framework langgraph
    cd my-agent
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    pip install -r requirements.txt
    ```
  </Step>

  <Step title="Configure Environment">
    ```bash theme={null}
    cp .env.example .env
    # Edit .env with your API keys
    ```
  </Step>

  <Step title="Test & Deploy Locally">
    ```bash theme={null}
    runagent serve .
    ```
  </Step>

  <Step title="Deploy to Remote (Coming Soon)">
    ```bash theme={null}
    runagent deploy .
    ```

    *Note: Remote deployment features are coming soon*
  </Step>
</Steps>

### Quick Commands Reference

<Tabs>
  <Tab title="Setup & Auth (Coming Soon)">
    ```bash theme={null}
    # Initial setup (Coming Soon)
    runagent setup --api-key your-key

    # Check configuration status
    runagent db-status --capacity

    # Remove configuration (Coming Soon)
    runagent teardown
    ```

    *Note: Authentication features are coming soon*
  </Tab>

  <Tab title="Project Management">
    ```bash theme={null}
    # Create new project
    runagent init PROJECT_NAME

    # List available templates
    runagent template --list

    # Create from specific template
    runagent init PROJECT_NAME --langgraph --template advanced

    # Interactive mode
    runagent init --interactive
    ```
  </Tab>

  <Tab title="Local Development">
    ```bash theme={null}
    # Start local server (automatically deploys with port allocation)
    runagent serve .

    # Use custom port
    runagent serve . --port 8080

    # Replace existing agent
    runagent serve . --replace agent-id

    # Check database status
    runagent db-status
    ```
  </Tab>

  <Tab title="Remote Deployment (Coming Soon)">
    ```bash theme={null}
    # Upload agent (Coming Soon)
    runagent upload --folder .

    # Start uploaded agent (Coming Soon)
    runagent start --id AGENT_ID

    # Full deployment (upload + start) (Coming Soon)
    runagent deploy --folder .

    # Deploy locally with serve command
    runagent serve .
    ```

    *Note: Remote deployment features are coming soon*
  </Tab>

  <Tab title="Execution">
    ```bash theme={null}
    # Run agent with parameters
    runagent run --id AGENT_ID --tag main --param1=value1 --param2=value2

    # Run with input file
    runagent run --id AGENT_ID --tag main --input config.json

    # Run locally
    runagent run --id AGENT_ID --tag main --local

    # Run with host/port
    runagent run --host localhost --port 8080 --tag main
    ```
  </Tab>

  <Tab title="Management">
    ```bash theme={null}
    # List local agents
    runagent db-status

    # Check capacity
    runagent db-status --capacity

    # Delete agent
    runagent delete --id AGENT_ID

    # Get agent details
    runagent db-status --agent-id AGENT_ID
    ```
  </Tab>
</Tabs>

## Configuration Management

### Authentication Setup (Coming Soon)

```bash theme={null}
# Setup with API key (Coming Soon)
runagent setup --api-key your-api-key

# Setup with custom base URL (Coming Soon)
runagent setup --api-key your-key --base-url https://custom-api.com

# Force reconfiguration (Coming Soon)
runagent setup --api-key new-key --force

# Remove all configuration (Coming Soon)
runagent teardown
```

*Note: Authentication and remote deployment features are coming soon.*

The setup command will create a configuration file at:

* Linux/Mac: `~/.runagent/user_data.json`
* Windows: `%USERPROFILE%\.runagent\user_data.json`

### Environment Variables (Coming Soon)

RunAgent CLI will support these environment variables:

| Variable             | Description                                 |
| -------------------- | ------------------------------------------- |
| `RUNAGENT_API_KEY`   | API key for authentication (Coming Soon)    |
| `RUNAGENT_BASE_URL`  | Custom API endpoint (Coming Soon)           |
| `RUNAGENT_CACHE_DIR` | Custom cache directory location             |
| `RUNAGENT_LOG_LEVEL` | Logging level (DEBUG, INFO, WARNING, ERROR) |

*Note: Authentication-related environment variables are coming soon.*

## Local Database Management

RunAgent maintains a local SQLite database for managing agents:

```bash theme={null}
# View database status
runagent db-status

# Check capacity (5 agents max)
runagent db-status --capacity

# View specific agent
runagent db-status --agent-id AGENT_ID

# Delete agent
runagent delete --id AGENT_ID

# Clean up old records
runagent db-status --cleanup-days 30
```

### Capacity Management

The local database supports up to **5 agents** simultaneously. When at capacity:

```bash theme={null}
# Replace oldest agent
runagent serve . --replace OLDEST_AGENT_ID

# Or delete an agent first
runagent delete --id AGENT_ID
```

## Output Formats

Most commands support different output formats:

```bash theme={null}
# Default human-readable output
runagent template --list

# JSON output for scripting
runagent template --list --format json

# Minimal output
runagent serve . --quiet
```

## Error Handling

RunAgent provides clear error messages:

```bash theme={null}
$ runagent serve nonexistent
Error: Directory 'nonexistent' does not exist

$ runagent run --id invalid-id --tag main
Error: Agent 'invalid-id' not found
```

### Common Exit Codes

| Code | Meaning                  |
| ---- | ------------------------ |
| 0    | Success                  |
| 1    | General error            |
| 2    | Command line usage error |
| 3    | Configuration error      |
| 4    | Network/API error        |
| 5    | Authentication error     |

## Advanced Usage

### Animation Control

```bash theme={null}
# Skip startup animation
runagent serve . --no-animation

# Use different animation style
runagent serve . --animation-style quick
runagent serve . --animation-style minimal
```

### Debugging

Enable verbose output for troubleshooting:

```bash theme={null}
# Verbose mode
runagent --verbose serve .

# Debug logging
RUNAGENT_LOG_LEVEL=DEBUG runagent serve .

# Check configuration status
runagent db-status --capacity
```

### Piping and Scripting

```bash theme={null}
# Pipe input from file
cat input.json | runagent run --id AGENT_ID --tag main --input -

# Use in scripts
if runagent db-status --capacity; then
    echo "Database has available slots"
else
    echo "Database is at capacity"
    exit 1
fi
```

### Aliases and Shortcuts

Add to your shell configuration:

```bash theme={null}
# ~/.bashrc or ~/.zshrc
alias ra='runagent'
alias ras='runagent serve .'
alias rad='runagent deploy .'
alias radb='runagent db-status'

# Function for quick agent creation
new-agent() {
    runagent init "$1" --framework langgraph && cd "$1"
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use Version Control">
    Always commit your `runagent.config.json` but never commit `.env` files containing API keys
  </Accordion>

  <Accordion title="Test Before Deploying">
    Use `runagent serve` and `runagent deploy-local` to test locally before deploying remotely
  </Accordion>

  <Accordion title="Monitor Capacity">
    Use `runagent db-status --capacity` to monitor local database usage
  </Accordion>

  <Accordion title="Use Templates">
    Start with templates for faster development: `runagent template --list`
  </Accordion>

  <Accordion title="Automate with Scripts">
    Use the CLI in CI/CD pipelines for automated deployments
  </Accordion>
</AccordionGroup>

## Getting Help

```bash theme={null}
# General help
runagent --help

# Command-specific help
runagent init --help
runagent serve --help
runagent run --help

# Check version
runagent --version

# View configuration status
runagent db-status --capacity
```

<Info>
  Join our [Discord community](https://discord.gg/runagent) for support and discussions about RunAgent CLI
</Info>

<Card title="Still have a question?" icon="circle-question" href="/components/columns">
  * Join our [Discord Community](https://discord.gg/Q9P9AdHVHz)
  * Email us: [hi@run-agent.ai](mailto:hi@run-agent.ai)
  * Follow us on [X](https://x.com/run_agent)
  * New here? [Sign up](https://run-agent.ai/dashboard)
</Card>