Getting Started

Two roles, two starting points

Your invitation determines what you need to do on day one. Pick the path that matches your role.

BA Owner / Account Operator

Explore and govern

Accept invitation → sign in → set billing context → list workspaces in your billing account → open dashboards in the UI.

No BigQuery setup or model authoring required. Any workspaces your developers have published to the billing account are ready to explore in the UI.

Developer / Analytics Engineer

Build and publish

Accept invitation → sign in → set billing context → set up BigQuery service account → create workspace → author sources, models, visualizations, dashboards → push.

This guide uses BigQuery as the starting path, so a BigQuery service account is set up before you write models. Postgres and MySQL are equally supported — see Sources if your data lives there instead.

Prerequisites before running commands

You have an invitation to the target account in https://my.looky.studio.
The Looky CLI is installed and available as looky in your shell.
You have a local folder that will act as the linked root (example: <local_root>).
You know the billing account id you should operate in (example: <billing_account_id>).

Day-zero sequence

Accept invitation and verify your role and scope (Owner Invitation).
Sign in to the UI, then link CLI to the same instance and root (Sign In and Connect the CLI).
Developers only: Mint a GCP service account JSON — you will drop it into the workspace's secrets/ folder once the workspace exists in the next step (BigQuery Dataset Access).
Set billing context, create the workspace, configure runtime/sources.runtime.yml, and deploy settings with looky push --settings (Create Your First Workspace).
Invite additional builders only after the first workspace has its sources deployed and at least one push of content succeeds (Invite Developers and Collaborators).

Baseline command flow

looky login https://my.looky.studio <local_root>
looky whoami

cd <local_root>
looky billing list
looky billing use <billing_account_id>

cd <local_root>/<billing_account_id>
looky create <workspace_slug> --name "My Workspace"
cd <workspace_slug>
looky status

# Edit runtime/sources.runtime.yml with real source values and drop
# the credentials JSON into secrets/. Then deploy:
looky push --settings

# Build content under content/ (models, viz, dashboards). Then:
looky validate
looky push

looky login https://my.looky.studio <local_root>
looky whoami

Set-Location <local_root>
looky billing list
looky billing use <billing_account_id>

Set-Location <local_root>\<billing_account_id>
looky create <workspace_slug> --name "My Workspace"
Set-Location <workspace_slug>
looky status

# Edit runtime\sources.runtime.yml with real source values and drop
# the credentials JSON into secrets\. Then deploy:
looky push --settings

# Build content under content\ (models, viz, dashboards). Then:
looky validate
looky push

Success criteria before moving to Build Workflow

looky whoami returns your authenticated user for the linked root.
looky billing use <billing_account_id> succeeds from <local_root>.
looky status resolves a workspace id in <billing_account_id>/<workspace_slug> shape.
looky push --settings deploys the runtime source config without errors.

If any one of these fails, stop and fix it before authoring dashboards. Most downstream failures are setup failures in disguise. Running looky validate is meaningful only after sources are deployed and you have content to compile.