exp

exp [options]exp run [project] [options]exp login [--root dir]exp build project [-t path] [options]exp optimize router|model project [options]exp config subcommand ...

exp is the command-line interface of Experiential (PyPI package experiential). It starts a local OpenAI-compatible (and Anthropic Messages) model gateway on loopback, controls which identities may call which model aliases and how much they may spend, and can turn production agent traces into a fitted router or a fine-tuned model.With no subcommand, an interactive terminal opens the branded home screen (Run Gateway is first). A non-interactive terminal starts the default gateway. First-run setup persists provider connections, creates one initial alias and identity, and prints a one-time virtual key as EXP_GATEWAY_URL and EXP_GATEWAY_KEY before readiness is checked, so the key remains available even if a provider route is not ready. Those names are used so an upstream OPENAI_API_KEY is not overwritten.The compiled exp-gateway-native data plane serves Chat Completions, Responses, and Anthropic Messages. Startup makes no provider call. The gateway writes no prompts, responses, tool arguments, raw keys, or provider secrets to SQLite. GET /usage and GET /usage.json expose content-free counts, tokens, latency, and estimated cost.Paid commands (build, optimize router, optimize model) share one cost-authorization policy: an estimate at or below 50% of the command budget runs automatically; up to the budget needs confirmation or --yes; above the budget fails closed unless an interactive override is given. --yes never raises the ceiling.A hosted gateway with the same wire protocol is available at https://api.experientiallabs.ai/v1. The CLI can also load a fitted project router from Python (`import exp`).

--root dir

Local .exp project root (default .exp in the current directory). Shared by every subcommand.

With no subcommand: expose one frozen project as the gateway's project-backed alias.

Exact frozen policy used with --project (or exp run --policy). Requires a project.

Loopback TCP port (default 8000). The data plane binds 127.0.0.1 only.

Validate gateway readiness and exit without binding.

Versioned JSON receipt (or JSON error) instead of the branded banner.

Never open first-run prompts. An uninitialized gateway exits 2 with gateway_not_initialized and the exact next commands.

Compatibility flag for a project-backed alias: project journals stay off while gateway accounting stays on. Requires a project.

Drain admitted work on shutdown (default 10).

Concurrent admission cap (default 1024).

Show help. Each subcommand also accepts --help.

.exp/

Default project root (--root). Holds settings.toml, models.toml, gateway SQLite, and project artifacts.

Telemetry preference and optional maximum_cost_usd command budget.

Secret-free provider connections and model aliases. Catalogs store an environment-variable name, never a raw key.

Linux user-data credential store (mode 0600). Process environment values override the store without rewriting it. Bedrock uses the AWS credential chain.

run [project]

Start the local gateway directly. Optional project becomes one project-backed alias. Same flags as the root command (--root, --port, --check, --json, --non-interactive, --ghost, --policy).

Open the Experiential Cloud Platform browser approval flow, save the organization key, and synchronize hosted model identities into .exp/models.toml. If a browser cannot be opened, paste a key at the hidden prompt.

Build a grounded world model from a local trace export. Bare exp build project (no -t) is the interactive wizard. Automation needs -t/--traces path. --source names the export format (default otlp; also braintrust, chat-json, langfuse, langsmith, mastra, otel-genai, phoenix, posthog). --dry-run prints preflight with no provider calls. --yes confirms an in-budget estimate. --max-build-cost-usd is the embedding spend ceiling (default 5.00). Repeatable --provider skips the opening list during setup (experiential-cloud, openai, anthropic, gemini, openrouter, openai-compatible, azure, bedrock).

Fit a frozen router from a completed build and verify held-out evidence.

Preflight bounded managed Tinker SFT from routed interactions (optional extra experiential[sft]).

Show or set the per-command cost ceiling (default $50.00). Stored in .exp/settings.toml.

Anonymous aggregate PostHog product telemetry (on by default). Never includes prompts, traces, paths, model names, or credentials.

Author secret-free provider connections, aliases, and build roles (world_model, judge, embedder). Interactive setup can paste keys into the user-data store.

Explicit gateway authoring without optimizer roles: init, status, provider, identity, alias, grant, key, usage, plus caller helpers call, models, and key check. Use --non-interactive --json in scripts.

Set up or manually calibrate a project judge.

Requires Python 3.12+. The console script is exp, which collides with other tools that have used that name (the old Expo CLI, now expo; DVC's dvc exp; unrelated PyPI packages). Install experiential, not a package named exp.The gateway listens on 127.0.0.1 only. First-run virtual-key material is shown once; if it was not saved, issue a replacement with exp config gateway key issue identity --key-id key --json. Human key issuance on a non-terminal requires --json or --output.Anonymous product telemetry is enabled by default; disable it with exp config telemetry disable. build --dry-run and exact completed-build replay make zero paid provider calls.

Experiential is developed by Experiential Labs (Apache-2.0; copyright 2026). PyPI package version 0.6.1 as of 2026-08-28. The CLI is a Typer app whose help text is "Build grounded simulations, optimize model use, and serve routers locally."

llm(1), ollama(1), aider(1), claude(1), curl(1), python(1)

Source code · Homepage · Documentation