CLI reference
In shortEvery 10xGraph CLI command with its purpose, usage line, options and defaults: init, dev, build, eval, test, skills, audit, config, demo and version.
- 9 min read
- 14 sections
- Updated
- v1.0.0
- Markdown
The 10xgraph command ships with the 10xgraph-api package. It has ten subcommands: init, dev, build, eval, test, skills, audit, config, demo and version. Global options go before the subcommand, and -h or --help works everywhere.
Global options
Placed before the subcommand, for example 10xgraph --no-color build.
| Option | Default | Purpose |
|---|---|---|
--format |
human |
Output format: human, plain, json or jsonl |
--json |
off | Shorthand for --format json |
--color |
auto |
Color policy: auto, always or never |
--no-color |
off | Shorthand for --color never |
--progress |
auto |
Progress mode: auto, tty, plain, json or quiet |
--animation / --no-animation |
on for an interactive terminal | Play the command intro. --no-animation prints a static header instead |
--fullscreen / --no-fullscreen |
off | Pin a header and footer on a full-screen surface. TENXGRAPH_FULLSCREEN=1 turns it on |
--cwd |
current directory | Run as if started in this directory (must exist) |
--verbose, -v |
0 | Increase diagnostics, repeatable |
--quiet, -q |
off | Suppress informational and success output |
--debug |
off | Enable debug diagnostics |
--yes, -y |
off | Accept recommended defaults |
--non-interactive |
off | Never prompt |
--version, -V |
Print the CLI version and exit |
--json cannot be combined with a different --format, and --no-color cannot be combined with a different --color.
On an interactive terminal each command opens with a short intro, under a second, that shows the CLI, core and Python versions and then leaves a one-line header in your scrollback. Press any key to skip it, or Ctrl+C to quit at once. Nothing waits for Enter unless you opted into --fullscreen.
Wherever a command takes --config with the default 10xgraph.json, it uses agentflow.json from the same directory when 10xgraph.json is missing. 10xgraph dev flags the old name in its startup output.
init
Scaffold a new agent project. Interactive init asks three questions: the agent name, the setup (Quick or Full) and the AI provider. Everything else comes from the setup.
10xgraph init [--path DIR] [--mode quick|full] [options]Quick writes a minimal config with auth off and no cache_store.
Full writes the recommended setup without asking:
"auth": "jwt""id_generator": "uuid""cache_store"with"type": "redis"(nourl, so Redis comes fromREDIS_URL), arate_limitof 100 requests per 60 seconds by user withfail_openfalse, andtoken_revocationon- WebSocket and AG-UI off
The summary lists these choices, and the next steps point to 10xgraph config for full control (WebSocket, AG-UI, ID generator, thread naming and every other setting).
The flags are overrides for scripts:
| Option | Default | Purpose |
|---|---|---|
--path, -p |
. |
Directory to initialize |
--force, -f |
off | Overwrite existing files |
--name |
inferred | Agent name, required only when it cannot be inferred |
--mode |
prompt | quick or full. --template quick-start|production is an alias |
--provider |
prompt | google, openai or anthropic |
--auth |
jwt |
Full only: none, jwt or custom |
--cache-store |
redis |
Full only: memory or redis |
--rate-limit / --no-rate-limit |
on | Full only: add or leave out cache_store.rate_limit |
--token-revocation / --no-token-revocation |
on with auth | Full only: add or leave out cache_store.token_revocation. Ignored with --auth none |
--websocket / --no-websocket |
off | Write websocket.enabled |
--yes, -y |
off | Accept the defaults without prompting |
--non-interactive |
off | Fail instead of prompting |
--dry-run |
off | Preview without writing files |
Quick ignores --auth, --cache-store, --rate-limit and --token-revocation. Example for a script:
10xgraph init --yes --mode full --name shop-support --provider openai --cache-store redisdev
Start the local development server (Uvicorn) and open the hosted playground when the API is ready. Use --no-open to serve only.
10xgraph dev [--config FILE] [--host HOST] [--port PORT] [--open | --no-open]| Option | Default | Purpose |
|---|---|---|
--config, -c |
10xgraph.json |
Config file |
--host, -H |
127.0.0.1 |
Bind address. Use 0.0.0.0 for all interfaces |
--port, -p |
8000 |
Port |
--reload / --no-reload |
on | Reload on file changes |
--open / --no-open |
on | Open the hosted playground when the API is ready |
--verbose, -v / --quiet, -q |
off | Logging level |
With MODE=production set, dev prints a warning if you also use --reload, or bind to a host other than loopback (127.0.0.1, localhost, ::1): the dev server has no TLS and is not meant for a real deployment.
dev is the only server command. 10xgraph api and 10xgraph play were removed before 1.0. For production, run Gunicorn in the image that 10xgraph build generates.
build
Generate deployment files. See Deploy with Docker and Kubernetes.
10xgraph build [--docker-compose] [--k8s] [options]| Option | Default | Purpose |
|---|---|---|
--output, -o |
Dockerfile |
Dockerfile path |
--force, -f |
off | Overwrite existing files |
--python-version |
3.13 |
Python version of the base image. The minimum is 3.12; an older version is refused |
--port, -p |
8000 |
Port to expose |
--docker-compose / --no-docker-compose |
off | Also write docker-compose.yml, omit CMD from the Dockerfile |
--k8s / --no-k8s |
off | Also write k8s.yaml |
--service-name |
10xgraph-api |
Service name in generated files |
--worker / --no-worker |
asked | Include a background worker. Needs a non-memory worker key in 10xgraph.json |
--scheduler / --no-scheduler |
off | Include the scheduler. Needs the worker |
--verbose, -v / --quiet, -q |
off | Logging level |
--docker-compose and --k8s cannot be combined: the compose image has no start command, so the pod would crash-loop. The command refuses and exits with an error. Run build once with --k8s, or once with --docker-compose.
At an interactive terminal, build asks where you will deploy, whether to run a worker and the scheduler, and whether to overwrite existing files. See Questions and background jobs.
eval
Run agent evaluations. Discovers *_eval.py and eval_*.py files in the target directory (default evals/) and runs their cases.
10xgraph eval [TARGET] [--threshold 0.8] [--parallel]| Option | Default | Purpose |
|---|---|---|
TARGET |
evals/ |
File or directory to evaluate |
--output, -o |
eval_reports |
Report directory |
--no-report |
off | Console summary only |
--threshold, -t |
unset | Fail if the overall pass rate is below this value (0.0 to 1.0) |
--parallel, -p |
off | Run all cases from all files concurrently |
--max-concurrency, -c |
4 |
Concurrent cases when --parallel is set |
--open / --no-open |
open | Open the HTML report in your browser when the run ends. Skipped with --no-report, -q, --format json/jsonl, --non-interactive, when CI is set, or when stdout is not a terminal |
--verbose, -v / --quiet, -q |
off | Output level |
Reports are HTML and JSON unless --no-report is set. When an option is left at its default, the evaluation block of 10xgraph.json can supply directory, output_dir, threshold, parallel and max_concurrency.
test
Run the project tests with pytest.
10xgraph test [PATH] [--coverage] [-k EXPR] [-- PYTEST_ARGS]| Option | Default | Purpose |
|---|---|---|
PATH |
pytest discovery | Test file or directory |
--coverage, -C |
off | Run with coverage (--cov=., terminal and HTML reports) |
--html |
off | Open the HTML coverage report (needs --coverage) |
-k |
unset | Only run tests matching this expression |
--verbose, -v / --quiet, -q |
off | Output level |
Extra arguments are forwarded to pytest. The test block of 10xgraph.json can set path, coverage and coverage_threshold. An explicit PATH wins over the config.
skills
Install the bundled coding-agent skill, or validate skills.
10xgraph skills [--agent codex|claude|github] [--all] [--list]| Option | Default | Purpose |
|---|---|---|
--agent, -a |
prompt | Target: codex, claude, github, or menu number 1, 2, 3 |
--all |
off | Install for every supported agent |
--list, -l |
off | List supported agents and exit |
--path, -p |
. |
Project directory to install into |
--force, -f |
off | Overwrite an existing installed skill |
--validate |
unset | Validate a skill directory or folder of them against the Agent Skills spec. Repeatable |
--verbose, -v / --quiet, -q |
off | Logging level |
Install locations: .agents/skills/10xgraph plus a 10xGraph section in AGENTS.md (Codex), .claude/skills/10xgraph plus a section in CLAUDE.md (Claude), and .github/skills/10xgraph plus .github/instructions/10xgraph.instructions.md (GitHub).
audit
Read-only environment check: Python version, installed packages, core evaluation API, 10xgraph.json validity, a security check, an audit log check and whether the default port is free. The security check reads only the JSON file and reports production-readiness gaps (auth, rate limiting, token revocation) as warnings; they never fail the command. With MODE=production, the audit log check warns when audit.enabled is not true (see Audit log). Exits 1 if any check fails, so it works as a CI gate.
10xgraph audit [--config FILE]| Option | Default | Purpose |
|---|---|---|
--config, -c |
10xgraph.json |
Config file to validate |
--verbose, -v / --quiet, -q |
off | Logging level |
revoke
Revoke one token or all of a user’s tokens. It builds the configured cache store the same way the server does (cache_store) and writes to it, so with a shared store the revocation reaches every worker at once and the server needs no restart. Turn the check on with "token_revocation": true inside cache_store in 10xgraph.json. The command refuses with an error when the cache store is InMemoryCacheStore, because a separate process cannot reach another process’s memory.
10xgraph revoke (--user USER_ID | --jti JTI) [--before EPOCH] [--expires-at EPOCH] [--redis-url URL] [--config FILE]| Option | Default | Purpose |
|---|---|---|
--user |
unset | Revoke all tokens of this user_id issued so far (log out everywhere) |
--jti |
unset | Revoke the one token with this jti claim |
--before |
unset | With --user: revoke tokens issued at or before this epoch time |
--expires-at |
unset | With --jti: the token’s exp (epoch seconds), to drop the entry |
--redis-url |
unset | Redis URL to write to, in place of the configured cache store |
--config, -c |
10xgraph.json |
Config file |
Pass exactly one of --user and --jti. With no shared cache store configured (cache_store absent or type memory) and no --redis-url, the command fails.
config
Edit and validate 10xgraph.json in a browser UI. The file is created on first save. If only agentflow.json exists, the editor starts from its contents and saving writes them to 10xgraph.json, leaving agentflow.json untouched.
10xgraph config [--config FILE] [--port PORT] [--no-open]| Option | Default | Purpose |
|---|---|---|
--config, -c |
10xgraph.json |
File to edit |
--port, -p |
0 (any free port) |
Editor port |
--open / --no-open |
on | Open the default browser |
The editor groups every key in a sidebar:
| Group | Pages |
|---|---|
| Get running | Core |
| Before production | Auth, Cache store (rate limiting, token revocation), Observability |
| Runs and streaming | Runs, WebSocket, AG-UI, Remote tools, Media |
| Project wiring | Checkpointer, ID generation, Thread naming, Memory store, Dependency injection |
| Developer tools | Test, Evaluation |
The Cache store page starts with three type cards (Memory, Redis, Custom). Under them, the Rate limiting and Token revocation tabs each have an on/off switch and the fields for that setting. The editor validates with the same parsers as the server and writes a .bak of the previous file on save.
demo
Preview terminal animations without touching the project.
10xgraph demo [--style all|typing|network|init|build|eval]| Option | Default | Purpose |
|---|---|---|
--style |
all |
Animation theme |
version
Print the CLI and core framework versions.
10xgraph versionAccepts --verbose and --quiet.
Exit codes
Commands exit 0 on success and non-zero on failure. Ctrl+C exits 130. 10xgraph test returns the pytest exit code.
Frequently asked questions
- What happened to the api and play commands?
- Both were removed before 1.0. Use dev, which starts the Uvicorn development server and opens the hosted playground by default; add --no-open to serve only. dev is not meant for production, so use build and Gunicorn there.