Rill Setup — Brainforge Analytics

Purpose: Run Rill locally (rill start) for delivery and financial dashboards. Supports both explores (ad-hoc analysis) and dashboards (saved visualizations).

1. Install Rill

Option A: Install script (recommended for Cursor VM)

./rill/scripts/install-rill.sh
export PATH="$HOME/.rill:$PATH"

Option B: Official installer (interactive)

curl https://rill.sh | sh

Option C: Homebrew (macOS)

brew install rilldata/tap/rill

Verify: rill version

2. Run Rill (Sample Data Only)

cd rill
rill start

Opens http://localhost:9009. The sample_goals CSV loads immediately — you can explore and build dashboards.

3. Connect to Snowflake (Real Data)

3.1 Get credentials from 1Password

op signin  # if not already signed in
op read "op://Brainforge AI Team/Brainforge Internal Snowflake/username"
op read "op://Brainforge AI Team/Brainforge Internal Snowflake/password"
op read "op://Brainforge AI Team/Brainforge Internal Snowflake/account"
# Also need: warehouse, role, database, schema

3.2 Create `.env` in `rill/`

cd rill
cp .env.example .env

Edit .env and set:

SNOWFLAKE_DSN=USERNAME:PASSWORD@ACCOUNT/DATABASE/SCHEMA?warehouse=<WAREHOUSE>&role=<ROLE>

Replace USERNAME, PASSWORD, ACCOUNT, DATABASE, SCHEMA with values from 1Password. The same variable is used for Rill Cloud project variables when deploying.

3.3 Enable Snowflake sources

cp sources/clockify_snowflake.yaml.example sources/clockify_snowflake.yaml

Update the sql in clockify_snowflake.yaml when the Clockify table location is confirmed (see delivery-analytics-plan).

3.4 Restart Rill

rill start

4. Explores vs Dashboards

Mode	Use Case
Explore	Ad-hoc queries, one-off charts, drill-downs, filters
Dashboard	Saved dashboards for recurring reports (daily pulse, weekly summary, etc.)

Both use the same underlying models. Build explores first to validate metrics, then promote to dashboards.

5. Deploy Rill Cloud projects (`delivery-analytics`, `finance-analytics`)

Deploy projects from:

rill/delivery/ → delivery-analytics (DP-195)
rill/finance/ → finance-analytics (DP-196)

For CI / Cursor Cloud (no interactive login), use a service account and API token.

5.1 Preconditions

Snowflake: SNOWFLAKE_DSN prepared for the reporting service account (service_user_report + role_report) using key-pair auth. DSN points to <TARGET_DATABASE>/BRAINFORGE_RILL and includes warehouse + role. Never commit DSN values to git.
Cursor Cloud: Use a Rill service account token (no rill login); see one-time setup and credentials table below.

5.2 One-time setup: service account (on a machine where you can run `rill login`)

Cursor Cloud cannot complete rill login (device flow). Use a service account and API token so deploy runs non-interactively.

You need the issued service token for deploy/query in CI/Cloud. For new projects, give the service an org role so it can create projects on first deploy.

Service name: Pick one (e.g. brainforge-ci). Cursor Cloud does not need the service name for deploy/query commands—only the token.

Create a service account with org role:

rill service create brainforge-ci --org brainforge --org-role admin

If projects already exist, use:

rill service set-role <service-name> --org brainforge --project delivery-analytics --role admin
rill service set-role <service-name> --org brainforge --project finance-analytics --role admin

Issue a token: rill service token issue --service brainforge-ci --org brainforge — copy it; shown only once.
Store the token (and any other secrets) in 1Password and/or Cursor Cloud (see 5.3).

5.3 Credentials to add to Cursor Cloud

Secret / env var	Purpose
`RILL_SERVICE_TOKEN`	Auth for `rill project deploy` and `rill query` in CI/Cursor Cloud. Required.
`RILL_USER_TOKEN`	User API token for `rill env set` / `rill env push` (service tokens cannot update project variables). Required when setting `SNOWFLAKE_DSN` from CLI.
`SNOWFLAKE_DSN`	Full Snowflake DSN for both projects (must use `service_user_report` + `role_report` in production). Build from 1Password key-pair material; see rill-production-service-user-report.md.

5.4 Auto-deploy on push to main (GitHub Actions)

A workflow in .github/workflows/rill-deploy.yml runs on push to main when files under rill/ change. It installs the Rill CLI and runs rill project deploy for both delivery-analytics and finance-analytics.

Required: Add the service token as a GitHub repo secret:

Secret name: RILL_SERVICE_TOKEN
Value: The token from rill service token issue --service brainforge-ci --org brainforge (see 5.2). Store in 1Password and paste into GitHub → Settings → Secrets and variables → Actions.

If the secret is missing, the workflow will fail at the deploy step; add it once to enable auto-deploy.

5.5 Deploy from repo root (manual / Cursor Cloud or CI)

From repo root (e.g. /workspace in Cursor Cloud):

export PATH="$HOME/.rill:$PATH"
rill project deploy /workspace \
  --org brainforge \
  --project delivery-analytics \
  --subpath rill/delivery \
  --description "Delivery health dashboards for Brainforge Delivery" \
  --push-env=false \
  --interactive=false \
  --api-token "$RILL_SERVICE_TOKEN"
 
rill project deploy /workspace \
  --org brainforge \
  --project finance-analytics \
  --subpath rill/finance \
  --description "Revenue and cost/margin dashboards for Brainforge Finance" \
  --push-env=false \
  --interactive=false \
  --api-token "$RILL_SERVICE_TOKEN"

Some orgs still require a user token for deploy/list operations (only users can list projects by fingerprint). If service-token deploy fails, run deploy from a trusted machine with RILL_USER_TOKEN.

5.6 Configure connector variable in cloud

After deploy, set the Snowflake DSN in Rill Cloud for both projects:

for project in delivery-analytics finance-analytics; do
  rill env set "$project" SNOWFLAKE_DSN "$SNOWFLAKE_DSN" \
    --org brainforge \
    --interactive=false \
    --api-token "$RILL_USER_TOKEN"
done

If RILL_USER_TOKEN is not available in Cursor Cloud, set the variable once using a user token on a trusted machine, then continue CI deploys with RILL_SERVICE_TOKEN.

5.7 Validate deployment with sample query

rill query \
  --org brainforge \
  --project delivery-analytics \
  --sql "select date, person, project, hours from delivery_time_effort_mart order by date desc limit 10" \
  --interactive=false \
  --api-token "$RILL_SERVICE_TOKEN"
 
rill query \
  --org brainforge \
  --project finance-analytics \
  --sql "select month_start, total_revenue, total_costs, operating_profit from finance_monthly_summary order by month_start desc limit 6" \
  --interactive=false \
  --api-token "$RILL_SERVICE_TOKEN"

Expected: delivery query returns rows for time/effort fields and finance query returns recent months with populated revenue/cost/margin values.

5.8 If deploy fails: “repository does not exist”

If rill project deploy ... --project finance-analytics fails with failed to fetch from remote: failed to open git repository: repository does not exist, the Rill Cloud project’s Git connection is wrong or broken. Fix it in the UI:

Open Rill Cloud → org brainforge → project finance-analytics.
Go to Project settings (or Source / Git).
Set the repository URL to the correct GitHub repo (e.g. this repo) and ensure the token/credential has access to it.
Save and trigger a refresh/redeploy, or run rill project deploy again from the repo.

6. Rill Cloud RBAC (DP-197)

This section documents project-level access for the split analytics projects:

delivery-analytics (delivery personas: delivery leads, EPs, CSOs)
finance-analytics (finance personas: CFO, execs, Ops)

Reference: Rill user group management

6.1 User groups

Group	Intended access	Project role
`delivery-viewers`	Delivery leads, EPs, CSOs	`viewer` on `delivery-analytics`
`finance-viewers`	CFO, execs, Ops	`viewer` on `finance-analytics`

6.2 Current membership snapshot (2026-03-03)

delivery-viewers:

ambersiru.lin@brainforge.ai
awaish.kumar@brainforge.ai
brian@brainforge.ai
casie.aviles@brainforge.ai
mustafa.raja@brainforge.ai
rico.rejoso@brainforge.ai
robert.tseng@brainforge.ai
ryan.brosas@brainforge.ai
samuel.roberts@brainforge.ai
uttam+dfd@brainforge.ai

finance-viewers:

ambersiru.lin@brainforge.ai
casie.aviles@brainforge.ai
robert.tseng@brainforge.ai
samuel.roberts@brainforge.ai
uttam+dfd@brainforge.ai

6.3 Project role assignments

Configured:

finance-viewers has viewer on finance-analytics.
Removed autogroup:members from finance-analytics so finance access is no longer org-wide by default.

Pending prerequisite:

delivery-analytics project does not exist yet in org brainforge (CLI returns Project not found).
After DP-195 creates the project, run:

export PATH="$HOME/.rill:$PATH"
rill usergroup add \
  --org brainforge \
  --project delivery-analytics \
  --group delivery-viewers \
  --role viewer \
  --interactive=false \
  --api-token "$RILL_SERVICE_TOKEN"

6.4 Add or remove users from a group

Add a user:

export PATH="$HOME/.rill:$PATH"
rill user add \
  --org brainforge \
  --group delivery-viewers \
  --email "<user-email>" \
  --interactive=false \
  --api-token "$RILL_SERVICE_TOKEN"

Remove a user:

export PATH="$HOME/.rill:$PATH"
rill user remove \
  --org brainforge \
  --group delivery-viewers \
  --email "<user-email>" \
  --interactive=false \
  --api-token "$RILL_SERVICE_TOKEN"

Use --group finance-viewers for finance access changes.

6.5 Verify RBAC configuration

export PATH="$HOME/.rill:$PATH"
 
# List project-level group roles
rill usergroup list --org brainforge --project finance-analytics \
  --interactive=false --api-token "$RILL_SERVICE_TOKEN"
 
# List members in each group
rill user list --org brainforge --group delivery-viewers \
  --interactive=false --api-token "$RILL_SERVICE_TOKEN"
rill user list --org brainforge --group finance-viewers \
  --interactive=false --api-token "$RILL_SERVICE_TOKEN"

7. Production Snowflake credentials for Rill Cloud (DP-198)

For the production runbook covering:

service_user_report verification/creation in Snowflake,
key-pair setup and rotation,
credential storage locations (1Password + Rill project settings),
configuration for both delivery-analytics and finance-analytics,
and onboarding new Rill projects,

see rill-production-service-user-report.md.

8. Rill Cloud verification checklist (DP-199)

Use this checklist after deploy/RBAC/credential setup tickets to verify the cloud deployment is healthy for both analytics projects.

8.1 Success criteria

delivery-analytics and finance-analytics both exist in org brainforge.
A Snowflake identity query succeeds from each cloud project.
At least one project-specific model query returns rows in each project.
Dashboard + explore resources load and remain Idle in project status.
Decision is explicit: production dashboards run in Rill Cloud; local is for development/testing only.

8.2 Precheck project presence

export PATH="$HOME/.rill:$PATH"
rill project list --org brainforge --interactive=false --api-token "$RILL_SERVICE_TOKEN"

Expected: both delivery-analytics and finance-analytics appear.

If delivery-analytics is missing and deploy fails with:

only users can list projects by fingerprint (PermissionDenied)

then deploy from a trusted machine using a user token:

export PATH="$HOME/.rill:$PATH"
rill project deploy /workspace \
  --org brainforge \
  --project delivery-analytics \
  --subpath rill/delivery \
  --description "Delivery health dashboards for Brainforge Delivery" \
  --push-env=false \
  --interactive=false \
  --api-token "$RILL_USER_TOKEN"

8.3 Snowflake connectivity check (both projects)

export PATH="$HOME/.rill:$PATH"
for project in delivery-analytics finance-analytics; do
  echo "== $project =="
  rill query \
    --org brainforge \
    --project "$project" \
    --connector snowflake \
    --sql "select current_account() as current_account, current_user() as current_user, current_role() as current_role" \
    --interactive=false \
    --api-token "$RILL_SERVICE_TOKEN"
done

Expected: each project returns one row with non-null account/user/role values.

8.4 Sample model query check (both projects)

export PATH="$HOME/.rill:$PATH"
 
# Delivery
rill query \
  --org brainforge \
  --project delivery-analytics \
  --sql "select date, person, project, hours from delivery_time_effort_mart order by date desc limit 10" \
  --interactive=false \
  --api-token "$RILL_SERVICE_TOKEN"
 
# Finance
rill query \
  --org brainforge \
  --project finance-analytics \
  --sql "select month_start, total_revenue, total_costs, operating_profit from finance_monthly_summary order by month_start desc limit 10" \
  --interactive=false \
  --api-token "$RILL_SERVICE_TOKEN"

Expected: both queries return rows.

8.5 Dashboard/explore save verification

CLI status check:

export PATH="$HOME/.rill:$PATH"
rill project status delivery-analytics --org brainforge --interactive=false --api-token "$RILL_SERVICE_TOKEN"
rill project status finance-analytics --org brainforge --interactive=false --api-token "$RILL_SERVICE_TOKEN"

Expected:

Canvas resources present for each project.
MetricsView resources present (explore backing datasets).
Resource status is Idle (no runtime errors).

Manual UI check (recommended for release sign-off):

Open each project URL shown in rill project status.
Open an explore from a metrics view.
Apply a filter/chart change and save.
Refresh and confirm the saved explore/dashboard persists.

8.6 Deployment decision (Open Question 5)

Production dashboards: hosted in Rill Cloud (delivery-analytics, finance-analytics) for shared access, RBAC, and managed runtime.
Local Rill (rill start): development/testing only for model and dashboard iteration before cloud deployment.

8.7 2026-03-03 verification snapshot

From Cursor Cloud on 2026-03-03:

finance-analytics Snowflake identity query succeeded.
finance-analytics rill project status shows Canvas + MetricsView resources in Idle.
delivery-analytics was not present in rill project list.
Deploy attempt with RILL_SERVICE_TOKEN failed with only users can list projects by fingerprint (PermissionDenied).
Local validation succeeded for both repo projects (/workspace/rill and /workspace/rill/finance) using Snowflake connector queries.

8.8 2026-03-04 DP-195 update

From Cursor Cloud on 2026-03-04:

Added dedicated delivery project at rill/delivery/ and validated resource hydration locally.

Local sample query succeeded:

rill query --local \
  --path /workspace/rill/delivery \
  --sql "select date, person, project, hours from delivery_time_effort_mart order by date desc limit 10"

Cloud deploy attempt for delivery-analytics from rill/delivery/ using RILL_SERVICE_TOKEN still failed with: only users can list projects by fingerprint (PermissionDenied).

Direct cloud query confirms the project is still absent:

rill query --org brainforge --project delivery-analytics --sql "select 1 as ok"

Next step remains: run deploy + rill env set once using RILL_USER_TOKEN on a trusted machine, then continue non-interactive deploy/query with RILL_SERVICE_TOKEN.

9. Executive summary canvas panel phases (DP-225)

rill/delivery/dashboards/executive_summary_canvas.yaml is a dedicated CEO/board single-pane view. During Phase 1 it should run with delivery metrics and explicit placeholders for finance mart dependencies.

Panel	Phase	Notes
Revenue header (total revenue, MoM, TTM growth)	Phase 2	Placeholder until finance mart is connected
Profitability strip (gross, operating, EBITDA margin)	Phase 2	Placeholder until finance mart is connected
Delivery strip (utilization, active projects, headcount)	Phase 1	Live from `delivery_time_effort_mart`
Cash position (cash on hand, current ratio, AR aging)	Phase 2	Placeholder until finance mart is connected
Alerts row (red/yellow/green)	Phase 1	Delivery KPI thresholds live now; extend with finance alerts in Phase 2

Current threshold assumptions for the alerts row (tunable as Alantra benchmarks are finalized):

Utilization: red < 70%, yellow 70%-79%, green >= 80%
Active projects: red 0, yellow 1-2, green >= 3
Team headcount: red <= 2, yellow 3-4, green >= 5

10. References

Rill docs
Snowflake connector
delivery-analytics-2026-03.md
delivery-and-finance-analytics-2026.md
governance.md
Rill deploy credentials — service accounts and tokens for CI
rill-production-service-user-report.md — production Snowflake credential workflow for Rill Cloud

Brainforge Knowledge

Explorer

rill-setup