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
ID Generation Guide - Snowflake ID generation
Thread Name Generator Guide - Thread naming strategies

Quick Start

Installation

pip install 10xscale-agentflow-cli

Initialize a New Project

# Create project structure
agentflow init

# Or with production config
agentflow init --prod

Start Development Server

agentflow api

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
✅ 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 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
`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

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:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests and linting
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

Name		Name	Last commit message	Last commit date
Latest commit History 114 Commits
.github		.github
.vscode		.vscode
agentflow_cli		agentflow_cli
docs		docs
examples/security		examples/security
graph		graph
scripts		scripts
tests		tests
.coveragerc		.coveragerc
.dockerignore		.dockerignore
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
ActionPlan.md		ActionPlan.md
MANIFEST.in		MANIFEST.in
Makefile		Makefile
README.md		README.md
TODOD.txt		TODOD.txt
agentflow.json		agentflow.json
mkdocs.yaml		mkdocs.yaml
plan.md		plan.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

10xHub/agentflow-cli

Folders and files

Latest commit

History

Repository files navigation