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)
  • Semantic overlays — Cube.dev overlay definitions in semantic/
  • 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 the Dev Container targets the bound Organization — overlays, tables, segments, integrations, and so on. The target org is determined by the REVOS_ORG_ID env var baked into the container config. Override it per-command with --org <id> or by setting REVOS_ORG_ID.

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 mounts this key automatically.

Switching organizations​

Use revos org switch to change the active Organization for CLI commands. This does not rebind an existing Project — it only affects commands that rely on the global org context (e.g., revos tables list).

To work against a different Organization from within a Project, pass --org <id> or set REVOS_ORG_ID. See Organizations for details.