Commands

All commands support --json for structured output unless noted otherwise. Use levered <command> --help for inline documentation on any command.

Authentication

Manage your session and credentials.

Configuration

Read and write CLI settings stored in ~/.levered/config.json.

Optimizations

Create, manage, and inspect optimizations.

List optimizations

levered optimizations list [--limit N] [--include-archived] [--json]

List optimizations in the current organization. Returns the most recent optimizations, up to --limit (default 10). Archived optimizations are hidden unless --include-archived is set.

Show optimization details

levered optimizations show <id> [--json]

Print full details for a single optimization, including design factors, model configuration, linked metric, and current status.

Create an optimization

levered optimizations create \
  --name NAME \
  --design-factors JSON \
  --reward-metric-id UUID \
  [--model-type cmab] \
  [--context-factors JSON] \
  [--json]

Create a new optimization and start training.

Example. Create a hero section optimization with two design factors:

levered optimizations create \
  --name "Landing Page Hero" \
  --design-factors '[
    {"name": "headline", "levels": ["Ship faster", "Build better", "Scale up", "Go live today", "Start free"]},
    {"name": "cta_text", "levels": ["Get started", "Try it free"]}
  ]' \
  --reward-metric-id 8a3b12c4-5678-4def-abcd-1234567890ab \
  --context-factors '[{"name": "country"}, {"name": "device_type"}]' \
  --json

Update optimization status

levered optimizations update <id> --status {live|completed|archived}

Transition an optimization to a new status. See Optimizations for the status lifecycle.

Archive an optimization

levered optimizations archive <id> [-y]

Archive an optimization. Prompts for confirmation unless -y is passed.

View results

levered optimizations results <id> [--json]

Print performance results for an optimization, including estimated lift over the baseline, confidence intervals, and factor importance rankings.

View progress

levered optimizations progress <id> [--matured-only] [--json]

Show how far along an experiment is: days running (from first measured traffic), enrollment per arm as unique users and converters with the holdout share, and convergence, covering progress to best, P(beats baseline), and the variant the model currently ranks highest with its traffic weight.

Enrollment counts are participant-level (a user exposed or converting multiple times counts once) and come from the measured holdout series; they are not comparable to the bandit's per-event exposure counts shown in results.

View guardrails

levered optimizations guardrails <id> [--matured-only] [--json]

Show each guardrail metric's bandit and holdout rates, the measured lift with its 95% confidence interval and p-value, and whether the guardrail is ok, violated, or still pending data, plus the overall rollup status.

Capture variant screenshots

levered optimizations screenshot <id> --url <page-url> \
  [--selector <css>] [--viewport 1280x800] [--wait-ms 800] \
  [--full-page] [--only 1,4] [--out-dir <dir>] [--no-upload]

Screenshot every servable variant of an optimization against a running app and upload the images to Levered, so each variant shows a visual preview in the dashboard's variants table.

For each variant, the command opens the page in a headless browser, intercepts the SDK's serve call, and forces that variant's factor values, so the page renders exactly what users in that arm see. Point --url at your local dev server (or a staging URL); the page must already be wired up with useVariant for this optimization.

Requires Node.js on PATH. The first run installs a pinned Playwright and downloads the Chromium browser (~130 MB, one-time) into ~/.levered/screenshot-runner/. Disabled and excluded variants are skipped, and re-running overwrites the previous screenshots.

List observations

levered optimizations observations <id> [--page N] [--size N] [--json]

Paginate through the raw observation data (exposures matched to rewards) for an optimization.

Models

Inspect and manage the bandit models behind optimizations.

Warehouse

Inspect and query your data warehouse. Warehouse connections are managed through the dashboard or the API.

These commands are especially useful for AI agents that need to discover table schemas before writing metric SQL.

Metrics

Define reward metrics that tell Levered what counts as a successful outcome.

List metrics

levered metrics list [--json]

Create a metric

levered metrics create \
  --name NAME \
  --sql SQL \
  --anonymous-id-col COL \
  --timestamp-col COL \
  [--value-col COL] \
  [--reward-type TYPE] \
  [--json]

Example. Create a sign-up conversion metric:

levered metrics create \
  --name "Sign-ups (7d)" \
  --sql "SELECT anonymous_id, signed_up_at FROM analytics.sign_ups WHERE signed_up_at >= CURRENT_DATE - 7" \
  --anonymous-id-col anonymous_id \
  --timestamp-col signed_up_at \
  --json

Preview metric data

levered metrics preview <id> [--limit N] [--json]

Run the metric's SQL query and display a sample of matching rows. Useful for verifying the query returns the expected data before linking the metric to an optimization.

Delete a metric

levered metrics delete <id> [-y]

Delete a metric. Prompts for confirmation unless -y is passed. Metrics linked to active optimizations cannot be deleted.

Variant Serving

Request a variant assignment for a user outside of the SDK.

levered serve <optimization-id> [--anonymous-id ID] [--context JSON] [--json]

Returns the selected variant, meaning the set of factor-level assignments, for the given user and context.

Interactive Dashboard

levered dashboard [--refresh SECONDS]

Launch a terminal UI (TUI) that displays live optimization data, including variant distributions, reward rates, and model state. The display refreshes on the interval specified by --refresh (default: 10 seconds).

This is a read-only view. Use it to monitor running optimizations without leaving the terminal.