> ## Documentation Index > Fetch the complete documentation index at: https://cubed3-cli-dbt-sync.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Cube CLI > Command-line interface for managing Cube deployments, data models, and workspace resources. The Cube CLI (`cube`) is a single-binary command-line interface for the Cube platform. Use it to create and manage deployments, deploy data model code, work with the data model Git workflow, connect GitHub repositories, tail deployment logs, and automate workspace administration from scripts and CI. The Cube CLI works with the Cube cloud platform. It is not required for running Cube Core locally. ## Installation Linux / macOS: ```bash theme={"dark"} curl -fsSL https://raw.githubusercontent.com/cube-js/cube/master/install-cli.sh | sh ``` Windows (PowerShell): ```powershell theme={"dark"} irm https://raw.githubusercontent.com/cube-js/cube/master/install-cli.ps1 | iex ``` The installer downloads the release binary for your platform and adds it to your `PATH`. Set `CUBE_VERSION` to pin a release tag, or `CUBE_INSTALL_DIR` to change the install location. The CLI checks for new releases in the background and prints a notice when one is available. Update in place at any time: ```bash theme={"dark"} cube update # install the latest release cube update --check # only report what's available ``` Running `cube` with no arguments prints the installed version above the help text. ## Authentication Sign in with the browser device flow — the CLI prints a URL and a short code, opens your browser, and waits for approval: ```bash theme={"dark"} cube login --url https://TENANT.cubecloud.dev ``` Credentials are saved to `~/.config/cube/config.toml` (Linux/macOS) or `%APPDATA%\cube\config.toml` (Windows). Multiple accounts are supported as named contexts (`--name` on login, `--context` on any command), and expired access tokens refresh automatically. For CI and scripts, use an [API key][ref-api-keys] instead: ```bash theme={"dark"} cube login --api-key sk-YOUR_API_KEY --url https://TENANT.cubecloud.dev # or, without a config file: CUBE_API_URL=https://TENANT.cubecloud.dev CUBE_API_KEY=sk-YOUR_API_KEY cube deployments list ``` ## Deploy a project The core workflow — create a deployment, connect a database, upload your data model, and query it: ```bash theme={"dark"} cube deployments create --name my-deployment --region aws-us-east-1-2 cube regions # list available regions ``` ```bash theme={"dark"} cube variables set DEPLOYMENT_ID \ CUBEJS_DB_TYPE=postgres \ CUBEJS_DB_HOST=db.example.com \ CUBEJS_DB_NAME=mydb \ CUBEJS_DB_USER=user \ CUBEJS_DB_PASS=secret ``` ```bash theme={"dark"} cube deployments update DEPLOYMENT_ID -d '{"deployMode":"cli"}' cube deploy DEPLOYMENT_ID --directory ./my-cube-project -m "initial deploy" ``` `cube deploy` hashes local files, uploads only what changed, removes remote files deleted locally (`--keep-missing` opts out), and triggers a single build. Pass `--branch` to deploy to a specific data model branch instead of the active dev-mode branch (or the deploy branch, if none is active). ```bash theme={"dark"} cube deployments build-status DEPLOYMENT_ID cube deployments token DEPLOYMENT_ID # mints a Core Data APIs token ``` Use the token against the deployment's [REST (JSON) API][ref-rest-api] endpoint. ## Import from GitHub Connect a deployment to a GitHub repository instead of uploading files: ```bash theme={"dark"} cube github status # link state of your GitHub account cube github installations # your GitHub App installations cube github repos INSTALLATION_ID # repositories in an installation cube github branches OWNER/REPO --installation INSTALLATION_ID cube deployments create --name from-repo --region aws-us-east-1-2 \ -d '{"creationMethod":"github"}' cube github connect DEPLOYMENT_ID REPO --installation INSTALLATION_ID --branch main ``` Connecting clones the repository into the deployment and triggers the first build. ## Command reference Run `cube --help` for the full options of any command. | Command | Description | | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `login`, `logout`, `whoami`, `context` | Authentication and saved contexts | | `deployments` | List, get, create, update, delete deployments; `token`, `build-status`, `advance-step`, `reset-step` | | `deploy` | Upload a local project directory and build it | | `logs` | Tail deployment pod logs (`--pod`, `-c/--container`, `--source production\|dev`) | | `regions` | List available deployment regions | | `github` (`gh`) | GitHub integration: `status`, `installations`, `repos`, `branches`, `connect` | | `data-model` | Data model files and Git workflow: `list`, `get`, `put`, `delete`, `rename`, `file-hashes`, `branches`, `create-branch`, `dev-mode`, `commit`, `pull`, `merge`, `merge-to-default` | | `dbt` | dbt sync: `sync` (`--ref`, `--wait`), `status`, `result`, `cancel` | | `environments` | Deployment environments and environment tokens | | `variables` | Deployment environment variables | | `folders`, `workbooks`, `reports`, `workspace` | Workspace content management | | `users`, `groups`, `attributes`, `policies` | Users, groups, and access control | | `tenant`, `notifications`, `integrations`, `oidc`, `api-keys` | Account administration | | `embed` | Embed sessions, tokens, embed tenants; `enable-dashboard`/`disable-dashboard` toggle signed embedding for a dashboard | | `agents`, `app`, `meta`, `scim` | Agents, app config, model metadata, SCIM v2 | | `api` | Raw authenticated API request (escape hatch): `cube api GET /api/v1/... -q key=value -d '{...}'` | | `update` | Update the CLI to the latest release | | `completion` | Generate shell completions | List commands print tables by default; pass `--json` anywhere for raw JSON output, suitable for piping to `jq`. ## Data model Git workflow Edit the data model through branches without touching production: ```bash theme={"dark"} cube data-model create-branch DEPLOYMENT_ID my-branch --dev-mode cube data-model put DEPLOYMENT_ID model/cubes/orders.yml --file orders.yml --branch my-branch cube data-model merge-to-default DEPLOYMENT_ID --branch my-branch -m "add orders cube" ``` `merge-to-default` merges into the deploy branch and rebuilds production. File writes (`put`, `delete`, `rename`) only land on a **dev-mode branch**. With `--dev-mode`, `create-branch` (and `dev-mode`) forks a personal `dev-…` branch and prints it — pass that printed name via `--branch`, not the name you gave `create-branch`, or omit `--branch` to use your active dev-mode branch. Writes targeting any other branch are rejected by the API. ## dbt sync Pull a dbt project's models in as cubes. The repository, credential and warehouse settings come from the deployment's dbt integration, so a sync needs only the deployment: ```bash theme={"dark"} cube dbt sync DEPLOYMENT_ID --wait ``` Each sync creates a **new branch** for the generated cubes and prints its name. `--wait` polls until the sync finishes, reporting each stage, then prints the generated files; it exits non-zero if the sync fails. Without `--wait` it returns a `syncJobId` you can follow yourself: ```bash theme={"dark"} cube dbt status DEPLOYMENT_ID SYNC_JOB_ID --wait cube dbt result DEPLOYMENT_ID SYNC_JOB_ID cube dbt cancel DEPLOYMENT_ID SYNC_JOB_ID ``` `--ref` syncs a specific branch or tag of the dbt repository instead of the one saved on the integration — which is what makes a pull-request gate meaningful, since otherwise every run would compile the tracked branch: ```bash theme={"dark"} cube dbt sync DEPLOYMENT_ID --ref feature/orders-model --wait ``` `--ref` takes a branch or tag, not a commit SHA. Syncs are not free — each one provisions a sandbox and parses the project — so prefer one per push over one per commit. ### dbt sync as a CI test gate Sync the branch under review, compile it, query it, and fail the job if any step breaks — without touching production: ```yaml theme={"dark"} env: CUBE_API_URL: ${{ secrets.CUBE_API_URL }} CUBE_API_KEY: ${{ secrets.CUBE_API_KEY }} DEPLOYMENT_ID: ${{ vars.CUBE_DEPLOYMENT_ID }} steps: - name: Sync the dbt branch under review run: | cube dbt sync "$DEPLOYMENT_ID" --ref "$GITHUB_HEAD_REF" --wait --json > sync.json echo "BRANCH=$(jq -r .branchName sync.json)" >> "$GITHUB_ENV" - name: Compile and query the generated model run: | DEV_BRANCH=$(cube data-model dev-mode "$DEPLOYMENT_ID" "$BRANCH" --json | jq -r .branchName) cube deployments build-status "$DEPLOYMENT_ID" --branch "$DEV_BRANCH" --wait TOKEN=$(cube deployments token "$DEPLOYMENT_ID") curl -sfG "$CUBE_API_URL/dev-mode/$DEV_BRANCH/cubejs-api/v1/load" \ -H "Authorization: $TOKEN" \ --data-urlencode 'query={"measures":["orders.count"]}' ``` With `--wait --json`, the sync writes one document carrying both the branch to compile and how the sync ended, which is why the branch name is available to the next step. Compile and query share a step because the dev-mode branch name is only known at runtime. The compile step has to run against the **dev-mode branch**, not the branch the sync created. A sync lands on a shared branch, and a shared branch has nothing compiling it until someone opens it in dev mode. `cube data-model dev-mode` forks a personal `dev-…` branch and prints the name to wait on. Waiting on the wrong branch fails quickly rather than hanging: `build-status` reports such a branch as `building` with an error of `Branch is not active` (or `Bad branch` if it doesn't exist), and `--wait` stops and says so. The API key needs `SchemaUpdate` on the deployment to start or cancel a sync, and `SchemaRead` to follow one. Any failure — a failed sync, a failed compile, a timeout — exits non-zero, so the job fails without extra scripting. A gate that runs per pull request accumulates the branches its syncs create. There is no CLI command to delete a branch yet, so prune them from the data model UI periodically, or merge the ones you want to keep. ## Environment variables | Variable | Description | | ------------------------ | ------------------------------------------------------------------------------------------- | | `CUBE_API_URL` | Tenant URL, e.g. `https://TENANT.cubecloud.dev` (alternative to a saved context) | | `CUBE_API_KEY` | Credential: an API key or token (alternative to `cube login`) | | `CUBE_AUTH_SCHEME` | Force the `Authorization` scheme: `bearer` or `api-key` (auto-detected by default) | | `CUBE_NO_UPDATE_CHECK` | Disable the background update check | | `CUBE_NO_TELEMETRY` | Disable anonymous usage telemetry (also disabled when `CI` is set) | | `CUBEJS_TELEMETRY=false` | Legacy alias for `CUBE_NO_TELEMETRY`, kept for compatibility with the previous `cubejs` CLI | | `CUBE_VERSION` | Installer only: release tag to install | | `CUBE_INSTALL_DIR` | Installer only: install directory | ## Telemetry The CLI sends anonymous usage events (command group, success/failure, version, platform). No personal data is collected; the anonymous identifier is a hash of the OS machine id. Telemetry is disabled automatically in CI, or explicitly with `CUBE_NO_TELEMETRY=1` (or the legacy `CUBEJS_TELEMETRY=false`). [ref-api-keys]: /admin/account-billing/api-keys [ref-rest-api]: /reference/core-data-apis/rest-api/index