10xScale Agentflow CLI

10xScale Agentflow CLI turns an Agentflow CompiledGraph into a production-grade FastAPI service, plus a Typer-based command line to scaffold, run, build, test, and evaluate it. You write a graph, point agentflow.json at it, and agentflow api serves it over REST + WebSocket with authentication, rate limiting, media handling, checkpointer/thread management, and a memory store API.

📦 Part of the 10xScale Agentflow library

This package (10xscale-agentflow-cli) is the API server + CLI layer of the larger 10xScale Agentflow framework. The core orchestration engine — StateGraph, Agent, ToolNode, state, persistence, memory, and tools — lives in the separate 10xscale-agentflow package. This CLI builds on top of it to expose your agent graphs as a deployable service.

Core framework: 10xscale-agentflow · source

This package (API + CLI): 10xscale-agentflow-cli

TypeScript client: @10xscale/agentflow-client

Docs: agentflow.10xscale.ai

✨ Key Features

🖥️ Professional CLI - Scaffold, run, build, test, and evaluate agents from one command line
⚡ FastAPI Backend - Your compiled graph auto-served over REST + WebSocket, high-performance and async
🔌 Config-Driven - One agentflow.json wires agent, auth, checkpointer, store, Redis, and rate limits
🔐 Authentication - Built-in JWT auth, custom BaseAuth backends, and RBAC authorization
🚦 Rate Limiting - Sliding-window limits with memory, Redis, or custom backends
🆔 Distributed IDs - Snowflake ID generation for multi-node deployments
🧵 Thread Management - Conversation thread naming, listing, state, and message APIs
🖼️ Multimodal & Media - File upload/download endpoints and media handling for multimodal agents
🎙️ Realtime Audio Bridge - WebSocket endpoint for live audio-to-audio agents (Gemini Live)
🐳 Docker & Kubernetes Ready - Generate production Dockerfiles and compose files with one command
🛡️ Production Hardening - Error/log sanitization, request size limits, security headers, startup validation
💉 Dependency Injection - InjectQ for clean, testable dependency wiring

Installation

Basic installation:

pip install 10xscale-agentflow-cli

Optional extras — install only what you configure:

pip install "10xscale-agentflow-cli[redis]"   # Redis rate-limit / cache backend
pip install "10xscale-agentflow-cli[jwt]"     # JWT authentication
pip install "10xscale-agentflow-cli[media]"   # Document text extraction (multimodal)
pip install "10xscale-agentflow-cli[otel]"    # OpenTelemetry tracing
pip install "10xscale-agentflow-cli[snowflakekit]"  # Snowflake ID generation

Requires Python ≥ 3.12. Depends on the core 10xscale-agentflow framework.

🚀 Quick Start

# 1. Scaffold a project (interactive: dev vs production, auth, rate limiting)
agentflow init

# 2. Start the dev API server (127.0.0.1:8000)
agentflow api

# 3. Or start the server and open the hosted playground
agentflow play

# 4. Generate production Docker files
agentflow build --docker-compose

🖥️ CLI Commands

For detailed command documentation, see the CLI Guide.

`agentflow init`

Initialize a new project with configuration and a sample graph.

agentflow init                  # interactive (chooses dev vs production setup)
agentflow init --path ./my-app  # custom directory
agentflow init --force          # overwrite existing files

`agentflow api`

Start the development API server.

agentflow api                              # defaults (127.0.0.1:8000)
agentflow api --host 127.0.0.1 --port 9000 # custom host/port
agentflow api --config production.json     # custom config file
agentflow api --no-reload                  # disable auto-reload
agentflow api --verbose                    # verbose logging

`agentflow play`

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

agentflow play
agentflow play --host 127.0.0.1 --port 9000
agentflow play --config production.json

`agentflow build`

Generate production Docker files.

agentflow build                            # Dockerfile
agentflow build --docker-compose           # Dockerfile + docker-compose.yml
agentflow build --python-version 3.12 --port 9000
agentflow build --force

`agentflow eval` / `agentflow test`

Run agent evaluations (discovers *_eval.py / eval_*.py, writes HTML + JSON to eval_reports/) and project tests (pytest).

agentflow eval --parallel --threshold 0.8
agentflow test --coverage

`agentflow skills`

Install bundled coding-agent skills (Codex, Claude, GitHub Copilot) into your project so your AI assistant knows how to build with Agentflow.

agentflow skills --all          # install for every supported agent
agentflow skills --agent claude # install for one
agentflow skills --list         # show supported agents

`agentflow version`

Display CLI and package 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,
  "rate_limit": {}
}

Configuration Options

Field	Type	Description
`agent`	string	Path to your compiled agent graph, `"module:attribute"` (required)
`env`	string	Path to environment variables file
`auth`	null \| "jwt" \| object	Authentication configuration
`authorization`	string \| null	Path to an `AuthorizationBackend` (RBAC / per-tool access)
`checkpointer`	string \| null	Path to a custom checkpointer
`injectq`	string \| null	Path to an InjectQ container
`store`	string \| null	Path to a data store
`redis`	string \| null	Redis connection URL
`rate_limit`	object \| null	Sliding-window rate limiting configuration
`thread_name_generator`	string \| null	Path to a custom thread name generator

See the Configuration Guide for complete details.

🔐 Authentication

Agentflow supports multiple authentication strategies. See the Authentication Guide for details.

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:
        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]"

from agentflow_cli import SnowFlakeIdGenerator

generator = SnowFlakeIdGenerator(
    snowflake_epoch=1704067200000,  # Jan 1, 2024
    snowflake_node_id=1,
    snowflake_worker_id=1,
)
new_id = await generator.generate()

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()
# "thoughtful-dialogue", "exploring-ideas", ...

See the Thread Name Generator Guide for custom implementations.

🛡️ Security

Agentflow CLI provides production-grade security features.

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

MODE=production                  # production mode
JWT_SECRET_KEY=<32+ chars>       # strong secret (secrets.token_urlsafe(32))
IS_DEBUG=false                   # disable debug
ORIGINS=https://yourdomain.com   # specific CORS origins (never *)
ALLOWED_HOST=yourdomain.com      # specific allowed hosts (never *)
DOCS_PATH=                       # recommended: disable API docs
REDOCS_PATH=
MAX_REQUEST_SIZE=10485760        # request size limit (10MB default)

For deployment hardening and authentication patterns, see the Deployment Guide and Authentication Guide.

🐳 Deployment

See the Deployment Guide for full instructions.

# Generate Docker files
agentflow build --docker-compose

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

# Check logs
docker compose logs -f

Cloud targets covered in the guide: AWS ECS, Google Cloud Run, Azure Container Instances, Kubernetes, and Heroku.

📁 Project Structure

agentflow-cli/
├── agentflow_cli/          # Main package
│   ├── __init__.py        # Package exports (BaseAuth, SnowFlakeIdGenerator, ThreadNameGenerator)
│   ├── cli/               # Typer CLI: main.py + commands/ + templates/
│   └── src/app/           # FastAPI application (main.py, loader.py, core/, routers/, utils/)
├── docs/                   # Documentation
├── tests/                  # Test suite
├── agentflow.json          # Configuration
├── pyproject.toml          # Project metadata
└── README.md               # This file

🔧 Development

# Clone and set up
git clone https://github.com/10xHub/agentflow-cli.git
cd agentflow-cli
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pre-commit install

# Quality gate
pytest                                # tests (coverage gate: 80%)
pytest --cov=agentflow_cli --cov-report=html
ruff check . && ruff format .         # lint + format
pre-commit run --all-files            # full gate (ruff + bandit, pinned versions)

Using the Makefile

make build     # build sdist + wheel
make test      # run tests
make test-cov  # run tests with coverage
make publish   # upload to PyPI (maintainers)
make clean     # remove build artifacts

Releasing

Releases are cut by pushing a version tag that matches pyproject.toml. The release.yml workflow then verifies the tag, builds the sdist + wheel, checks the distribution metadata, and creates a GitHub Release with auto-generated notes and the artifacts attached. PyPI publishing is manual (make publish).

git tag v0.3.2.9 && git push origin v0.3.2.9

📄 License

MIT License - see LICENSE for details.

🔗 Links & Resources

Documentation - Full framework docs
Core framework (10xscale-agentflow) - The orchestration engine this CLI serves
This repository - Source code and issues
PyPI Project - Package releases
Local docs - CLI, configuration, deployment, auth, rate limiting, IDs, thread names

🙏 Contributing

Contributions are welcome! Fork the repo, create a feature branch, run tests and linting, and open a Pull Request. See the repository for issue reporting and guidelines.

💬 Support

Documentation: agentflow.10xscale.ai and local docs
Issues: GitHub Issues
Repository: GitHub

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 223 Commits
.github/workflows		.github/workflows
.vscode		.vscode
agentflow_cli		agentflow_cli
examples		examples
tests		tests
.coveragerc		.coveragerc
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.python-version		.python-version
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
Makefile		Makefile
README.md		README.md
agentflow.json		agentflow.json
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

10xScale Agentflow CLI

📦 Part of the 10xScale Agentflow library

✨ Key Features

Installation

🚀 Quick Start

🖥️ CLI Commands

agentflow init

agentflow api

agentflow play

agentflow build

agentflow eval / agentflow test

agentflow skills

agentflow version

⚙️ Configuration

Configuration Options

🔐 Authentication

JWT Authentication

Custom Authentication

🆔 ID Generation

🧵 Thread Name Generation

🛡️ Security

Production Security Checklist

🐳 Deployment

📁 Project Structure

🔧 Development

Using the Makefile

Releasing

📄 License

🔗 Links & Resources

🙏 Contributing

💬 Support

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`agentflow init`

`agentflow api`

`agentflow play`

`agentflow build`

`agentflow eval` / `agentflow test`

`agentflow skills`

`agentflow version`

Packages