Skip to main content

Concepts

Key terms used throughout RevOS and the CLI.

Organization​

An Organization is the top-level tenant in RevOS. It owns:

  • Data lake — BigQuery dataset where all project data lands
  • Integrations — connected data sources and destinations
  • Members — users and their roles
  • Billing — subscription and usage tracking

Organizations are created and managed through the RevOS web UI. The CLI can list and switch between organizations you belong to — see Organizations.

Project​

A Project is a local working directory scaffolded by revos init. It is bound to exactly one Organization and contains:

  • dbt models — medallion-architecture SQL transformations (bronze / silver / gold)
  • Cubes — Cube.dev semantic model definitions in cubes/
  • Connections — sync pipelines in connections/, each pointing at a Source by id (Sources themselves are managed via revos sources against the API)
  • Connectors — custom low-code connectors in connectors/, authored, tested, and published with revos connectors
  • Dev Container config — .devcontainer/ with pre-installed tooling
  • Credentials — GCP service account key written to ~/.revos/{project}-gsa-creds.json

A Project is a developer's local view into the Organization's data platform.

Relationship​

One Organization can have many Projects. Each Project points to exactly one Organization.

Organization (source of truth)
├── Project A   (developer laptop)
├── Project B   (CI runner)
└── Project C   (another developer)

The Organization holds the canonical data, integrations, and configuration. Projects are local checkouts that read from and write to it.

Practical Implications​

All CLI commands target the bound Organization​

Every revos command run inside a Project (any directory under revos.yaml) targets that Project's bound Organization — cubes, tables, segments, connections, and so on. The CLI reads revos.yaml on every command and uses metadata.orgId as the authoritative destination. Inside a Project, --org and REVOS_ORG_ID are not accepted: the CLI hard-fails on mismatch rather than silently sending writes to a different org.

Where credentials live​

  • CLI auth token — stored globally by revos auth login; shared across all Projects.
  • Service account key — per-Project, written to ~/.revos/{project}-gsa-creds.json during revos init. The Dev Container does not bind-mount this from the host; instead, running revos init inside the container re-provisions the same key into the container's own ~/.revos/ (persisted across rebuilds via the per-project revos-{slug}-credentials Docker volume).

Switching organizations​

Use revos org switch to change your global default Organization for commands run outside a Project. Inside a Project, revos org switch only updates the global default; it does not rebind the Project (whose org is anchored in revos.yaml) and the CLI prints a warning to that effect.

To target a different Organization, either cd outside the Project tree or scaffold a new Project for that Org with revos init. See Organizations for details.