AgentFlow CLI - Complete Guide¶

The agentflow CLI is a professional command-line interface for scaffolding, running, and deploying agent-based APIs built with the AgentFlow framework.

Installation¶

pip install 10xscale-agentflow-cli

For development with all optional dependencies:

pip install "10xscale-agentflow-cli[redis,sentry,firebase,snowflakekit,gcloud]"

Quick Start¶

# Initialize a new project
agentflow init

# Start development server
agentflow api

# Generate Dockerfile
agentflow build

Commands Overview¶

Command	Description
`agentflow init`	Initialize a new project with config and graph scaffold
`agentflow api`	Start the development API server
`agentflow build`	Generate Docker deployment files
`agentflow version`	Display CLI and package versions

`agentflow init`¶

Initialize a new AgentFlow project with configuration and sample graph code.

Synopsis¶

agentflow init [OPTIONS]

Options¶

Option	Type	Default	Description
`--path`, `-p`	STRING	`.`	Directory to initialize files in
`--force`, `-f`	FLAG	`False`	Overwrite existing files
`--prod`	FLAG	`False`	Include production configuration files
`--verbose`, `-v`	FLAG	`False`	Enable verbose logging
`--quiet`, `-q`	FLAG	`False`	Suppress all output except errors

Behavior¶

Default Mode: - Creates agentflow.json configuration file - Creates graph/react.py with a sample React-based agent - Creates graph/__init__.py to make it a Python package

Production Mode (--prod): - All default files plus: - .pre-commit-config.yaml - Pre-commit hooks configuration - pyproject.toml - Python project metadata and tooling config

Examples¶

Basic initialization:

agentflow init

Initialize in a specific directory:

agentflow init --path ./my-agent-project

Initialize with production config:

agentflow init --prod

Overwrite existing files:

agentflow init --force

Initialize production project in a new directory:

agentflow init --prod --path ./production-agent --force
cd production-agent
pre-commit install

Generated Files¶

`agentflow.json`¶

{
  "agent": "graph.react:app",
  "env": ".env",
  "auth": null,
  "checkpointer": null,
  "injectq": null,
  "store": null,
  "redis": null,
  "thread_name_generator": null
}

`graph/react.py`¶

A fully-commented sample agent implementation featuring: - LiteLLM integration for AI completion - Tool definition and execution - State graph orchestration - Conditional routing - In-memory checkpointer

`agentflow api`¶

Start the AgentFlow API development server with hot-reload support.

Synopsis¶

agentflow api [OPTIONS]

Options¶

Option	Type	Default	Description
`--config`, `-c`	STRING	`agentflow.json`	Path to configuration file
`--host`, `-H`	STRING	`0.0.0.0`	Host to bind the server to
`--port`, `-p`	INTEGER	`8000`	Port to bind the server to
`--reload` / `--no-reload`	FLAG	`True`	Enable/disable auto-reload
`--verbose`, `-v`	FLAG	`False`	Enable verbose logging
`--quiet`, `-q`	FLAG	`False`	Suppress all output except errors

Behavior¶

Loads the specified configuration file
Loads environment variables from .env file (or file specified in config)
Sets GRAPH_PATH environment variable
Starts Uvicorn server with specified host and port
Watches for file changes and auto-reloads (if --reload is enabled)

Examples¶

Start with default settings:

agentflow api

Start with custom config file:

agentflow api --config production.json

Start on localhost only:

agentflow api --host 127.0.0.1

Start on custom port:

agentflow api --port 9000

Start without auto-reload (for testing):

agentflow api --no-reload

Start with verbose logging:

agentflow api --verbose

Combine multiple options:

agentflow api --config staging.json --host 127.0.0.1 --port 8080 --verbose

Server Access¶

Once started, the API is accessible at: - Default: http://0.0.0.0:8000 - Local access: http://localhost:8000 - Network access: http://<your-ip>:8000

API Endpoints¶

The server provides several endpoints: - GET /ping - Health check endpoint - POST /threads - Create a new thread - GET /threads/{thread_id} - Get thread details - POST /threads/{thread_id}/messages - Send a message - GET /threads/{thread_id}/messages - Get thread messages

Development Workflow¶

# 1. Initialize project
agentflow init

# 2. Create .env file with your API keys
echo "GEMINI_API_KEY=your_key_here" > .env

# 3. Start development server
agentflow api --verbose

# 4. Test the API
curl http://localhost:8000/ping

# 5. Make changes to your graph - server auto-reloads

`agentflow build`¶

Generate production-ready Docker deployment files.

Synopsis¶

agentflow build [OPTIONS]

Options¶

Option	Type	Default	Description
`--output`, `-o`	STRING	`Dockerfile`	Output Dockerfile path
`--force`, `-f`	FLAG	`False`	Overwrite existing files
`--python-version`	STRING	`3.13`	Python version for base image
`--port`, `-p`	INTEGER	`8000`	Port to expose in container
`--docker-compose`	FLAG	`False`	Also generate docker-compose.yml
`--service-name`	STRING	`agentflow-cli`	Service name in docker-compose
`--verbose`, `-v`	FLAG	`False`	Enable verbose logging
`--quiet`, `-q`	FLAG	`False`	Suppress all output except errors

Behavior¶

Searches for requirements.txt in common locations:
./requirements.txt
./requirements/requirements.txt
./requirements/base.txt
./requirements/production.txt
Generates optimized Dockerfile with:
Multi-stage build support
Non-root user for security
Health check configuration
Gunicorn + Uvicorn workers
Optionally generates docker-compose.yml

Examples¶

Generate basic Dockerfile:

agentflow build

Generate with custom Python version:

agentflow build --python-version 3.12

Generate with custom port:

agentflow build --port 9000

Generate Dockerfile and docker-compose.yml:

agentflow build --docker-compose

Complete production setup:

agentflow build --docker-compose --python-version 3.13 --port 8000 --force

Custom service name in docker-compose:

agentflow build --docker-compose --service-name my-agent-api

Generated Dockerfile Features¶

Base Image: Python slim image for reduced size
Security: Non-root user execution
Optimization: Multi-layer caching for faster builds
Health Check: Built-in /ping endpoint monitoring
Production Server: Gunicorn with Uvicorn workers

Docker Build and Run¶

After generating the Dockerfile:

# Build the image
docker build -t my-agent-api .

# Run the container
docker run -p 8000:8000 --env-file .env my-agent-api

# Or use docker-compose
docker compose up --build

`agentflow version`¶

Display version information for the CLI and installed packages.

Synopsis¶

agentflow version [OPTIONS]

Options¶

Option	Type	Default	Description
`--verbose`, `-v`	FLAG	`False`	Show additional version details
`--quiet`, `-q`	FLAG	`False`	Show only version number

Examples¶

# Show version
agentflow version

# Verbose output with dependencies
agentflow version --verbose

Global Options¶

All commands support these global options:

Option	Description
`--help`, `-h`	Show help message and exit
`--verbose`, `-v`	Enable verbose logging output
`--quiet`, `-q`	Suppress all output except errors

Examples¶

# Get help for any command
agentflow init --help
agentflow api --help
agentflow build --help

# Run with verbose output
agentflow api --verbose
agentflow build --verbose

Configuration File Resolution¶

The CLI searches for configuration files in this order:

Explicit path: If you provide --config /path/to/config.json, it uses that
Current directory: Looks for agentflow.json in current working directory
Relative to script: Searches relative to the CLI installation
Package directory: Falls back to package installation location

Environment Variables¶

The CLI respects these environment variables:

Variable	Purpose	Used By
`GRAPH_PATH`	Path to active config file	API server
`GEMINI_API_KEY`	API key for Gemini models	LiteLLM
`OPENAI_API_KEY`	API key for OpenAI models	LiteLLM
`JWT_SECRET_KEY`	Secret key for JWT auth	Auth system
`JWT_ALGORITHM`	Algorithm for JWT (e.g., HS256)	Auth system
`SNOWFLAKE_*`	Snowflake ID generator config	ID generation

Exit Codes¶

Code	Meaning
`0`	Success
`1`	General error
`2`	Configuration error
`3`	Validation error
`130`	Interrupted by user (Ctrl+C)

Common Workflows¶

Starting a New Project¶

# 1. Initialize with production config
agentflow init --prod

# 2. Install pre-commit hooks
pre-commit install

# 3. Create environment file
cat > .env << EOF
GEMINI_API_KEY=your_api_key_here
LOG_LEVEL=INFO
EOF

# 4. Install dependencies
pip install -e ".[redis,sentry]"

# 5. Start development server
agentflow api --verbose

Development Workflow¶

# Start server with auto-reload
agentflow api --reload --verbose

# In another terminal, test the API
curl http://localhost:8000/ping

# Make changes to graph/react.py
# Server automatically reloads

Production Deployment¶

# 1. Generate Docker files
agentflow build --docker-compose --force

# 2. Review generated files
cat Dockerfile
cat docker-compose.yml

# 3. Build and test locally
docker compose up --build

# 4. Push to registry
docker tag agentflow-cli:latest registry.example.com/agentflow:latest
docker push registry.example.com/agentflow:latest

# 5. Deploy to production
kubectl apply -f k8s/deployment.yaml

Testing Different Configurations¶

# Test with different config files
agentflow api --config dev.json --port 8001 &
agentflow api --config staging.json --port 8002 &
agentflow api --config prod.json --port 8003 &

# Test each endpoint
curl http://localhost:8001/ping
curl http://localhost:8002/ping
curl http://localhost:8003/ping

Troubleshooting¶

Server won't start¶

Problem: Error loading graph from graph.react:app

Solution:

# Ensure your graph directory is a Python package
touch graph/__init__.py

# Verify your PYTHONPATH
export PYTHONPATH="${PYTHONPATH}:$(pwd)"

# Check your config file
cat agentflow.json

Port already in use¶

Problem: OSError: [Errno 48] Address already in use

Solution:

# Find process using the port
lsof -i :8000

# Kill the process
kill -9 <PID>

# Or use a different port
agentflow api --port 8001

Config file not found¶

Problem: ConfigurationError: Config file not found

Solution:

# Check current directory
ls -la agentflow.json

# Use explicit path
agentflow api --config /full/path/to/agentflow.json

# Or initialize a new config
agentflow init

Requirements not found during build¶

Problem: No requirements.txt found

Solution:

# Create requirements.txt
pip freeze > requirements.txt

# Or let build use default installation
agentflow build  # Will install agentflow-cli from PyPI

Best Practices¶

Development¶

Use verbose logging during development:
```
agentflow api --verbose
```
Keep auto-reload enabled for faster iteration:
```
agentflow api --reload
```
Use localhost for local-only access:
```
agentflow api --host 127.0.0.1
```

Production¶

Disable auto-reload in production:
```
agentflow api --no-reload
```
Use environment-specific configs:
```
agentflow api --config production.json
```

Run behind a reverse proxy (nginx, Traefik):

# Bind to localhost only
agentflow api --host 127.0.0.1 --port 8000

Use Docker for consistent deployments:

agentflow build --docker-compose --force
docker compose up -d

Security¶

Never commit .env files - add to .gitignore
Use different secrets per environment
Run containers as non-root user (Dockerfile does this automatically)

Keep dependencies updated:

pip install --upgrade 10xscale-agentflow-cli

Additional Resources¶

Configuration Guide - Complete configuration reference
Deployment Guide - Production deployment strategies
Authentication Guide - Setting up auth

Getting Help¶

# Command-specific help
agentflow init --help
agentflow api --help
agentflow build --help

# Check version
agentflow version

AgentFlow CLI - Complete Guide¶

Installation¶

Quick Start¶

Commands Overview¶

agentflow init¶

Synopsis¶

Options¶

Behavior¶

Examples¶

Generated Files¶

agentflow.json¶

graph/react.py¶

agentflow api¶

Synopsis¶

Options¶

Behavior¶

Examples¶

Server Access¶

API Endpoints¶

Development Workflow¶

agentflow build¶

Synopsis¶

Options¶

Behavior¶

Examples¶

Generated Dockerfile Features¶

Docker Build and Run¶

agentflow version¶

Synopsis¶

Options¶

Examples¶

Global Options¶

Examples¶

Configuration File Resolution¶

Environment Variables¶

Exit Codes¶

Common Workflows¶

Starting a New Project¶

Development Workflow¶

Production Deployment¶

Testing Different Configurations¶

Troubleshooting¶

Server won't start¶

Port already in use¶

Config file not found¶

Requirements not found during build¶

Best Practices¶

Development¶

Production¶

Security¶

Additional Resources¶

Getting Help¶

`agentflow init`¶

`agentflow.json`¶

`graph/react.py`¶

`agentflow api`¶

`agentflow build`¶

`agentflow version`¶