Your UltraCart data warehouse already has the data. Orders, customers, items, analytics, and more streaming into BigQuery in real time. The missing piece has always been getting that data out in a useful format without needing a data engineer or an expensive BI tool. That changes with the @ultracart/bq-skill package, which pairs your BigQuery data with Claude Code to turn natural language questions into complete, replayable reports.
https://github.com/UltraCart/uc-bq-claude-skill
What This Gives You
Ask a question in plain English. Get a full report: SQL query, ECharts visualization, PDF, and executive analysis, saved as code in your Git repository. From that point on, a single command refreshes the report with fresh data. No AI cost on replay unless you want updated analysis.
- Natural language to finished report: Open Claude Code and type something like "Show me revenue trends by product category for the last 90 days." Claude discovers your schema, writes optimized SQL, builds a chart, renders it to PNG and PDF, writes executive analysis, and saves everything as a replayable manifest.
- Replay forever with one command: Once a report exists,
uc-bq run revenue-by-categoryre-executes the saved SQL with fresh data, re-renders the chart, and regenerates the PDF. Add--no-analysisfor charts and data only with zero LLM cost. - Reports are version-controlled code: SQL, chart configs, and YAML manifests live in Git. Review changes in pull requests, track history with
git log, roll back a broken report withgit revert. Your reporting gets the same rigor as your application code. - Professional output: Every report produces ECharts visualizations, combined PDFs with charts and analysis, and markdown summaries. These are ready for stakeholders, not rough data dumps.
Connect Your Own Data Sources
Your UltraCart data warehouse is the starting point, but it doesn't have to be the only source. The CLI lets you register external GCP projects alongside your UltraCart data: marketing warehouses, DBT pipelines, advertising platforms, or any BigQuery dataset you have access to.
- Browse before committing: Use
uc-bq schema --project=my-marketing-warehouseto explore an external project's datasets and tables before adding them to your config. - Register with one command:
uc-bq config add-project marketing --project-id=my-marketing-warehouseadds the project. Then expose the specific datasets and tables you want available for queries. - Query across sources: Once registered, external tables appear alongside your UltraCart tables. Claude Code can join your e-commerce order data with your Google Ads spend, Funnel.io marketing data, or any other BigQuery dataset in a single query.
- You control access: You explicitly choose which datasets and tables to expose. Nothing is visible until you add it.
Automated Delivery and Alerts
Reports don't need to sit in a directory waiting to be opened. Configure delivery to push completed reports directly to the people who need them.
- Slack and email delivery: Add a
deliverysection to any report manifest and use--deliveron your next run. Charts and PDFs land in a Slack channel or inbox automatically. Supported email providers include SendGrid, Postmark, Mailgun, Resend, and AWS SES. - Alarms for management by exception: Define threshold, percent-change, or missing-data conditions on any report. When revenue drops more than 20% or a query returns zero rows, you get notified. When everything is normal, reports run silently. Severity levels control whether you get an inline note, a distinct alert, or a Slack
@channelmention. - Schedule with your existing tools:
uc-bq runis pure Node.js with no LLM dependency. Schedule it in cron, GitHub Actions, or any CI/CD system. A GitHub Actions workflow template is included that handles service account authentication, runs all reports, and delivers results on a weekly cadence.
Executive Report Decks and Dashboards
Individual reports are useful. Combined decks are what executives actually want to read.
- Combined PDF decks: Group multiple reports into a single deck with a branded cover page, clickable table of contents, and all charts and analyses in one document. Define a deck once in YAML, then generate it with
uc-bq deck run weekly-executive. - Interactive HTML dashboards: Generate a self-contained HTML file with live ECharts visualizations including tooltips, hover effects, zoom, and responsive layout. Deploy it to S3, an internal web server, or open it from disk. No server required.
- Deck-level delivery: Deliver the combined deck PDF to Slack and email instead of sending individual reports. One polished document for the C-suite.
Getting Started
If you already have Claude Code, the fastest path is to let it handle the setup. Open Claude Code and paste:
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.
If you prefer to install manually:
- Install the package:
npm install -g @ultracart/bq-skill - Install the Claude Code skill:
uc-bq install-skill - Authenticate with Google Cloud:
gcloud auth application-default login - Configure:
uc-bq init
Your BigQuery data warehouse must be enabled on your UltraCart merchant account. Contact UltraCart support if you're unsure about your access. Full setup instructions, external data source configuration, and the complete CLI reference are available in the Getting Started documentation and the full reference guide.
What You Can Build
Here are some reports merchants are already building with the skill:
- Revenue trends by product category, payment method, or customer segment
- Customer cohort retention and lifetime value analysis
- Top products by revenue, units sold, or margin
- Marketing attribution by joining your ad spend data with order revenue
- Inventory velocity and reorder forecasting
- Subscription churn and renewal rate tracking
- Weekly executive briefing decks combining multiple report types
Every report starts with a question in natural language. Claude Code handles the SQL, visualization, and manifest creation. You handle the decisions.
Cost and Access
- The package is free and open source: Apache 2.0 license. Install from npm.
- BigQuery costs are minimal: On-demand pricing is $6.25/TB scanned. A typical report scans 1-3 GB (~$0.01-0.02). The CLI includes a 10 GB safety limit that blocks expensive queries before they run.
- LLM costs only when you choose: Replaying reports has zero AI cost. Executive analysis on scheduled runs uses your choice of provider: Anthropic, OpenAI, Google Gemini, Grok, or AWS Bedrock.
- Data access follows your taxonomy level: UltraCart controls which fields are available based on your account's taxonomy assignment. Standard users get order totals, item data, and analytics. Higher levels include customer PII.
The @ultracart/bq-skill package is available now on npm. Source code and issue tracking are on GitHub. For detailed documentation, start with the Getting Started guide or dive into the full reference.