10xScale Agentflow CLI

Agentflow is now 10xGraph. 0.6.0 is the final release of 10xscale-agentflow-cli on PyPI. The API server and CLI continue as 10xgraph-api (pip install 10xgraph-api). See 10xgraph.com and github.com/10xGraph. Existing installs keep working. See Moving to 10xGraph below.

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

🔀 Moving to 10xGraph

The project is renamed to 10xGraph (by 10xScale) because "Agentflow" is shared by several unrelated projects and was hard to find. The server, CLI, license and maintainers stay the same.

What changes

What happens to this package

• 0.6.0 is the last version of 10xscale-agentflow-cli. No further releases, fixes or security patches will be published under this name.
• Installed copies keep working. Pin 10xscale-agentflow-cli==0.6.0 if you cannot migrate yet.
• This release depends on 10xscale-agentflow (>=0.10.0), the final release of the old core. Do not install 10xgraph in the same environment: both provide the agentflow module and must not be installed side by side.
• Your agentflow.json and graph code carry over.

How to migrate

pip uninstall 10xscale-agentflow-cli 10xscale-agentflow
pip install 10xgraph-api

✨ 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 local development server and open the playground (127.0.0.1:8000)
agentflow dev

# 3. Check the environment if anything looks wrong
agentflow audit

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

agentflow api (server only) and agentflow play (server + playground) remain available; dev is the goal-oriented wrapper around them.

🖥️ CLI Commands

Run agentflow --help or agentflow COMMAND --help for the generated command reference.

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 init --path ./my-app --name MyAgent --template quick-start \
  --non-interactive            # reproducible CI/agent workflow
agentflow init --path ./my-app --template production --auth jwt \
  --rate-limit redis --yes --dry-run

agentflow dev

Start the development API server and open the hosted playground when it is ready.

agentflow dev                              # defaults (127.0.0.1:8000)
agentflow dev --host 127.0.0.1 --port 9000 # custom host/port
agentflow dev --config production.json     # custom config file
agentflow dev --no-open --no-reload        # API only, without auto-reload

agentflow api and agentflow play remain available as compatibility commands.

Adaptive and structured output

agentflow play                         # full-screen surface in an interactive terminal
agentflow demo                         # preview every animation theme safely
agentflow demo --style build           # one theme: typing, network, init, build, or eval
agentflow --no-fullscreen play         # keep output in your normal scrollback
agentflow --no-animation play          # accessible/static workflow
agentflow --format plain --no-color audit
agentflow --format jsonl eval --parallel
agentflow --quiet build
agentflow --cwd ../my-agent dev

On an interactive terminal a command runs on its own full-screen surface: a pinned header (identity, version, subtitle), a pinned footer status bar, and the command's output scrolling between them. The intro reveals the Agentflow wordmark on the full canvas and collapses into that header, and each command shows its own pipeline — play/dev config→runtime→server→playground, init template→graph→config→project, build source→deps→image→ship, eval discover→load→score→report, audit python→core→config→port.

The surface is held until you press Enter, so a fast command cannot erase its own result. Pass --no-fullscreen (or set AGENTFLOW_NO_FULLSCREEN=1) to keep everything in your normal scrollback instead — useful when you want to scroll back or copy a path afterwards.

Long-running work reports through a live step timeline: stages are declared up front, pending ones stay dimmed, and the running one animates with an elapsed timer. agentflow eval uses a determinate progress bar with a running pass/fail tally.

Motion is disabled automatically for redirected output, CI, TERM=dumb, JSON/JSONL, and AGENTFLOW_NO_SPINNER=1. Use --no-animation for a stable screen-reader friendly experience, or --animation to force motion in a compatible terminal. Every animated surface has a plain line-per-transition renderer and a versioned JSON/JSONL event renderer.

agentflow build

Generate production Docker files.

agentflow build                            # Dockerfile
agentflow build --docker-compose           # Dockerfile + docker-compose.yml
agentflow build --k8s                      # Dockerfile + k8s.yaml (Deployment + Service)
agentflow build --python-version 3.12 --port 9000
agentflow build --service-name my-agent    # name used in docker-compose.yml / k8s.yaml
agentflow build --force                    # overwrite an existing Dockerfile

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                # pick agents interactively (space toggles, enter confirms)
agentflow skills --all          # install for every supported agent
agentflow skills --agent claude # install for one
agentflow skills --list         # show supported agents
agentflow skills --force        # overwrite an existing install
agentflow skills --validate ./.agents/skills  # check skills against the Agent Skills spec

Run without flags to get a checklist of the supported agents. Each row shows where it installs, agents that are already set up are labelled and pre-checked, and picking one that exists offers to overwrite rather than failing.

agentflow version

Display CLI and package version information.

agentflow --version            # script-friendly CLI version only
agentflow version

agentflow audit

Read-only check of everything that has to be true before dev, eval, or build can work here: the Python interpreter, the installed 10xscale-agentflow-cli and 10xscale-agentflow packages, whether the installed core still exposes the evaluation API this CLI imports, whether agentflow.json is present and declares a valid agent key, and whether the default port is free.

agentflow audit                    # table of six checks
agentflow --format json audit      # machine-readable, for CI
agentflow --no-animation audit     # static output

Nothing is written or changed. It exits 1 if any check fails and 0 otherwise — warnings (no project config, port already bound) are reported without failing the run — so it works as a CI gate.

agentflow config

Open a local browser editor for agentflow.json: switch optional sections (auth, authorization, rate limiting, observability, ...) on or off, fill in their fields, Validate without saving, and Save to write the file. Saving is blocked while there are errors, and the previous file is kept as agentflow.json.bak.

agentflow config                           # edit ./agentflow.json
agentflow config -c path/to/agentflow.json --port 8765 --no-open

agentflow demo

Preview the terminal animations and progress states without touching project state.

agentflow demo                  # every theme
agentflow demo --style eval     # one of: typing, network, init, build, eval

⚙️ 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,
  "remote_tools": [],
  "redis": null,
  "thread_name_generator": null,
  "rate_limit": {}
}

Configuration Options

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

Agentflow is MIT licensed and made by 10xScale. Contributions are accepted under the same license.

🔗 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 (final release: 0.6.0)
• 10xGraph and github.com/10xGraph - Where development continues
• 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. New projects should start on 10xGraph.

Made with ❤️ for the AI agent development community