AI-Powered Reporting with Claude Code - Getting Started

Last Updated: April 08, 2026

Overview

UltraCart streams your e-commerce data -- orders, customers, items, analytics, and more -- into a per-merchant BigQuery data warehouse. The @ultracart/bq-skill package lets you build, visualize, and automate reports against that data using Claude Code as your AI analyst and a deterministic CLI for replay.

Reports are code. SQL, chart configs, and manifests live in Git. You design a report once with Claude Code, then replay it forever with uc-bq run -- no AI cost on subsequent runs unless you want executive analysis.

Key capabilities:

Design reports with natural language -- Ask Claude Code a question about your data and get a complete report with SQL, charts, PDFs, and executive analysis
Replay without AI -- Once a report exists, uc-bq run refreshes it with fresh data using pure Node.js -- no LLM calls, no per-run cost
Professional output -- Every report produces ECharts visualizations, PDFs, and markdown analysis, ready for stakeholders
Version-controlled -- Reports live in Git. Review changes in PRs, track history, roll back with git revert

Quick Start with Claude Code

If you already have Claude Code running, the fastest way to get started is to let it handle the installation for you. Open Claude Code and paste this:

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

Claude Code will read the package documentation, install the CLI and skill prompt, guide you through authentication, and help you configure your merchant connection -- all within the conversation. Once setup is complete, you can immediately start asking questions about your data.

This is the recommended path for most users. The manual steps below cover the same ground if you prefer to install things yourself or need to troubleshoot.

Prerequisites

Required Software

Node.js >= 24
- Check your version: node --version
- If you use nvm: nvm install 24
- Download from nodejs.org if needed
Google Cloud CLI (gcloud)
- macOS: brew install google-cloud-sdk
- Linux (Debian/Ubuntu): sudo apt-get install google-cloud-cli
- Windows: Download from cloud.google.com/sdk/docs/install
Claude Code
- Required for designing new reports
- Not needed for replaying existing ones

Required Access

BigQuery data warehouse enabled -- Your UltraCart merchant account must have the data warehouse active. Contact UltraCart support if you're unsure.
Google account with BigQuery access -- You need a Google account that has been granted access to your UltraCart BigQuery project. The project ID follows the pattern ultracart-dw-{merchantid}.

Installation

Install the package globally:

npm install -g @ultracart/bq-skill

Then install the Claude Code skill prompt:

uc-bq install-skill

This copies the skill to ~/.claude/skills/uc-bq/SKILL.md. Restart Claude Code for the skill to take effect.

If your .npmrc routes @ultracart to GitHub Packages, install directly from the public registry tarball instead:

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

To verify the installation:

uc-bq --version

Authentication

The CLI uses Google Cloud Application Default Credentials (ADC). You authenticate once and the BigQuery SDK picks up your credentials automatically.

1. Sign in to your Google account:

gcloud auth login

This opens a browser window. Sign in with the Google account that has access to your UltraCart BigQuery project.

2. Set application default credentials:

gcloud auth application-default login

This creates a local credential file that the BigQuery SDK finds automatically. You only need to do this once per machine -- credentials persist across terminal sessions.

3. Configure the CLI:

uc-bq init

This prompts for your merchant ID, taxonomy level, and preferences, then writes .ultracart-bq.json and tests the connection. The BigQuery project ID is derived automatically from your merchant ID (ultracart-dw-{merchantid}).

4. Verify it works:

uc-bq schema --list

If you see your tables, you're authenticated and connected.

For CI/CD and scheduled runs, use a service account instead of personal credentials. See the full reference guide for setup instructions.

Your First Report

Open Claude Code and ask a question about your data:

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

Claude Code will:

Discover your schema via uc-bq schema
Generate and test SQL via uc-bq query
Create an ECharts visualization
Render to PNG via uc-bq render
Write an executive analysis
Save a replayable report manifest

Result: A report directory under ./reports/{merchant_id}/{report-name}/ containing:

./reports/DEMO/revenue-by-category/
├── report.yaml           # Manifest -- parameters, config, metadata
├── query.sql             # Parameterized SQL template
├── chart.js              # ECharts chart configuration
├── chart.png             # Full visualization
├── report.pdf            # Combined PDF with chart + executive analysis
├── report.md             # Executive analysis (markdown)
└── data.json             # Query results

Try more questions:

"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"

Replaying Reports

Once a report is created, replay it anytime without Claude Code:

# Replay with default date parameters
uc-bq run revenue-by-category

# Custom date range
uc-bq run revenue-by-category --start_date=2026-01-01 --end_date=2026-03-31

# Replay all saved reports
uc-bq run-all

# Charts and data only, zero LLM cost
uc-bq run revenue-by-category --no-analysis

Replay executes the saved SQL with fresh data, re-renders the chart, and generates a combined PDF. The report manifest captures everything needed to reproduce the report -- you never lose the recipe.

Available Commands

Command	Description

Command	Description
`uc-bq init`	Interactive setup -- creates config and tests BigQuery connectivity
`uc-bq schema --list`	List all available tables in your data warehouse
`uc-bq schema --tables=X`	Get schema details for specific tables
`uc-bq list`	List all saved reports
`uc-bq run <name>`	Replay a saved report with fresh data
`uc-bq run-all`	Replay all saved reports
`uc-bq history <name>`	Show run history for a report
`uc-bq validate --config`	Validate your configuration file
`uc-bq install-skill`	Install or update the Claude Code skill prompt
`uc-bq install-skill --uninstall`	Remove the Claude Code skill prompt

Troubleshooting

Could not load the default credentials

Cause: Google Cloud ADC has not been configured.

Solution: Run gcloud auth application-default login to set up credentials.

Permission denied / Access Denied

Cause: Your Google account hasn't been granted access to the UltraCart BigQuery project.

Solution: Contact your UltraCart admin to provision BigQuery access for your Google account.

Project not found

Cause: The project ID is derived from your merchant ID (ultracart-dw-{merchantid}). If the merchant ID in your config is wrong, the project won't be found.

Solution: Verify that your merchant ID in .ultracart-bq.json is correct. Run uc-bq init to reconfigure.

Dataset not found

Cause: Your taxonomy level may not include the dataset you're querying. Standard-level users can't access ultracart_dw_medium.

Solution: Check your taxonomy level with your UltraCart admin. See the full reference guide for dataset access details.

Query exceeds safety limit

Cause: The estimated bytes processed exceeds the default 10 GB safety limit.

Solution: Use --force to bypass for a single command, or adjust max_query_bytes in your config. See Cost Protection for details.

Next Steps

AI-Powered Reporting with Claude Code - Full Reference -- Full configuration, external data sources, delivery, alarms, decks, and scheduling
Full CLI Reference -- Every command and flag
Report Delivery Setup -- Slack and email configuration
GitHub Repository -- Source code and issue tracker