10xscale-agentflow-cli 0.3.2

CLI and API for 10xscale AgentFlow

AgentFlow CLI

A professional Python API framework for building agent-based applications with FastAPI, state graph orchestration, and comprehensive CLI tools.

📚 Documentation

• CLI Guide - Complete command-line interface reference
• Configuration Guide - All configuration options explained
• Deployment Guide - Docker, Kubernetes, and cloud deployment
• Authentication Guide - JWT and custom authentication
• Rate Limiting Guide - Memory, Redis, and custom rate-limit backends
• ID Generation Guide - Snowflake ID generation
• Thread Name Generator Guide - Thread naming strategies

Quick Start

Installation

pip install 10xscale-agentflow-cli

Redis rate limiting is optional. Install the Redis extra only when you configure rate_limit.backend as redis:

pip install "10xscale-agentflow-cli[redis]"

JWT auth and document text extraction are optional too. Install only the extra you need:

pip install "10xscale-agentflow-cli[jwt]"
pip install "10xscale-agentflow-cli[media]"

Initialize a New Project

# Create project structure
agentflow init

# Or with production config
agentflow init --prod

Start Development Server

agentflow api

Start API With Play

agentflow play

Generate Docker Files

agentflow build --docker-compose

Key Features

• ✅ CLI Tools - Professional command-line interface for scaffolding and deployment
• ✅ State Graph Orchestration - Build complex agent workflows with LangGraph
• ✅ FastAPI Backend - High-performance async web framework
• ✅ Authentication - Built-in JWT auth and custom authentication support
• ✅ Rate Limiting - Sliding-window limits with memory, Redis, and custom backends
• ✅ ID Generation - Distributed Snowflake ID generation
• ✅ Thread Management - Intelligent thread naming and conversation management
• ✅ Docker Ready - Generate production-ready Docker files
• ✅ Dependency Injection - InjectQ for clean dependency management
• ✅ Development Tools - Hot-reload, pre-commit hooks, testing

CLI Commands

For detailed command documentation, see the CLI Guide.

agentflow init

Initialize a new project with configuration and sample graph.

# Basic initialization
agentflow init

# With production config (pyproject.toml, pre-commit hooks)
agentflow init --prod

# Custom directory
agentflow init --path ./my-project

# Force overwrite existing files
agentflow init --force

agentflow api

Start the development API server.

# Start with defaults (localhost:8000)
agentflow api

# Custom host and port
agentflow api --host 127.0.0.1 --port 9000

# Custom config file
agentflow api --config production.json

# Disable auto-reload
agentflow api --no-reload

# Verbose logging
agentflow api --verbose

agentflow play

Start the development API server and open the hosted playground with your local backend URL preconfigured.

# Start with defaults and open the playground
agentflow play

# Custom host and port
agentflow play --host 127.0.0.1 --port 9000

# Custom config file
agentflow play --config production.json

# Disable auto-reload
agentflow play --no-reload

agentflow build

Generate production Docker files.

# Generate Dockerfile
agentflow build

# Generate Dockerfile and docker-compose.yml
agentflow build --docker-compose

# Custom Python version and port
agentflow build --python-version 3.12 --port 9000

# Force overwrite
agentflow build --force

agentflow version

Display version information.

agentflow version

Configuration

The configuration file (agentflow.json) defines your agent, authentication, and infrastructure settings:

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

Configuration Options

Field	Type	Description
agent	string	Path to your compiled agent graph (required)
env	string	Path to environment variables file
auth	null|"jwt"|object	Authentication configuration
checkpointer	string|null	Path to custom checkpointer
injectq	string|null	Path to InjectQ container
store	string|null	Path to data store
redis	string|null	Redis connection URL
rate_limit	object|null	Sliding-window rate limiting configuration
thread_name_generator	string|null	Path to custom thread name generator

See the Configuration Guide for complete details.

Authentication

AgentFlow supports multiple authentication strategies. See the Authentication Guide for complete details.

No Authentication

{
  "auth": null
}

JWT Authentication

agentflow.json:

{
  "auth": "jwt"
}

.env:

JWT_SECRET_KEY=your-super-secret-key
JWT_ALGORITHM=HS256

Custom Authentication

agentflow.json:

{
  "auth": {
    "method": "custom",
    "path": "auth.custom:MyAuthBackend"
  }
}

auth/custom.py:

from agentflow_cli import BaseAuth
from fastapi import Response, HTTPException
from fastapi.security import HTTPAuthorizationCredentials

class MyAuthBackend(BaseAuth):
    def authenticate(
        self,
        res: Response,
        credential: HTTPAuthorizationCredentials
    ) -> dict[str, any] | None:
        # Your authentication logic
        token = credential.credentials
        user = verify_token(token)

        if not user:
            raise HTTPException(401, "Invalid token")

        return {
            "user_id": user.id,
            "username": user.username,
            "email": user.email
        }

ID Generation

AgentFlow includes Snowflake ID generation for distributed, time-sortable unique IDs.

pip install "10xscale-agentflow-cli[snowflakekit]"

Usage:

from agentflow_cli import SnowFlakeIdGenerator

# Initialize
generator = SnowFlakeIdGenerator(
    snowflake_epoch=1704067200000,  # Jan 1, 2024
    snowflake_node_id=1,
    snowflake_worker_id=1
)

# Generate ID
id = await generator.generate()
print(f"Generated ID: {id}")

Environment Configuration:

SNOWFLAKE_EPOCH=1704067200000
SNOWFLAKE_NODE_ID=1
SNOWFLAKE_WORKER_ID=1
SNOWFLAKE_TIME_BITS=39
SNOWFLAKE_NODE_BITS=5
SNOWFLAKE_WORKER_BITS=8

See the ID Generation Guide for more details.

Thread Name Generation

Generate human-friendly names for conversation threads.

from agentflow_cli.src.app.utils.thread_name_generator import AIThreadNameGenerator

generator = AIThreadNameGenerator()
name = generator.generate_name()
# Output: "thoughtful-dialogue", "exploring-ideas", etc.

See the Thread Name Generator Guide for custom implementations.

Security

AgentFlow CLI provides enterprise-grade security features for production deployments.

Security Features

• ✅ Authentication - Built-in JWT and custom authentication backends
• ✅ Authorization - Resource-based access control with extensible backends
• ✅ Request Limits - DoS protection with configurable size limits (default 10MB)
• ✅ Error Sanitization - Production-safe error messages preventing information disclosure
• ✅ Log Sanitization - Automatic redaction of sensitive data (tokens, passwords, secrets)
• ✅ Security Warnings - Startup validation for insecure configurations
• ✅ HTTPS Ready - SSL/TLS support with secure headers

Production Security Checklist

Before deploying to production, ensure:

# Required: Set production mode
MODE=production

# Required: Strong JWT secret (32+ characters)
JWT_SECRET_KEY=<generate-with-secrets.token_urlsafe(32)>

# Required: Disable debug mode
IS_DEBUG=false

# Required: Specific CORS origins (not *)
ORIGINS=https://yourdomain.com

# Required: Specific allowed hosts (not *)
ALLOWED_HOST=yourdomain.com

# Recommended: Disable API docs
DOCS_PATH=
REDOCS_PATH=

# Recommended: Configure request size limit
MAX_REQUEST_SIZE=10485760  # 10MB default

Quick Security Setup

1. Enable JWT Authentication:

{
  "auth": "jwt"
}

2. Implement Authorization:

# auth/rbac_backend.py
from agentflow_cli.src.app.core.auth.authorization import AuthorizationBackend

class RBACAuthorizationBackend(AuthorizationBackend):
    async def authorize(self, user, resource, action, resource_id=None, **context):
        role = user.get("role", "viewer")
        # Implement your authorization logic
        return role == "admin" or (role == "developer" and action == "read")

3. Configure in agentflow.json:

{
  "auth": "jwt",
  "authorization": {
    "path": "auth.rbac_backend:RBACAuthorizationBackend"
  }
}

Security Validation

AgentFlow automatically validates your configuration and warns about security issues:

⚠️  SECURITY WARNING: CORS ORIGINS='*' in production.
   Set ORIGINS to specific domains.

⚠️  SECURITY WARNING: DEBUG mode enabled in production!
   Set IS_DEBUG=false

Comprehensive Security Guide

For detailed security documentation, threat model, best practices, and deployment guidelines, see:

📖 SECURITY.md - Complete Security Guide

Topics covered:

• Threat model and attack vectors
• Authentication and authorization patterns
• Production deployment checklist
• Docker and Kubernetes security configurations
• Security testing and monitoring
• Incident response procedures
• Vulnerability reporting

Deployment

See the Deployment Guide for complete deployment instructions.

Docker Deployment

# Generate Docker files
agentflow build --docker-compose

# Build and run
docker compose up --build -d

# Check logs
docker compose logs -f

Kubernetes

See Deployment Guide - Kubernetes for complete manifests.

Cloud Platforms

• AWS ECS
• Google Cloud Run
• Azure Container Instances
• Heroku

Project Structure

agentflow-cli/
├── agentflow_cli/          # Main package
│   ├── __init__.py        # Package exports
│   ├── cli/               # CLI commands
│   │   ├── main.py       # CLI entry point
│   │   └── commands/     # Command implementations
│   └── src/              # Application source
│       └── app/          # FastAPI application
│           ├── main.py   # App entry point
│           ├── core/     # Core functionality
│           ├── routers/  # API routes
│           └── utils/    # Utilities
├── graph/                 # Agent graphs
│   ├── __init__.py
│   └── react.py          # Sample React agent
├── docs/                  # Documentation
├── tests/                 # Test suite
├── agentflow.json        # Configuration
├── pyproject.toml        # Project metadata
└── README.md             # This file

Development

Setup

# Clone repository
git clone https://github.com/10xHub/agentflow-cli.git
cd agentflow-cli

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Testing

# Run all tests
pytest

# With coverage
pytest --cov=agentflow_cli --cov-report=html

# Run specific test file
pytest tests/test_cli.py -v

Code Quality

# Format code
ruff format .

# Lint code
ruff check .

# Fix auto-fixable issues
ruff check --fix .

Using the Makefile

# Show available commands
make help

# Install development dependencies
make dev-install

# Run tests
make test

# Format and lint
make format
make lint

# Build package
make build

# Clean build artifacts
make clean

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

MIT License - see LICENSE file for details.

Support

• Documentation: Complete Documentation
• Issues: GitHub Issues
• Repository: GitHub

Credits

Developed by 10xScale and maintained by the community.

---

Made with ❤️ for the AI agent development community