CLI Overview - RunAgent

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

pip install runagent

Verify installation:

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

setup

Configure authentication and API keys (Coming Soon)

teardown

Remove RunAgent configuration (Coming Soon)

init

Initialize a new agent project

template

Manage project templates

serve

Run agent locally for testing

upload

Upload agent to remote server (Coming Soon)

start

Start uploaded agent on remote server (Coming Soon)

deploy

Full deployment (upload + start) or local deploy

run

Execute a deployed agent

db-status

Show local database status and statistics

delete

Delete an agent from local database

Command Structure

RunAgent follows a consistent command structure:

runagent [GLOBAL_OPTIONS] COMMAND [COMMAND_OPTIONS] [ARGUMENTS]

Examples:

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

Setup Authentication (Coming Soon)

runagent setup --api-key your-api-key

Note: Authentication features are coming soon

Create Project

runagent init my-agent --framework langgraph
cd my-agent

Install Dependencies

pip install -r requirements.txt

Configure Environment

cp .env.example .env
# Edit .env with your API keys

Test & Deploy Locally

runagent serve .

Deploy to Remote (Coming Soon)

runagent deploy .

Note: Remote deployment features are coming soon

Quick Commands Reference

# 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

# 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

# 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

# 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

# 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

# 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

Configuration Management

Authentication Setup (Coming Soon)

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

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

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

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

$ 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

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

# Verbose mode
runagent --verbose serve .

# Debug logging
RUNAGENT_LOG_LEVEL=DEBUG runagent serve .

# Check configuration status
runagent db-status --capacity

Piping and Scripting

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

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

Use Version Control

Always commit your runagent.config.json but never commit .env files containing API keys

Test Before Deploying

Use runagent serve and runagent deploy-local to test locally before deploying remotely

Monitor Capacity

Use runagent db-status --capacity to monitor local database usage

Use Templates

Start with templates for faster development: runagent template --list

Automate with Scripts

Use the CLI in CI/CD pipelines for automated deployments

Getting Help

# 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

Join our Discord community for support and discussions about RunAgent CLI

Still have a question?

Join our Discord Community
Email us: [email protected]
Follow us on X
New here? Sign up

Reference

API Reference

SDK Reference

CLI Reference

Configuration

​Installation

​Global Options

​Available Commands

setup

teardown

init

template

serve

upload

start

deploy

run

db-status

delete

​Command Structure

​Command Categories

​Setup & Configuration (Authentication Coming Soon)

​Project Management

​Local Development

​Remote Deployment (Coming Soon)

​Execution

​Common Workflows

​Development Workflow

​Quick Commands Reference

​Configuration Management

​Authentication Setup (Coming Soon)

​Environment Variables (Coming Soon)

​Local Database Management

​Capacity Management

​Output Formats

​Error Handling

​Common Exit Codes

​Advanced Usage

​Animation Control

​Debugging

​Piping and Scripting

​Aliases and Shortcuts

​Best Practices

​Getting Help

Still have a question?

Installation

Global Options

Available Commands

Command Structure

Command Categories

Setup & Configuration (Authentication Coming Soon)

Project Management

Local Development

Remote Deployment (Coming Soon)

Execution

Common Workflows

Development Workflow

Quick Commands Reference

Configuration Management

Authentication Setup (Coming Soon)

Environment Variables (Coming Soon)

Local Database Management

Capacity Management

Output Formats

Error Handling

Common Exit Codes

Advanced Usage

Animation Control

Debugging

Piping and Scripting

Aliases and Shortcuts

Best Practices

Getting Help