Skip to main content

revos init

Scaffold a new RevOS data engineering project.

Usage​

revos init [destination]

The destination can be a project name, relative path, or absolute path. If omitted, the current directory name is used as the project name.

Requires: revos auth login first for greenfield runs. In-project runs (when revos.yaml already exists) sign you in automatically if needed.

Flags​

FlagDescription
-y, --yesNon-interactive mode — skip confirmation prompts
--dry-runPreview what would be created without making changes

Two Modes​

revos init behaves differently depending on whether you run it inside an existing project (i.e. a tree containing revos.yaml):

  • Greenfield — no revos.yaml found walking up from the destination → full scaffold + service account provisioning + IaC discovery.
  • In-project — revos.yaml discovered → idempotent. The org prompt is skipped (org is read from revos.yaml), scaffolding is skipped (existing files are never overwritten), IaC discovery is skipped, and the GCP service account key is only provisioned if ~/.revos/{project}-gsa-creds.json is missing. If you aren't authenticated yet, the browser opens for sign-in first — no org picker is shown because the org is already pinned in revos.yaml. Re-running with everything in place is a clean no-op.

The in-project mode is what powers the Dev Container onboarding flow: open the container with no host credentials shared in and run a single revos init — it signs you in via the browser and materializes the GCP service account key into the container's ~/.revos/.

What It Does (Greenfield)​

  1. Organization selection — Fetches your organizations and prompts you to select one (auto-selects if only one). The selected org must have a BigQuery dataset configured.
  2. Service account provisioning — Creates a GCP service account for your org (idempotent) and writes the key to ~/.revos/{project}-gsa-creds.json (or %USERPROFILE%\.revos\{project}-gsa-creds.json on Windows).
  3. Directory structure — Creates a medallion-architecture dbt project: 
    project/
    ├── .devcontainer/
    ├── .claude/
    │   ├── settings.json        # security rules
    │   └── skills/              # RevOS AI skills (installed from revosai/skills)
    ├── dbt/models/
    │   ├── bronze/
    │   ├── silver/
    │   └── gold/
    ├── cubes/
    ├── connectors/             # custom low-code connectors (see Connectors)
    └── connections/
  4. Dev Container — Generates .devcontainer/devcontainer.json, Dockerfile, post-create.sh, post-start.sh, and welcome.sh with Python 3.13, Node.js, Google Cloud CLI, dbt-bigquery, the connector test runtime (so revos connectors check/discover/read work out of the box), and jq pre-installed. The container has no host bind mounts; instead it persists three per-project named Docker volumes — revos-{slug}-credentials (~/.revos), revos-{slug}-gcloud (~/.config/gcloud), and revos-{slug}-claude (~/.claude) — so CLI login, GSA key, gcloud auth state, and Claude Code state all survive Rebuild Container.
  5. dbt configuration — Generates dbt/profiles.yml and dbt/dbt_project.yml pre-configured for BigQuery with medallion materialization settings.
  6. Standard files — .gitignore and README.md.
  7. AI companion files — CLAUDE.md, AGENTS.md, and .claude/settings.json with deny rules that block AI assistants from reading ~/.revos/ (CLI credentials and service account keys), ~/.config/gcloud/ (Google Cloud Application Default Credentials), from running gcloud auth print-*-token commands, and from editing the settings file itself (so the AI can't lift its own restrictions).
  8. AI skills — Installs the RevOS skills into .claude/skills/ (exploring your data lakehouse, authoring Connection configs from Source streams, creating Cube.dev semantic models, building dbt transformations, loading sample data, querying and visualizing the semantic model) by running npx skills add revosai/skills/data-engineering --copy. The skills come from the public revosai/skills repository (grouped into bundles — data-engineering is the one for this project type), so you can refresh them in an existing project with npx skills update — no init re-run or CLI upgrade. The Dev Container also re-installs/refreshes them on every start (self-healing if a prior install failed), keeping them current automatically. See AI Skills. Needs network access; if it fails, init still completes and prints the command to install them later.
  9. IaC discovery — Pulls existing Connections and Cubes from the API into connections/ and cubes/, so the project starts from the live state. Pass --no-pull to skip. Sources are managed only through revos sources commands and referenced from Connection YAML by their server id.
  10. Project marker — Writes revos.yaml at the root, pinning the directory to your organization. The CLI walks up from the current directory to find this file when you run commands like revos status, revos apply, revos diff, and revos pull. Run revos status to list local resources, revos diff to preview drift, revos apply to push local changes to the API, or revos pull to import remote state into your YAML.

Example​

# Scaffold into a new directory
revos init my-data-project
cd my-data-project

# Preview without creating anything
revos init my-data-project --dry-run

# Non-interactive mode
revos init my-data-project --yes

After scaffolding, open the project in VS Code and click Reopen in Container. Inside the container, finish setup with:

revos init          # signs you in via browser (if needed) and provisions the GCP service account key into ~/.revos

Subsequent container starts auto-activate the service account via postStartCommand, so bq, dbt, and gcloud work without manual steps.

Organization Binding​

During revos init, you select an organization. That choice is baked into the scaffolded project — every generated file is configured for that specific org. There is no post-init way to rebind the project to a different organization.

Where the Org Is Stored​

FileSettingPurpose
revos.yamlmetadata.orgIdAuthoritative org for all CLI commands run inside this project tree
.devcontainer/devcontainer.jsoncontainerEnv.REVOS_ORG_IDConvenience for non-CLI tools inside the container (validated against revos.yaml)
.devcontainer/devcontainer.jsoncontainerEnv.REVOS_BQ_DATASETBigQuery dataset belonging to the org
.devcontainer/devcontainer.jsoncontainerEnv.GOOGLE_CLOUD_PROJECTGCP project associated with the org
~/.revos/<project>-gsa-creds.jsonService-account key (host & container, both written by revos init)GCP credentials scoped to the org's resources
dbt/profiles.ymlproject and datasetBigQuery target generated from the org's configuration

Implications​

  • revos apply / pull / diff always target the org in revos.yaml. If the container's REVOS_ORG_ID env var disagrees (e.g. you opened a different project's container), the CLI hard-fails rather than silently writing to the wrong org.
  • --org is rejected inside a project. The destination is revos.yaml's metadata.orgId; --org only works outside a project tree.
  • Different org = separate project. If you need to work with another organization, scaffold a new project with revos init.
  • Sharing a project folder across orgs won't work without re-scaffolding, because the service-account key, dbt profile, and container environment all reference the original org.
tip

To see which org you are currently targeting, run revos org current inside the Dev Container.

Next Steps​