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:

curl -fsSL https://raw.githubusercontent.com/cube-js/cube/master/install-cli.sh | sh

Windows (PowerShell):

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:

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:

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 instead:

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:

1. Create a deployment

   cube deployments create --name my-deployment --region aws-us-east-1-2
   cube regions  # list available regions
   
2. Connect a database

   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
   
3. Deploy your project

   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).

4. Watch the build and query

   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 endpoint.

Import from GitHub

Connect a deployment to a GitHub repository instead of uploading files:

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 <command> --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; settings, versions, 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, enable-branch/disable-branch, dev-mode, commit, pull, merge, merge-to-default
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
spec	Show the API’s OpenAPI specification — see Discovering the API
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.

Changing the Cube version

cube deployments versions lists the Cube versions a deployment can switch to — the head of each update channel, plus the older versions your account has run before:

cube deployments versions DEPLOYMENT_ID

VERSION  CHANNEL  LATEST  CURRENT  PASS AS
1.7.20   latest   true    true     cubejs/cube:v1.7.20
1.6.69   latest   false   false    cubejs/cube:v1.6.69

Apply one with update. Any of 1.7.20, v1.7.20 or cubejs/cube:v1.7.20 is accepted; a version that is not on the list is rejected. The container image is resolved from the version, so there is nothing else to set:

cube deployments update DEPLOYMENT_ID --release-channel-version 1.7.20
cube deployments update DEPLOYMENT_ID --release-channel release  # move to a channel's latest

cube deployments settings DEPLOYMENT_ID reads back every setting, including the version and channel currently in effect.

Discovering the API

cube spec prints the OpenAPI specification of the API you are logged into, so neither you nor an AI agent has to guess an endpoint’s parameters. It reads /api/v1/spec from the deployment itself, which means the contract you get is the one that build actually serves.

With no arguments it lists every operation:

cube spec

METHOD  PATH                                            SUMMARY
GET     /api/v1/deployments                             Get deployments
PUT     /api/v1/deployments/{deploymentId}              Update a deployment
...

Pass a pattern to narrow it down. The match is case-insensitive and covers the method, path, summary, and operation id:

cube spec settings

Add --json to get OpenAPI instead of a table. Unfiltered, that is the entire document — pipe it into a code generator or a validator. Filtered, it is a smaller but still valid document containing just the matching operations plus every schema they reference, transitively:

cube spec updateDeployment --json

That last form is the one to reach for when you want an endpoint’s full parameter list: the request body’s schema is included rather than left as a $ref pointing into a document you would then have to fetch in full.

Point an agent at cube spec <topic> --json and it can construct a correct request without any hardcoded knowledge of the API.

Data model Git workflow

Edit the data model through branches without touching production:

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.

enable-branch keeps a shared branch’s staging environment always active, so it stays queryable without anyone viewing the branch in the UI — useful for running tests against a branch from CI. disable-branch reverts to the default, where the environment is only active while viewed. cube data-model branches DEPLOYMENT_ID shows the current state per branch, and cube environments list DEPLOYMENT_ID --type staging lists the enabled ones with their API credentials.

cube data-model enable-branch DEPLOYMENT_ID my-branch
cube data-model disable-branch DEPLOYMENT_ID my-branch

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).