Skip to main content
Tutorial

Getting Started with the uc-bq CLI

Overview​

By the end of this page you will have the uc-bq command installed, a working connection to your UltraCart BigQuery data warehouse, and one report on disk that you can re-run at any time.

The work splits into four short stages: install the package, authenticate with Google Cloud, point the CLI at your merchant account, and ask Claude Code for a report. Budget about fifteen minutes for the first three, most of which is waiting on downloads.

If you would rather not do any of it by hand, skip to Let Claude Code install it for you.

Before you begin​

You need three pieces of software and two kinds of access.

Node.js 24 or later. Check with node --version. If you use nvm, run nvm install 24. Otherwise download it from nodejs.org. Earlier versions are rejected by the package.

The Google Cloud CLI (gcloud). On macOS, brew install google-cloud-sdk. On Debian or Ubuntu, sudo apt-get install google-cloud-cli. On Windows, use the installer at cloud.google.com/sdk/docs/install.

Claude Code. Only needed while you are designing reports. Replaying an existing report never calls it. Installation instructions are at claude.com/claude-code.

Data Warehouse (BigQuery) enabled on your merchant account. If you are not sure whether it is on, see Data Warehouse (BigQuery). Contact UltraCart support to enable it.

A Google account registered with UltraCart. UltraCart provisions BigQuery access per Google account and assigns it a taxonomy level, which controls how much customer detail you can read. Your UltraCart administrator does this from Providing Users Access to the Data Warehouse. Your warehouse lives in a Google Cloud project named ultracart-dw-{merchantid}.

Install the CLI and the skill​

Install the package globally so uc-bq is on your path everywhere:

npm install -g @ultracart/bq-skill

A local install works too, in which case prefix every command with npx, as in npx uc-bq init.

warning

If your ~/.npmrc maps the @ultracart scope to GitHub Packages, this install fails, because the package is published to the public npm registry. Point the single command at the public registry instead:

npm install -g @ultracart/bq-skill --registry=https://registry.npmjs.org

The same file's ignore-scripts=true setting, if you have one, stops Puppeteer from downloading the headless browser that renders charts. Fix that with npx puppeteer browsers install chrome. See Troubleshooting for both.

Confirm the install:

uc-bq --version

Now install the skill prompt that teaches Claude Code how to use the CLI:

uc-bq install-skill

This writes ~/.claude/skills/uc-bq/SKILL.md. Restart Claude Code afterwards so it picks the skill up. Run uc-bq install-skill --dry-run first if you want to see what it would write, and uc-bq install-skill --uninstall to remove it later.

Authenticate with Google Cloud​

The CLI reads Google Cloud Application Default Credentials. You authenticate once per machine and the BigQuery client finds the credentials on its own, so no keys end up in your reports or your repository.

Sign in with the Google account that UltraCart registered:

gcloud auth login

Then create the application default credentials the BigQuery client looks for:

gcloud auth application-default login

Both open a browser. The credentials persist across terminal sessions, so this is a one-time step. To undo it later, run gcloud auth application-default revoke.

For scheduled and CI runs, where no browser exists, use a service account instead. That path is covered in Scheduling and automation.

Configure your merchant​

Run the interactive setup:

uc-bq init

It asks for your merchant ID, your taxonomy level, which dataset to read, where to write reports, and what image format to produce. It then writes .ultracart-bq.json in the current directory and immediately tests the BigQuery connection, so a mistake surfaces here rather than halfway through your first report.

The BigQuery project ID is derived from the merchant ID, so there is nothing to paste in. Commit .ultracart-bq.json to your repository: it contains no credentials.

Every field it writes, along with the settings init does not ask about, is documented in the Configuration reference.

Verify the connection yourself:

uc-bq schema --list

A list of tables such as uc_orders, uc_customers, and uc_items means you are connected. An error here is almost always authentication or taxonomy level, both covered in Troubleshooting.

Create your first report​

Open Claude Code in the directory containing .ultracart-bq.json and ask a question in plain language:

Show me revenue trends by product category for the last 90 days

Claude Code reads your schema with uc-bq schema, writes and tests SQL with uc-bq query, designs an ECharts visualization, renders it with uc-bq render, writes an executive analysis, and saves a manifest describing how to rebuild all of it.

When it finishes you have a directory like this:

./reports/DEMO/revenue-by-category/
├── report.yaml           # Manifest: parameters, chart type, config, run history
├── query.sql             # Parameterized SQL
├── chart.js              # ECharts configuration
├── analysis_prompt.md    # System prompt for future analysis runs
├── chart.png             # Rendered chart
├── report.md             # Executive analysis
├── report.pdf            # Chart and analysis combined
└── data.json             # Query results

Commit that directory. The manifest, SQL, chart configuration, and analysis prompt are the recipe; everything else is regenerated on each run.

Other questions worth trying:

  • What are my top 10 products by revenue this quarter?
  • Build a customer cohort retention analysis for the past 6 months
  • Compare revenue by payment method, month over month

Replay the report without Claude Code​

This is the part that makes the report worth committing. Refresh it with fresh data:

uc-bq run revenue-by-category

That re-runs the saved SQL, re-renders the chart, rebuilds the PDF, and appends an entry to the run history in report.yaml. It makes no AI calls unless an analysis prompt and an API key are both present.

Override the dates without editing anything:

uc-bq run revenue-by-category --start_date=2026-01-01 --end_date=2026-03-31

Refresh every report you have:

uc-bq run-all

Because replay is ordinary Node.js, the same command works unattended. See Scheduling and automation when you are ready for that.

Let Claude Code install it for you​

If Claude Code is already running, it can do everything above from the conversation. Paste this:

Install this skill globally and walk me through setting it up:
https://www.npmjs.com/package/@ultracart/bq-skill

It reads the package documentation, installs the CLI and the skill prompt, walks you through authentication, and helps you configure the merchant connection. The manual steps above remain useful when something goes wrong and you need to check one stage at a time.

Next steps​

Was this page helpful?