Skip to main content
Tutorial

AI-Powered Reporting with Claude Code - Getting Started

Last Updated: April 08, 2026

Table of Contents​

  1. Overview
  2. Quick Start with Claude Code
  3. Prerequisites
  4. Installation
  5. Authentication
  6. Your First Report
  7. Replaying Reports
  8. Available Commands
  9. Troubleshooting
  10. Next Steps

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​

  1. Node.js >= 24

    • Check your version: node --version
    • If you use nvm: nvm install 24
    • Download from nodejs.org if needed

  2. Google Cloud CLI (gcloud)

  3. 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.

info

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

bash

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.

tip

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:

  1. Discover your schema via uc-bq schema
  2. Generate and test SQL via uc-bq query
  3. Create an ECharts visualization
  4. Render to PNG via uc-bq render
  5. Write an executive analysis
  6. 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​

CommandDescription
uc-bq initInteractive setup -- creates config and tests BigQuery connectivity
uc-bq schema --listList all available tables in your data warehouse
uc-bq schema --tables=XGet schema details for specific tables
uc-bq listList all saved reports
uc-bq run <name>Replay a saved report with fresh data
uc-bq run-allReplay all saved reports
uc-bq history <name>Show run history for a report
uc-bq validate --configValidate your configuration file
uc-bq install-skillInstall or update the Claude Code skill prompt
uc-bq install-skill --uninstallRemove 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
Was this page helpful?