Reference

uc-bq CLI Reference

Overview

uc-bq has fourteen top-level commands. Four of them (init, install-skill, validate, config) manage setup. Four (schema, query, dry-run, render) are the primitives Claude Code drives while designing a report. The rest (run, run-all, list, history, deck, alarm) operate on reports that already exist.

Commands that execute a BigQuery query perform a dry run first and abort if the estimate exceeds the configured limit. See Cost protection.

Global options

Available on every command.

Flag	Description
`-m, --merchant <id>`	Target a specific merchant, overriding `default_merchant` in the config
`--llm-provider <provider>`	LLM provider override: `anthropic`, `openai`, `grok`, `bedrock`, `gemini`
`-V, --version`	Print the installed package version
`-h, --help`	Print usage for the command

uc-bq install-skill

Copies the Claude Code skill prompt to ~/.claude/skills/uc-bq/SKILL.md. The skill is a markdown prompt, not executable code: it teaches Claude Code UltraCart's BigQuery schema conventions, SQL patterns, ECharts conventions, and the CLI surface below.

Option	Description
`--dry-run`	Report what would be written without writing it
`--uninstall`	Remove the installed skill

uc-bq install-skill --dry-run
uc-bq install-skill
uc-bq install-skill --uninstall

The command is idempotent. Claude Code must be restarted before it picks up a newly installed skill.

uc-bq init

Creates .ultracart-bq.json and tests BigQuery connectivity. Interactive when given no flags, non-interactive when --merchant-id is supplied. Exits with status 1 if the connectivity test fails.

Option	Default	Description
`--merchant-id <id>`		Merchant ID. Supplying it selects non-interactive mode
`--taxonomy <level>`	`standard`	`standard`, `low`, `medium`, or `high`
`--dataset <dataset>`	`ultracart_dw`	BigQuery dataset name
`--output-dir <dir>`	`./reports`	Root directory for generated reports
`--output-format <format>`	`png`	`png`, `pdf`, or `both`

uc-bq init
uc-bq init --merchant-id=DEMO --taxonomy=medium
uc-bq init --merchant-id=DEMO --taxonomy=high --dataset=ultracart_dw --output-dir=./reports --output-format=png

Interactive mode loops over merchants, optionally walks external GCP project registration by listing the datasets and tables it finds, and then writes the config.

uc-bq schema

Reports the schema of UltraCart tables and of any registered external project.

Option	Default	Description
`--list`		List the tables available at your taxonomy level
`--tables <tables>`		Comma-separated table names to describe
`--filter <query>`		Filter columns by keyword, or by LLM when `--api-key` is given
`--api-key <key>`		API key for LLM-backed column filtering
`--format <format>`	`text`	`text` or `json`
`--dataset <dataset>`	configured dataset	Dataset to read
`--project <project>`		Browse any GCP project, without registering it first
`--refresh`		Clear and re-fetch every cached external table schema
`--live`		Read schema from BigQuery, bypassing the bundled enhanced schemas

uc-bq schema --list
uc-bq schema --tables=uc_orders,uc_items
uc-bq schema --tables=uc_orders --filter="revenue,date,category"
uc-bq schema --tables=uc_orders --format=json

uc-bq schema --project=my-marketing-warehouse
uc-bq schema --project=my-marketing-warehouse --dataset=google_ads --list
uc-bq schema --project=my-marketing-warehouse --dataset=google_ads --tables=campaigns

uc-bq schema --refresh

The package ships enhanced schemas containing column descriptions, allowed values, and mandatory flags. Those are preferred over live BigQuery metadata unless --live is passed. External tables are addressed as alias.dataset.table and their schemas are cached under .ultracart-bq-cache/.

Inside Claude Code the skill instructs the model to fetch the full schema as JSON and filter it in context rather than using --filter, which avoids a second model call.

uc-bq query

Executes SQL against BigQuery and prints a sample of the results.

Option	Default	Description
`--file <path>`		Path to a SQL file
`--sql <sql>`		Inline SQL string
`--params <json>`		JSON object of parameter values
`--sample <rows>`	`20`	Rows to display
`--output <path>`		Write the full result set to a JSON file
`--force`		Bypass the cost safety check
`--max-bytes <bytes>`	`10737418240`	Cost limit for this command, in bytes

Supply either --file or --sql, not both.

uc-bq query --file=query.sql --params='{"start_date":"2026-01-01","end_date":"2026-03-28"}'
uc-bq query --sql="SELECT COUNT(*) AS cnt FROM \`ultracart-dw-demo.ultracart_dw.uc_orders\`"
uc-bq query --file=query.sql --params='{"start_date":"2026-01-01"}' --output=data.json
uc-bq query --file=query.sql --params='{"start_date":"2026-01-01"}' --sample=50

The file written by --output is a plain JSON array of row objects, which is the same shape uc-bq render expects for --data.

uc-bq dry-run

Estimates bytes processed and cost without executing the query.

Option	Description
`--file <path>`	Path to a SQL file
`--sql <sql>`	Inline SQL string
`--params <json>`	JSON object of parameter values

uc-bq dry-run --file=query.sql --params='{"start_date":"2026-01-01","end_date":"2026-03-28"}'

#   Estimated bytes processed: 2.4 GB
#   Estimated cost: $0.015

Cost is calculated at BigQuery's on-demand rate of $6.25 per TB.

uc-bq validate

Validates a config file or a report manifest against the bundled JSON Schemas. Exits with status 1 on failure.

Option	Description
`--config`	Validate `.ultracart-bq.json`
`--manifest <path>`	Validate a `report.yaml` manifest

uc-bq validate --config
uc-bq validate --manifest=./reports/DEMO/revenue-by-category/report.yaml

Deck definitions are not covered by validate.

uc-bq render

Renders an ECharts configuration to PNG or PDF using a headless browser.

Option	Default	Description
`--chart <path>`		Path to the `chart.js` file. Required
`--data <path>`		Path to the `data.json` file. Required
`--output <path>`		Output file path
`--width <pixels>`	`1200`	Chart width
`--height <pixels>`	`600`	Chart height
`--format <format>`	`png`	`png` or `pdf`
`--dashboard`		Thumbnail mode, which forces 200x200
`--preview`		Accepted, but not implemented

uc-bq render --chart=chart.js --data=data.json --output=chart.png
uc-bq render --chart=chart.js --data=data.json --output=chart.pdf --format=pdf
uc-bq render --chart=chart.js --data=data.json --output=thumb.png --dashboard
uc-bq render --chart=chart.js --data=data.json --output=chart.png --width=1600 --height=900

warning

--preview is parsed by the CLI but the renderer has no preview path, so a --preview run with no --output writes no file. Always pass --output.

Rendering also needs network access: the render template loads ECharts and the USA map data from a CDN at render time.

uc-bq run

Replays a saved report with fresh data.

Argument: <report-name>, the report directory name under the merchant's report directory. Names containing .., /, or \ are rejected.

Option	Default	Description
`--no-analysis`		Skip executive analysis generation
`--analysis-api-key <key>`		API key for analysis on a headless run
`--analysis-model <model>`	`claude-sonnet-4-5-20250929`	Model used for analysis
`--deliver`		Deliver via Slack and email as configured in the manifest
`--no-deliver`		Skip delivery even when configured
`--skip-alarms`		Skip alarm evaluation
`--landscape`		Produce the PDF in landscape orientation
`--force`		Bypass the cost safety check
`--max-bytes <bytes>`	`10737418240`	Cost limit for this run, in bytes

Parameter values are overridden with extra flags in the form --param_name=value. Only lowercase names with underscores are treated as parameters, so hyphenated flags are never mistaken for one.

uc-bq run revenue-by-category
uc-bq run revenue-by-category --start_date=2026-01-01 --end_date=2026-03-31
uc-bq run revenue-by-category --deliver --no-analysis
uc-bq run revenue-by-category --landscape
uc-bq run revenue-by-category --analysis-api-key=$ANTHROPIC_API_KEY --analysis-model=claude-haiku-4-5-20251001
uc-bq run revenue-by-category --llm-provider=openai --analysis-api-key=$OPENAI_API_KEY

A run resolves parameters, performs the cost dry run, executes the query, writes data.json, renders chart.png and chart-dashboard.png, appends to run_history in report.yaml, evaluates alarms, generates analysis when an API key and an analysis_prompt.md are both present, builds report.pdf, and finally delivers. Analysis is skipped silently when no API key is available.

uc-bq run-all

Replays every report directory containing a report.yaml for the current merchant. Accepts the same options and parameter overrides as run.

uc-bq run-all --start_date=2026-01-01 --end_date=2026-03-31
uc-bq run-all --deliver --no-analysis
uc-bq run-all -m DEMO2

A failing report is reported and skipped rather than aborting the batch. A total bytes and cost summary is printed at the end.

uc-bq list

Lists saved reports for the current merchant. Takes no arguments or options.

uc-bq list

#   Reports for merchant: DEMO
#
#   Name                          Last Run      Description
#   ────────────────────────────────────────────────────────────
#   Revenue by Product Category   2026-03-28    Daily revenue by category
#   Customer Cohort Analysis      2026-03-25    LTV by signup month

uc-bq history

Shows the run history recorded in a report's manifest.

Argument: <report-name>

uc-bq history revenue-by-category

#   Revenue by Product Category - Run History
#
#   Run Date     Parameters                    Rows     Cost
#   ────────────────────────────────────────────────────────────
#   2026-03-28   startdate=2025-12-28  ...     1,247    $0.015
#   2026-03-21   startdate=2025-12-21  ...     1,189    $0.014

The cost column is derived from the bytes recorded for each run at $6.25 per TB.

uc-bq config

Reads and writes .ultracart-bq.json, report manifests, and deck definitions.

warning

Every config subcommand reads and writes the config file in the current working directory. A config in your home directory is loaded at runtime but cannot be edited this way.

Merchants

Command	Arguments and options
`config show`	Print the current configuration
`config add-merchant <id>`	`--taxonomy <level>` required, `--dataset <dataset>` optional
`config remove-merchant <id>`	Refuses to remove the default merchant

uc-bq config show
uc-bq config add-merchant DEMO2 --taxonomy=standard
uc-bq config add-merchant DEMO3 --taxonomy=medium --dataset=ultracart_dw
uc-bq config remove-merchant DEMO2

External projects

Command	Arguments and options
`config add-project <alias>`	`--project-id <id>` required, `--description <desc>` optional
`config remove-project <alias>`
`config add-dataset <alias> <dataset>`	`--discover` adds every table it finds
`config remove-dataset <alias> <dataset>`
`config add-tables <alias> <dataset> <tables...>`
`config remove-tables <alias> <dataset> <tables...>`

uc-bq config add-project marketing --project-id=my-marketing-warehouse --description="Google Ads and Meta"
uc-bq config add-dataset marketing google_ads_data --discover
uc-bq config add-tables marketing meta_ads_data campaigns ad_sets ads
uc-bq config remove-tables marketing meta_ads_data ads

See External data sources for the full workflow.

Delivery

Command	Arguments and options
`config add-slack <report> <channels...>`	Slack channel IDs, not channel names
`config remove-slack <report> <channels...>`
`config set-email <report>`	`--to`, `--provider`, `--subject`, all three required on first use
`config add-email <report> <emails...>`
`config remove-email <report> <emails...>`
`config set-email-provider <report> <provider>`	`sendgrid`, `postmark`, `mailgun`, `resend`, `ses`
`config set-email-subject <report> <subject>`
`config show-delivery <report>`

uc-bq config add-slack revenue-by-category C0123456789 C9876543210
uc-bq config set-email revenue-by-category \
  --to=ceo@example.com,marketing@example.com \
  --provider=sendgrid \
  --subject="Weekly: Revenue by Category"
uc-bq config show-delivery revenue-by-category

Alarms

Command	Arguments and options
`config add-alarm <report>`	See the option table below
`config show-alarms <report>`
`config remove-alarm <report> <alarm-name>`
`config set-delivery-mode <report> <mode>`	`always` or `alarm_only`
`config set-mention-on-alarm <report> <mention>`	For example `@channel` or `@here`

`add-alarm` option	Default	Description
`--name <name>`		Alarm name. Required
`--type <type>`		`threshold`, `pct_change`, or `missing_data`. Required
`--metric <metric>`		Column in `data.json` to evaluate
`--aggregate <agg>`	`sum`	`sum`, `avg`, `min`, `max`, `first`, or `last`
`--operator <op>`		`<`, `>`, `<=`, `>=`, `==`, or `!=`
`--value <value>`		Threshold value, or percent for `pct_change`
`--severity <sev>`	`high`	`low`, `high`, or `critical`
`--cooldown <dur>`	`24h`	For example `24h`, `7d`, `30m`, or `0`

uc-bq config add-alarm revenue-by-category \
  --name "Revenue Drop" \
  --type pct_change \
  --metric total_revenue \
  --aggregate sum \
  --operator "<" \
  --value -20 \
  --severity high \
  --cooldown 24h

uc-bq config set-delivery-mode revenue-by-category alarm_only

Report and deck parameters

Command	Arguments
`config set-param <report> <param> <value>`
`config remove-param <report> <param>`
`config show-params <report>`
`config set-deck-param <deck> <param> <value>`
`config remove-deck-param <deck> <param>`
`config show-deck-params <deck>`
`config set-deck-delivery-mode <deck> <mode>`	`always` or `alarm_only`

uc-bq config set-param revenue-by-category start_date -90d
uc-bq config set-param revenue-by-category end_date today
uc-bq config set-deck-param weekly-executive start_date start_of_year

Values accept the relative date expressions listed in the Configuration reference.

uc-bq deck

Builds and manages report decks.

deck run

Runs every report in a deck and produces one combined PDF.

Argument: <deck-name>, the deck definition name without the .yaml extension.

Option	Default	Description
`--deliver`		Deliver the deck PDF via Slack and email
`--no-analysis`		Skip analysis for the contained reports
`--landscape`		Landscape orientation
`--force`		Bypass the cost safety check
`--analysis-api-key <key>`		API key for analysis
`--analysis-model <model>`	`claude-sonnet-4-5-20250929`	Model used for analysis
`--max-bytes <bytes>`	`10737418240`	Cost limit, in bytes
`--skip-alarms`		Skip alarm evaluation

Parameter overrides use the same --param_name=value form as run.

uc-bq deck run weekly-executive
uc-bq deck run weekly-executive --deliver --no-analysis
uc-bq deck run weekly-executive --start_date=2026-01-01 --end_date=2026-03-31

deck dashboard

Generates a self-contained interactive HTML dashboard from the data already on disk.

Option	Description
`--open`	Open the generated file in the default browser

uc-bq deck dashboard weekly-executive
uc-bq deck dashboard weekly-executive --open

deck list

Lists every deck definition for the current merchant. No options.

uc-bq deck list

deck create

Writes a new deck definition file.

Option	Description
`--title <title>`	Deck title. Required
`--reports <reports>`	Comma-separated report directory names. Required
`--company <company>`	Company name for the cover page
`--logo-url <url>`	Logo URL for the cover page
`--landscape`	Landscape orientation
`--params <params>`	Comma-separated `param=value` pairs

uc-bq deck create weekly-executive \
  --title="Weekly Executive Briefing" \
  --reports=revenue-by-category,top-products,customer-ltv \
  --company="DEMO Commerce Inc." \
  --logo-url="https://example.com/logo.png" \
  --landscape \
  --params="start_date=start_of_year,end_date=today"

warning

deck create is not interactive. Without both --title and --reports it prints the available reports and exits with status 1. The name field written into the file is taken from --title, not from the deck file name.

uc-bq alarm

Inspects alarms without running a query.

Command	Description
`alarm test <report-name>`	Evaluate the report's alarms against the existing `data.json`, with no query and no delivery
`alarm history <report-name>`	Print the metric history and active suppressions from `alarm_state.json`

uc-bq alarm test revenue-by-category
uc-bq alarm history revenue-by-category

Configuration reference - config file fields, date expressions, environment variables
Getting started - install and first report
Report delivery - what --deliver needs to be configured first
Report alarms - what the alarm subcommands operate on
Troubleshooting - error messages from these commands

Was this page helpful?

Overview​

Global options​

uc-bq install-skill​

uc-bq init​

uc-bq schema​

uc-bq query​

uc-bq dry-run​

uc-bq validate​

uc-bq render​

uc-bq run​

uc-bq run-all​

uc-bq list​

uc-bq history​

uc-bq config​

Merchants​

External projects​

Delivery​

Alarms​

Report and deck parameters​

uc-bq deck​

deck run​

deck dashboard​

deck list​

deck create​

uc-bq alarm​

Related Documentation​

Overview

Global options

uc-bq install-skill

uc-bq init

uc-bq schema

uc-bq query

uc-bq dry-run

uc-bq validate

uc-bq render

uc-bq run

uc-bq run-all

uc-bq list

uc-bq history

uc-bq config

Merchants

External projects

Delivery

Alarms

Report and deck parameters

uc-bq deck

deck run

deck dashboard

deck list

deck create

uc-bq alarm

Related Documentation