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. 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:$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.

A context does not hold a default space. A command that works on one entity in a space takes --space, or names the entity as <space>/<slug>, and a list or bulk command without --space spans every space in the organization you can see:

cub unit list --space $SPACE
cub unit get $SPACE/my-unit

To get your current context:

cub context get

Contexts

A context bundles the server, organization, and user 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

Reading output

-o json, -o yaml, -o jq=<expr> and -o yq=<expr> give structured output, -o name just the names, and --select <fields> limits which fields are fetched. Read a command's -o json once before writing a jq expression against it, because the shapes are not the entity alone:

  • get wraps the entity with related entities. cub unit get -o json returns the Unit under Unit, alongside its Target, UpstreamUnit, ChangeSet and others, so its slug is .Unit.Slug. A Unit's configuration data is not in it; cub unit data prints that.
  • list returns a list of the same wrappers. The slugs of cub space list -o json are .[].Space.Slug.
  • Function output is one object per Unit. cub function get with -o json, -o yaml or -o jq=... prints, for each Unit, an object with SpaceID, UnitID, SpaceSlug, UnitSlug, OutputType and Output, one after another rather than as one list; pipe -o json to jq -s to combine them. --show values drops the wrapper and prints the values alone, and --show data prints the configuration data the function returned.

A flag that takes one value, such as --filter, keeps the last one given; repeat only the flags whose help says they can be repeated.

Setting an entity's fields

Each field of an entity that you can set has a flag on that entity's create and update commands, named for the field: --display-name, --where-trigger, --release-target. A field that refers to another entity takes its slug, <space>/<slug> for one in another space, or its ID. Giving - as the value clears the field.

cub space update prod-eu --display-name "Production EU" --attribute-filter platform/standard-attributes
cub space update prod-eu --attribute-filter -

A field that is a list of things with fields of their own, such as a View's columns or a ChangeWorkflow's stages, has one flag that names the elements and one flag for each of their fields, given as <element>=<value>:

cub view update my-view --column Unit.Slug --column Unit.CreatedAt \
    --column-order-by-direction Unit.CreatedAt=DESC

--set and --unset reach any field by its path, including ones with no flag of their own. They are on the create and update commands of spaces, components, filters, views, triggers, invocations, links, attributes, and change workflows:

cub changeworkflow update my-workflow --set "Stages.?Name=prod.WhereSpace=Labels.Stage = 'prod'"
cub view update my-view --set Filter=platform/all-units --unset 'Columns.?Name=Unit~1CreatedAt'
  • A path is field names separated by dots, in the configuration path syntax: a list element is selected by position or as ?<key>=<value>, and a dot inside a name is written ~1. An element that isn't there is added.
  • The names are the ones cub <entity> edit shows, where a reference is named for what it refers to: Filter, not FilterID.
  • A list of plain values separates them with ;. An object, or a list of objects, is given as YAML or JSON.
  • --unset clears a field, or removes the list element the path ends at.
  • With --patch, a path can't go through a list element, because a patch replaces a list whole. Update one entity without --patch to change an element.

How flag values are written

Separator Meaning Example
, Between the values of a flag that can be repeated --unit a,b is --unit a --unit b
= A key and its value --label Environment=prod
: The parts of one value, in a fixed order --permission Manage:user@example.com
; The items of a list inside one value --stage-prerequisites 'prod=Released;Healthy'
/ A slug and the space it is in --release-target infra/cluster
- Nothing: clears a field, or with key=- removes a key --where-trigger -, --label Environment=-

Quote a value that holds a space, a ;, or anything else your shell reads.

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.