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:
OptionDescription
--helpShow help message and exit
--versionDisplay RunAgent version
--verboseEnable verbose output
--quietSuppress 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

1

Setup Authentication (Coming Soon)

runagent setup --api-key your-api-key
Note: Authentication features are coming soon
2

Create Project

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

Install Dependencies

pip install -r requirements.txt
4

Configure Environment

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

Test & Deploy Locally

runagent serve .
6

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

​
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:
VariableDescription
RUNAGENT_API_KEYAPI key for authentication (Coming Soon)
RUNAGENT_BASE_URLCustom API endpoint (Coming Soon)
RUNAGENT_CACHE_DIRCustom cache directory location
RUNAGENT_LOG_LEVELLogging 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

CodeMeaning
0Success
1General error
2Command line usage error
3Configuration error
4Network/API error
5Authentication 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

Always commit your runagent.config.json but never commit .env files containing API keys
Use runagent serve and runagent deploy-local to test locally before deploying remotely
Use runagent db-status --capacity to monitor local database usage
Start with templates for faster development: runagent template --list
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