Skip to content

CLI Usage

cub is the command-line tool for using ConfigHub.

Installation

You can install the CLI with the following one-liner:

curl -fsSL https://hub.confighub.com/cub/install.sh | bash

The CLI is a single binary which will be saved to ~/.confighub/bin/cub. The script will also download the worker binary cub-worker-run and place it in the same directory. You need to add cub to your path. You can do that in a variety of ways:

  • sudo ln -sf ~/.confighub/bin/cub /usr/local/bin/cub
  • ln -sf ~/.confighub/bin/cub ~/bin/cub
  • export PATH=~/.confighub/bin/cub:$PATH

etc.

The CLI binary is available for Linux and Mac, ARM64 and AMD64 architectures as well as a Windows AMD64 binary which does not yet have an install script.

Getting started

To get credentials:

cub auth login

And login using your browser.

To set the default space, where SPACE is set to the slug of a space you have access to within the organization you are logged into:

cub context set --space $SPACE

To get your current context:

cub context get

Contexts

A context bundles the server, organization, user, and default space that commands run against. Your contexts are stored locally in ~/.confighub/config.yaml, and one of them is the current context. List them and see which is current with:

cub context list

Switch the current context with cub context use <name>. This is persistent — it changes the current context for every terminal until you switch again.

Per-terminal contexts

When you want different terminals to use different contexts at the same time — for example one pointed at production and another at a local development server — set the CUB_CONTEXT environment variable instead of switching the current context. It selects the context for that shell only, without changing the stored current context that other terminals use:

export CUB_CONTEXT=prod-eu
cub unit list

The context a command uses is resolved in this order, highest priority first:

  1. The --context <name> flag, which applies to a single command.
  2. The CUB_CONTEXT environment variable, which applies to the current shell.
  3. The current context set with cub context use.

If --context or CUB_CONTEXT names a context that does not exist, the command fails rather than falling back to the current context, so you never run against an unexpected target. When an override is in effect, cub context get shows how the context was selected and cub context list notes the active context, so it is always clear which one is in use.

General CLI Usage patterns

The cub CLI follows the pattern of:

cub <entity/area> <verb> [<flags>] [<arguments>]

For example:

cub unit create --space prod-eu deployment deployment.yaml

For more information

Use cub --help for detailed command help and cub --help-overview for an up-to-date usage overview.

A CLI reference is also available in the documentation.