Waxell CLI (wax)

The wax CLI is the primary developer interface to Waxell. It ships with the waxell SDK and lets you authenticate, deploy agents, explore execution runs and traces, manage governance, and configure everything about your tenant from the terminal.

wax login          # authenticate
wax push           # deploy agents from waxell.yaml
wax runs           # browse execution runs
wax traces         # explore distributed traces

Run wax --help for the full command tree, or wax <command> --help for options on any command.

Installation

The wax CLI ships with the waxell package on PyPI. It requires Python 3.10–3.14.

pipx (recommended for CLI use)

pipx installs waxell into an isolated environment and puts wax on your PATH without polluting your global or project Python. This is the most reliable way to get the CLI.

pipx install waxell

If you don't have pipx yet:

python3 -m pip install --user pipx
python3 -m pipx ensurepath      # adds pipx's bin dir to your PATH
# open a new terminal so the PATH change takes effect

pip (when you also want the Python library)

Use pip if you want to import the SDK in the same environment — ideally inside a virtual environment:

python3 -m venv .venv && source .venv/bin/activate
pip install waxell

Framework adapters (optional)

Install extras to bring in adapters for a specific agent framework:

pipx install "waxell[langgraph]"     # or: crewai, pydantic-ai, autogen, claude-sdk
pipx install "waxell[all]"           # every framework adapter

Verify and upgrade

wax --version                  # confirm the CLI is on your PATH
wax --help                     # see the full command tree

pipx upgrade waxell            # if installed with pipx
pip install --upgrade waxell   # if installed with pip

Troubleshooting installation

wax: command not found after install

The package installed but its script directory isn't on your PATH.

• pipx: run python3 -m pipx ensurepath, then open a new terminal.
• pip (--user): the script lands in your user base bin dir. Find it with python3 -m site --user-base (the binary is in the bin subfolder on macOS/Linux, Scripts on Windows) and add that to your PATH.
• As a fallback, you can always invoke it as a module: python3 -m waxell_sdk.cli --help.

error: externally-managed-environment (PEP 668)

Newer system/Homebrew Python installs block global pip install. This is exactly the case pipx is built for — use pipx install waxell instead, or install into a virtual environment (python3 -m venv .venv && source .venv/bin/activate && pip install waxell). Avoid pip install --break-system-packages.

Wrong Python version / requires-python error

waxell needs Python 3.10–3.14. Check with python3 --version. If your default Python is too old or too new, point pipx at a supported interpreter: pipx install --python python3.12 waxell.

Installed, but wax --version shows an old version

You likely have two copies (e.g. a pip install shadowing a pipx one). Run which -a wax (macOS/Linux) or where wax (Windows) to see every wax on your PATH, then remove the stale one — pip uninstall waxell and/or pipx uninstall waxell — and reinstall via a single method.

SSL / corporate proxy errors during install

Behind a proxy, set HTTPS_PROXY (and HTTP_PROXY) before installing. If your network does TLS interception, point pip at your corporate CA bundle with pip install --cert /path/to/ca-bundle.pem waxell or the PIP_CERT env var.

Still stuck? wax doctor runs a full health check (auth, config, connectivity) and repairs common breakage once the CLI is on your PATH.

Authentication

Interactive login

wax login                      # production (default → api.waxell.dev)
wax login --profile staging    # save credentials under a named profile
wax login --local              # local dev server (localhost:8001)
wax login --url https://...    # custom API URL

wax login prompts for an API key (get one from app.waxell.dev/settings/api-keys), validates it against the server, and writes it to ~/.waxell/config under the chosen profile. Profiles never overwrite each other, so you can keep prod, staging, and local credentials side by side.

Configuration without a browser

If you already have an API key, scaffold the config directly — no login flow:

wax config init                       # interactive prompts
wax config init --no-input            # scaffold an empty profile, fill key later
wax config set api_key wax_sk_...     # set a value individually
wax whoami                            # verify you're authenticated

Profiles

A profile is a named [section] in ~/.waxell/config holding an API URL and key. Select one for any command with --profile / -p:

wax -p staging whoami
wax -p staging runs
wax config profiles                   # list all configured profiles

tip

By convention, [default] is reserved for developers; installers write a [connect] profile plus per-tool sections. Pushing agents should always use an explicit profile (wax -p acme_local push) rather than --local, so the correct domain_url is registered.

Global flags

These apply to every command (place them before the subcommand):

Flag	Description
--profile / -p <name>	Config profile to use
--local	Use the local dev server (localhost:8001)
--version	Print the wax version and exit

Environment variables

Variable	Description
WAX_API_KEY / WAXELL_API_KEY	API key (overrides config file)
WAX_API_URL / WAXELL_API_URL	API URL (overrides config file)

Configuration precedence: --profile flag → ~/.waxell/config → environment variables.

Command catalog

wax --help groups commands into the same sections shown below. Run wax <command> --help for full options on any command.

Core

Command	Description
wax login	Authenticate with Waxell and save your API key
wax whoami	Show the current authenticated user and tenant
wax doctor	Run every health check and repair common breakage

Observability

Command	Description
wax agents	Manage and monitor deployed agents
wax runs	Browse, inspect, and tail agent execution runs
wax llm-calls	LLM call browser and per-model analytics
wax traces	Trace explorer for distributed execution tracing
wax sessions	Session browser and analytics
wax observe-users	User analytics for agent usage
wax errors	Error analysis and diagnostics
wax metrics	Metrics dashboard and analytics
wax costs	Cost analytics and budget tracking
wax lineage	Walk the agent causality graph (runs + edges)

Governance

Command	Description
wax policies	Manage governance policies (list, show, push)
wax kill-switches	Manage kill switches (list, show)
wax budgets	Manage governance budgets (list, show)
wax governance	Governance events, compliance, and policy packs

Agent development

Command	Description
wax push	Auto-discover and deploy agents, tools, workflows, and skills
wax push-tool / push-workflow / push-domain / push-skill	Deploy a single standalone artifact
wax signals	Fire signals at agents and poll for results (fire, show)
wax validate <agent>	Validate an agent's registration and execution readiness
wax context <agent>	Check context-file coverage and quality for an agent
wax test <scenarios>	Run agent eval scenarios
wax dev <path>	Watch an agent directory and re-parse on save
wax export <agent>	Export an agent spec to JSON
wax prompt	Manage tenant-registered prompts
wax mcp	Manage the tenant's outbound MCP server registry
wax claude-init	Install the Waxell Runtime skill for Claude Code

Configuration

Command	Description
wax config	Manage ~/.waxell/config (init, show, set, profiles)
wax keys	Manage API keys (list, create, show, revoke, rotate)
wax secrets	Manage secrets (list, scan, check)
wax llm	LLM configuration (call, routing, models)
wax provider	LLM provider instances, catalog, and capability groups
wax domains	Manage tenant domain configurations
wax sub-user-auth	Manage the per-tenant Ed25519 signing keypair

Organization & identity

Command	Description
wax teams / users / roles	Organization management
wax identities	Identity providers and SSO
wax sub-tenants	Manage sub-tenants
wax end-users / end-user-groups	Waxell end-user identity records
wax billing / wax usage	Billing and usage analytics

Integrations

Command	Description
wax claude-code	Claude Code observability & governance integration
wax cowork	Claude Cowork observability integration
wax guard	Inspect and edit the local-guard config
wax network-monitor	Network-monitor flow uploader (macOS)
wax observe mcp-proxy	Governance proxy for a third-party MCP server

Adapter platform

Command	Description
wax adapter	Inspect adapter capability manifests; bulk-import framework artifacts
wax hub	Inspect the canonical adapter event hub
wax registry	Browse and manage canonical registry artifacts

Deploying agents — wax push

wax push is the workhorse. It auto-discovers a waxell.yaml manifest, packages your agents (plus tools, workflows, skills, and context files), and deploys them to your tenant.

wax push                          # auto-discovers waxell.yaml in cwd
wax push ./projects/finance       # discover waxell.yaml under a path
wax push --dry-run                # validate and show what would push, no upload

Flag	Description
path (positional, optional)	Directory or file to discover and push
--profile <name>	Config profile to push against
--dry-run	Show what would be pushed without uploading
--bundle <name>	Use a pre-approved dependency bundle (e.g. data-science, web-scraping, ai-ml)
--include-source / --no-source	Include source for isolated execution (default: auto-detect from deps)

tip

Always push with an explicit profile: wax -p acme_local push. Using --local keeps the default profile (which has no domain_url), so domains register on the wrong port and 404.

After pushing, activate or manage versions:

wax agents list                   # see all agents + execution metrics
wax agents info <name>            # signals and domain endpoints for an agent
wax agents activate <name>       # draft → active
wax agents pause <name>          # pause without deactivating
wax agents promote <name> --version <v>   # set an existing version as default
wax agents rollback <name> --version <v>  # restore a prior version as a new version

The single-artifact variants (push-tool, push-workflow, push-domain, push-skill) deploy one artifact without a full manifest.

Exploring runs — wax runs

A run is one end-to-end execution of an agent workflow. Each run has a numeric Run ID, an OTel trace_id, and a tree of spans (agent → LLM calls → tool calls). Runs are listed newest-first and filtered by your plan's retention window.

wax runs                                   # last 10 runs in the last 24h
wax runs list --hours 168                  # last week
wax runs list --agent outreach --status error
wax runs show 230 --spans                  # span tree for run 230
wax runs watch --agent my-agent            # tail new runs for one agent
wax runs stats --hours 168                 # aggregate totals + top agents

wax runs list flags:

Flag	Description
--agent <name>	Filter to runs whose agent name contains NAME (case-insensitive)
--status <success|error|running>	Only show runs in this state
--hours <N>	Look back N hours (default 24). Try 168 for a week
--limit <N>	Max rows (default 10; server caps at 100)
--format <table|json>	Pretty table or pipe-friendly JSON

note

runs list returns a Run ID column — pass that to runs show. show also accepts an OTel trace_id or a workflow_id, whichever is easiest to paste. Results are clamped to your tenant's retention window server-side.

Firing signals — wax signals

Signals trigger agents and let you poll or stream the resulting run:

wax signals fire <name> --payload '{"key": "value"}'
wax signals fire <name> --payload-file ./input.json
wax signals show <run_id>                  # inspect a fired run

Validating before you ship — wax validate

wax validate <agent_name>              # check registration + execution readiness
wax validate <agent_name> --verbose    # full diagnostic detail
wax context <agent_name>               # context-file coverage and quality
wax context <agent_name> --fix         # scaffold missing context stubs

Eval harness — wax test

wax test runs scenario-based evals against an agent using the Scenario / Turn / Expect DSL.

wax test ./evals                                  # run every scenario in a dir
wax test ./evals my_scenario                      # run named scenarios only
wax test ./evals --list                           # list scenarios + tags, don't run
wax test ./evals --tag smoke --exclude-tag slow   # filter by tag
wax test ./evals --bail                           # stop on first failure
wax test ./evals -p staging                       # run against a profile (uploads results)

Flag	Description
--tag <t> / --exclude-tag <t>	Include/skip scenarios by tag (repeatable)
--include-expensive	Include scenarios tagged expensive (paid-API hits); off by default
--bail	Stop on the first scenario failure
--list	List discovered scenarios + tags and exit
--report <path>	Where to write the markdown report (default /tmp/waxell-eval/<ts>/report.md)
--profile <name>	~/.waxell/config profile to run against
--trace-url-template <tpl>	Format string for trace links in the report ({trace_id})
--upload / --no-upload	POST results to /v1/evals/runs/ (defaults ON when --profile is set)
--triggered-by <user|schedule|ci>	Run source, used by the eval dashboard for filtering

Configuration commands

wax config init                       # create ~/.waxell/config + first profile
wax config init --no-input            # scaffold without prompts
wax config show                       # print the active config (key masked)
wax config set api_key wax_sk_...     # set api_url | api_key | domain_url
wax config profiles                   # list configured profiles

API keys and secrets:

wax keys list                         # list API keys
wax keys create --name ci-key         # mint a new key
wax keys rotate <key_id>              # rotate a key
wax keys revoke <key_id>              # revoke a key

wax secrets list                      # list tenant secrets (values masked)
wax secrets scan ./my-agents          # scan source for hardcoded secrets
wax secrets check --agent <name>      # verify an agent's required secrets exist

Common workflows

Push and watch an agent

wax -p acme push ./my-agents          # push everything under a directory
wax runs watch --agent my-agent       # tail new runs as they arrive
wax traces                            # open the trace explorer

Set up Claude Code observability

wax claude-code setup                         # install observability hooks
wax claude-code setup --governance            # + PreToolUse policy enforcement
wax claude-code setup --governance --mcp      # + MCP governance tools
wax claude-code status                        # current session state

Diagnose a broken setup

wax doctor                            # runs every health check; repairs common breakage
wax whoami                            # confirm auth + tenant

Next steps

• Installation Guide — get started with Waxell
• Runtime Quickstart — build your first agent
• waxell.yaml Reference — the manifest wax push reads
• Observe Overview — observability for any framework