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

init

Initialize a new agent project

serve

Run agent locally for testing

deploy

Deploy agent to production

run

Execute a deployed agent

upload

Upload agent to server

start

Start uploaded agent

setup

Configure authentication

template

Manage project templates

​
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 deploy . --env production
runagent run agent-id --input '{"query": "Hello"}'

​
Common Workflows

​
Development Workflow

1

Create Project

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

Install Dependencies

pip install -r requirements.txt
3

Configure Environment

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

Test Locally

runagent serve .
5

Deploy

runagent deploy .

​
Quick Commands Reference

# Create new project
runagent init PROJECT_NAME

# List available templates
runagent template list

# Create from specific template
runagent init PROJECT_NAME --template chatbot

​
Configuration Management

​
Authentication Setup

# Initial setup
runagent setup

# Remove configuration
runagent teardown

The setup command creates a configuration file at:

  • Linux/Mac: ~/.runagent/config.json
  • Windows: %USERPROFILE%\.runagent\config.json

​
Environment Variables

RunAgent CLI respects these environment variables:

VariableDescription
RUNAGENT_API_KEYAPI key for authentication
RUNAGENT_API_URLCustom API endpoint
RUNAGENT_CONFIG_PATHCustom config file location
RUNAGENT_LOG_LEVELLogging level (DEBUG, INFO, WARNING, ERROR)

​
Output Formats

Most commands support different output formats:

# Default human-readable output
runagent list

# JSON output for scripting
runagent list --json

# Minimal output
runagent list --quiet

​
Error Handling

RunAgent provides clear error messages:

$ runagent serve nonexistent
Error: Directory 'nonexistent' does not exist

$ runagent run invalid-id
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

​
Piping and Scripting

# Pipe input from file
cat input.json | runagent run AGENT_ID --input -

# Use in scripts
if runagent serve . --check; then
    echo "Agent configuration valid"
else
    echo "Configuration errors found"
    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 .'

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

​
Debugging

Enable verbose output for troubleshooting:

# Verbose mode
runagent --verbose serve .

# Debug logging
RUNAGENT_LOG_LEVEL=DEBUG runagent serve .

# Dry run (coming soon)
runagent deploy . --dry-run

​
Best Practices

​
Getting Help

# General help
runagent --help

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

# Check version
runagent --version

Join our Discord community for support and discussions