Install the CLI
Install the cubicle CLI on macOS or Linux (x64 or arm64) with the one-line installer or by hand with a SHA-256 checksum, add the optional root tunnel for SSH and the private network, upgrade, uninstall and log in.
The cubicle CLI manages Boxes, access and SSH from your computer. It runs on macOS and Linux, on
x64 and arm64 processors. Windows is not supported.
Install with the script
curl -fsSL https://api.cubicle.sh/downloads/install | shThe script does the following:
- It picks the bundle for your system and processor, and downloads
cubicle-<os>-<arch>.tar.gzwith its.sha256checksum fromhttps://api.cubicle.sh/downloads/. - It verifies the checksum. On a mismatch it stops with "Checksum mismatch; the download may have changed during an update. Try again."
- It runs the bundle's
install.sh, which lists what it will do and asksInstall the Cubicle CLI? [y/N]. - It offers the optional tunnel, then prints
Run `cubicle login` to sign in.
Run it as your normal user. The CLI needs no administrator rights, and the installer refuses to
run as root; only the tunnel uses sudo.
Installer flags
Pass flags to the installer after sh -s --:
curl -fsSL https://api.cubicle.sh/downloads/install | sh -s -- --yes --no-tunnel| Flag | Effect |
|---|---|
--yes | Installs the CLI without asking. Without a terminal to ask on, the installer cancels unless you pass it. |
--tunnel | Also installs the tunnel without asking first. sudo still asks for your password. |
--no-tunnel | Skips the tunnel offer. |
Without --tunnel or --no-tunnel, the installer offers the tunnel when it has a terminal, and
otherwise prints how to add it later.
Install by hand
Download the bundle and its checksum, verify, extract and run its installer. The bundles are
cubicle-darwin-arm64, cubicle-darwin-x64, cubicle-linux-arm64 and cubicle-linux-x64.
curl -fLO https://api.cubicle.sh/downloads/cubicle-darwin-arm64.tar.gz
curl -fLO https://api.cubicle.sh/downloads/cubicle-darwin-arm64.tar.gz.sha256
shasum -a 256 -c cubicle-darwin-arm64.tar.gz.sha256
tar -xzf cubicle-darwin-arm64.tar.gz
cd cubicle-darwin-arm64
./install.shUse cubicle-darwin-x64 on an Intel Mac.
install.sh takes the same flags as the script: --yes, --tunnel and --no-tunnel.
What gets installed
| Path | Contents |
|---|---|
~/.local/share/cubicle/cli | The bundle: the CLI, its own Node.js runtime, the cubicle-network WireGuard binary, install.sh, uninstall.sh and third-party licenses. |
~/.local/share/cubicle/cli-previous | The previous installation, kept when you upgrade. |
~/.local/bin/cubicle | A link to the CLI. |
~/.config/cubicle/ | Your login details and the private network log, written when you use the CLI. See Files the CLI writes. |
When XDG_DATA_HOME is set, the bundle goes to $XDG_DATA_HOME/cubicle/cli instead. The CLI
needs no system Node.js, Homebrew or WireGuard package.
Add ~/.local/bin to your PATH
When ~/.local/bin is not on your PATH, the installer prints:
Add /home/you/.local/bin to your PATH, for example in ~/.zshrc or ~/.bashrc:
export PATH="$HOME/.local/bin:$PATH"Add the export line to your shell's startup file and open a new terminal. When another
cubicle comes first on your PATH, the installer prints which one it is.
Verify the installation
cubicle versionIt prints the installed version and build target, and the API that cubicle login uses:
cubicle <version> (darwin-arm64)
default API: https://api.cubicle.shAdd the tunnel
The tunnel is an optional network helper that runs as root. You need it for cubicle connect,
cubicle ssh and for reaching Boxes at their private IP addresses or
<box>.<org>.cubicle.internal names. Logging in, managing Boxes, running commands and taking
snapshots work without it.
cubicle tunnel installThe command asks first, then installs the helper with sudo. cubicle tunnel status prints
whether the tunnel is installed and connected, and cubicle tunnel uninstall removes it and keeps
the CLI. Install the tunnel explains what the helper
does and what it needs on Linux and macOS.
Upgrade
Run the installer again:
curl -fsSL https://api.cubicle.sh/downloads/install | shIt replaces ~/.local/share/cubicle/cli and keeps the version it replaced in cli-previous. When
the tunnel is installed, it asks Update the tunnel? [y/N] so that the root copy matches the new
version.
Uninstall
cubicle logout
~/.local/share/cubicle/cli/uninstall.shWhen XDG_DATA_HOME is set, the uninstaller is $XDG_DATA_HOME/cubicle/cli/uninstall.sh.
cubicle logout is optional. It signs you out and removes your stored login. The uninstaller then
does the following:
- It removes the tunnel first when it is installed;
sudoasks for your password. - It removes the CLI, its previous version and the
~/.local/bin/cubiclelink. - It keeps your stored login (unless you logged out),
~/.config/cubicle/and the device identity in/var/lib/cubicle/cli.
Log in
cubicle loginThe command prints a Dashboard link and a code to approve. See Log in to the CLI.
Related
- Quickstart: log in, create an API key and run a command in a Box.
- Sign in and API keys: sign-in methods, the CLI login and service account API keys.
- CLI overview: global options, Box arguments and every command.
- Reach a Box over the private network: connect with the tunnel.
- SSH into a Box: add an SSH key and connect.
Quickstart
Install the cubicle CLI, log in, create a service account with a write API key, then use @cubicle/sdk from TypeScript to create a Box, run uname -a in it, print the output and delete the Box.
Sign in and API keys
How people sign in to Cubicle (email and password, Google, cubicle login device flow) and reset a password, how programs authenticate with service account API keys (cbk_), which routes read and write keys can call, how to create, expire, revoke and use keys, and what happens to Boxes when a key, service account or member is removed.