Local Setup
Prerequisitesβ
- Node 22 (
.nvmrc) gcloud, logged in with your Birdy Grey account- API keys for
.env. Ask the team.
Installβ
npm install
cp .env.example .env
gcloud auth application-default login
Application default credentials cover Firestore, BigQuery and Vertex AI embeddings.
Runβ
npm run dev # http://localhost:8080/apps/birdybot/v1/healthcheck
Test with the CLIβ
The CLI scripts run the same pipelines as Slack and print to the console. They're the main way to test a change locally.
| Script | Exercises |
|---|---|
npm run query "..." | Classification and routing, end to end |
npm run product "..." | Product questions (Shopify, Airtable, BigQuery) |
npm run activation "..." | Upcoming launches (Airtable) |
npm run customer "email" | Customer DM lookup |
npm run order "..." | Order DM lookup |
npm run replace "..." | Replacement options |
npm run discount "CODE" | Discount code lookup |
npm run docs "..." | CX SOP questions (Guru) |
npm run ask, bug, outage, feature | Codebase Q&A and triage |
npm run linear SITE-123 | Triage of a real Linear issue |
npm run pr-digest, icebreaker, fpl-digest | Scheduled posts. Print only; -- --post posts to Slack |
What local runs touchβ
| System | Local default |
|---|---|
| Shopify | Whichever store .env names |
| Fulfil, platform, API Gateway, storefront links | Staging, from .env.example |
| Firestore | Staging, birdy-bot database |
| BigQuery | Production data warehouse, read-only |
| Slack | Real workspaces, if a bot token is set |
Slack behavior (threads, reactions, DMs, buttons) can't be tested locally. Deploy to staging and test there.
Checksβ
npm run test:ci
npm run typecheck
npm run biome:check