cli

module
v0.21.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 29, 2026 License: Apache-2.0

README

norcube CLI

release ci license

Command-line interface for the Norcube platform. Manage backups, namespaces, organizations, and more from the terminal.

What it's best at: proving you're never locked in to Norcube Backup. norcube backup jobs download streams any backup straight from storage into pg_restore or mongorestore, and norcube backup health shows whether your backups actually restore — restore-tested against real throwaway databases, not just checksummed.

norcube CLI demo

Scripted demo with sanitized names: whoami, Backup health, scripting with -o json --query, any endpoint with norcube api, and your CLI sessions. The tape and stub live in demo/.

Status: pre-1.0. Norcube Backup (data sources, backups on demand and downloads, restores, restore tests and their settings, health, policies), LangSync (namespaces, terms, translations, languages, prompts, glossary, API keys, CSV import, audit log, project sync), DomainRadar (domain checks, bulk checks, saved domains, brand monitoring, name generation), Billing (status, subscriptions, usage, invoices, spending caps), organizations, profiles, and norcube api for everything else. See the changelog.

Install

Homebrew (macOS / Linux):

brew install --cask norcubeplatform/tap/norcube

Installs norcube, the short alias nrc, and bash/zsh/fish completions. Upgrade with brew upgrade norcube.

Debian / Ubuntu, Fedora / RHEL / openSUSE, Alpine:

Every release has .deb, .rpm and .apk packages for amd64 and arm64. They install /usr/bin/norcube, the nrc alias, shell completions and man pages (man norcube).

VERSION=0.21.0   # the release to install, without the leading v
ARCH=amd64       # or arm64
BASE=https://github.com/norcubeplatform/cli/releases/download/v$VERSION

# Debian / Ubuntu
curl -fsSLO "$BASE/norcube_${VERSION}_linux_${ARCH}.deb"
sudo apt install "./norcube_${VERSION}_linux_${ARCH}.deb"

# Fedora / RHEL / openSUSE
curl -fsSLO "$BASE/norcube_${VERSION}_linux_${ARCH}.rpm"
sudo dnf install "./norcube_${VERSION}_linux_${ARCH}.rpm"   # or: sudo zypper install ...

# Alpine (the package isn't signed with an apk key; verify the download first)
curl -fsSLO "$BASE/norcube_${VERSION}_linux_${ARCH}.apk"
sudo apk add --allow-untrusted "./norcube_${VERSION}_linux_${ARCH}.apk"

The packages aren't served from an apt/dnf repository, so upgrade by installing the next release's package the same way. Verify a release shows how to check a download before installing it.

One-liner (macOS / Linux):

curl -fsSL https://github.com/norcubeplatform/cli/raw/main/install.sh | sh

Installs to ~/.norcube/bin/norcube and creates a short alias nrc → norcube in the same directory. A per-user location means norcube upgrade never needs sudo. Override the install directory with INSTALL_DIR=/usr/local/bin (system-wide; later upgrades will need sudo), or pin a version with VERSION=v0.2.0.

If ~/.norcube/bin isn't on your PATH yet, the script prints the export line to add to your shell rc:

export PATH="$HOME/.norcube/bin:$PATH"

The script verifies the SHA-256 against the release's checksums.txt before writing to disk; it'll abort if the download was tampered with.

Direct download:

Download the archive for your platform from the GitHub Releases page (norcube_<os>_<arch>.tar.gz, or norcube_windows_amd64.zip), extract norcube (norcube.exe on Windows), and put it on your PATH. The archive also holds shell completions (completions/) and man pages (manpages/).

From source (requires Go ≥ 1.24):

git clone git@github.com:norcubeplatform/cli.git norcube-cli
cd norcube-cli
make install   # installs `norcube` to $GOPATH/bin

Upgrade

norcube upgrade

Checks GitHub for newer releases, downloads the archive for your platform, verifies its SHA-256 against the release's checksums.txt (both over TLS from GitHub), and atomically replaces the running binary. Nothing is replaced when the checksum is missing or doesn't match. Run norcube --version afterward to confirm.

If norcube was installed with Homebrew or a deb/rpm/apk package (or a Scoop or winget package, once those are published), the upgrade command detects that and tells you to upgrade with that tool instead; pass --force if you really want to override it.

Verify a release

Every release is built by the release workflow from a tag, and ships:

  • checksums.txt: the SHA-256 of every archive, package and SBOM;
  • checksums.txt.sigstore.json: a keyless Sigstore signature of checksums.txt, made with the workflow's GitHub identity;
  • <archive>.sbom.json: an SPDX software bill of materials per archive;
  • a GitHub artifact attestation (SLSA build provenance) for every file in checksums.txt.

norcube upgrade and install.sh check the SHA-256. To also check that the checksums were signed by this repository's release workflow, install cosign and run:

VERSION=v0.21.0
gh release download "$VERSION" --repo norcubeplatform/cli \
  --pattern checksums.txt --pattern checksums.txt.sigstore.json \
  --pattern norcube_linux_amd64.tar.gz

cosign verify-blob checksums.txt \
  --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp '^https://github\.com/norcubeplatform/cli/\.github/workflows/release\.yaml@refs/tags/v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

# then check the download against the verified checksums
sha256sum --ignore-missing -c checksums.txt          # Linux
shasum -a 256 --ignore-missing -c checksums.txt      # macOS

To pin the exact release instead of any tag, replace --certificate-identity-regexp ... with --certificate-identity "https://github.com/norcubeplatform/cli/.github/workflows/release.yaml@refs/tags/$VERSION".

To check the build provenance with the GitHub CLI:

gh attestation verify norcube_linux_amd64.tar.gz \
  --repo norcubeplatform/cli \
  --signer-workflow norcubeplatform/cli/.github/workflows/release.yaml

The macOS binaries are signed with a Developer ID certificate and notarized by Apple when the release was built with the signing keys configured; codesign -dv --verbose=2 "$(command -v norcube)" shows the signature.

Quick start

norcube login                       # opens your browser, signs you in
norcube whoami                      # who you are and which organization commands target
norcube org use my-org              # target another organization
norcube backup jobs list            # every backup job in the organization
norcube backup health               # which backups actually restore
norcube langsync namespaces list    # LangSync namespaces
norcube domainradar check acme.dev  # is a domain free?
norcube billing usage estimate      # this month's charges so far
norcube doctor                      # something not working? start here

nrc is a short alias for norcube (the install script, the Homebrew cask and the Linux packages create it). Add -o json and --query to any command for scripting, and --org <slug> to target another organization for one command.

In CI and on servers

Create a CI token for the organization (scopes limit what it can do, and it always expires), store it as the secret NORCUBE_TOKEN, and run commands as usual:

norcube auth ci-token create --name "GitHub Actions" --scopes langsync.sync -o text | gh secret set NORCUBE_TOKEN
- uses: norcubeplatform/setup-norcube@v1
  with:
    token: ${{ secrets.NORCUBE_TOKEN }}
- run: nrc langsync sync

On a machine without a browser, norcube login --device signs you in with a code you approve on your phone or laptop. See CI and automation.

Documentation

Contributing and security

Contributions are welcome. See CONTRIBUTING.md for the dev setup and the DCO sign-off we require instead of a CLA, and docs/ARCHITECTURE.md for how the code is organized and how to add a service or a command. Security issues go through private vulnerability reporting, not public issues — details in SECURITY.md.

Open core

This CLI is open source (Apache 2.0) and always will be: the tool that proves you can take your data and leave should not itself be a lock-in. The Norcube platform it talks to — the hosted backup scheduling, restore testing, alerting, and the rest — is a commercial service. The API surface between them is documented at docs.norcube.com, so the CLI is also a reference client if you'd rather script against the API directly.

License

Apache License 2.0 — see LICENSE. Use it, fork it, ship it, including commercially.

"Norcube" and the Norcube logo are trademarks of Norcube; the license does not grant trademark rights. A fork is welcome to exist, just not to call itself Norcube.

Directories

Path Synopsis
cmd
norcube command
internal
api
api/apierror
Package apierror renders non-2xx API responses into error messages that are actually useful for debugging.
Package apierror renders non-2xx API responses into error messages that are actually useful for debugging.
api/billing
Package billing provides primitives to interact with the openapi HTTP API.
Package billing provides primitives to interact with the openapi HTTP API.
api/domainradar
Package domainradar provides primitives to interact with the openapi HTTP API.
Package domainradar provides primitives to interact with the openapi HTTP API.
api/langsync
Package langsync provides primitives to interact with the openapi HTTP API.
Package langsync provides primitives to interact with the openapi HTTP API.
api/snapdb
Package snapdb provides primitives to interact with the openapi HTTP API.
Package snapdb provides primitives to interact with the openapi HTTP API.
cli
cli/backup
Package backup implements the `norcube backup ...` command tree (snapdb is the backend service behind the Norcube Backup product).
Package backup implements the `norcube backup ...` command tree (snapdb is the backend service behind the Norcube Backup product).
cli/billing
Package billing implements the `norcube billing ...` command tree: the organization's account status, subscriptions, usage estimate, invoices and spending caps.
Package billing implements the `norcube billing ...` command tree: the organization's account status, subscriptions, usage estimate, invoices and spending caps.
cli/domainradar
Package domainradar implements the `norcube domainradar ...` command tree: domain checks, bulk checks, saved domains, brand monitoring and the name generator.
Package domainradar implements the `norcube domainradar ...` command tree: domain checks, bulk checks, saved domains, brand monitoring and the name generator.
cli/langsync
Package langsync implements the `norcube langsync ...` command tree.
Package langsync implements the `norcube langsync ...` command tree.
cli/langsync/projectcfg
Package projectcfg loads and writes the per-project Langsync config (`.langsync.json`).
Package projectcfg loads and writes the per-project Langsync config (`.langsync.json`).
cli/langsync/projectcfg/translations
Package translations reads and writes language files for the sync command.
Package translations reads and writes language files for the sync command.
clictx
Package clictx carries the global per-invocation state (flags, cancellable context) attached to every cobra command, so subcommand packages can read it without importing the root cli package and creating an import cycle.
Package clictx carries the global per-invocation state (flags, cancellable context) attached to every cobra command, so subcommand packages can read it without importing the root cli package and creating an import cycle.
clierr
Package clierr holds the CLI's process exit codes and the error types that select them, so scripts can branch on why a command failed.
Package clierr holds the CLI's process exit codes and the error types that select them, so scripts can branch on why a command failed.
cmdutil
Package cmdutil is the one path from a command's result to stdout.
Package cmdutil is the one path from a command's result to stdout.
completion
Package completion serves dynamic shell completions (organization slugs, namespaces, data source and job ids, language codes) from the API.
Package completion serves dynamic shell completions (organization slugs, namespaces, data source and job ids, language codes) from the API.
config
Package config reads and writes the CLI's configuration file.
Package config reads and writes the CLI's configuration file.
credstore
Package credstore holds the CLI's secrets: one item per key in the OS keyring, or one 0600 file per key when no keyring is available.
Package credstore holds the CLI's secrets: one item per key in the OS keyring, or one 0600 file per key when no keyring is available.
orgs
Package orgs turns what the user typed for --org (an id or a slug) into an organization id the services accept.
Package orgs turns what the user typed for --org (an id or a slug) into an organization id the services accept.
output
Package output renders command results in one of four user-selected formats: a human-friendly table, JSON, YAML, or tab-separated text.
Package output renders command results in one of four user-selected formats: a human-friendly table, JSON, YAML, or tab-separated text.
registry
Package registry is the CLI's list of Norcube services, read from the embedded services.yaml.
Package registry is the CLI's list of Norcube services, read from the embedded services.yaml.
resolve
Package resolve decides which profile, endpoints, organization, credentials and output format one command uses, and remembers where each value came from (for `norcube config list`).
Package resolve decides which profile, endpoints, organization, credentials and output format one command uses, and remembers where each value came from (for `norcube config list`).
service
Package service builds the typed API client a command needs, the same way for every Norcube service: it resolves the profile, the target organization, the service endpoint, a token source for the service's audience (from the selected credential store) and the shared HTTP transport.
Package service builds the typed API client a command needs, the same way for every Norcube service: it resolves the profile, the target organization, the service endpoint, a token source for the service's audience (from the selected credential store) and the shared HTTP transport.
sse
Package sse reads server-sent event streams (text/event-stream), as the HTML standard defines them, and keeps a stream going across dropped connections.
Package sse reads server-sent event streams (text/event-stream), as the HTML standard defines them, and keeps a stream going across dropped connections.
term
Package term decides what the CLI may do with the user's terminal: is a stream a TTY, may it carry color, may we prompt.
Package term decides what the CLI may do with the user's terminal: is a stream a TTY, may it carry color, may we prompt.
transport
Package transport builds the one HTTP client every part of the CLI uses: generated API clients, the auth client, the token exchange and artifact downloads.
Package transport builds the one HTTP client every part of the CLI uses: generated API clients, the auth client, the token exchange and artifact downloads.
tools
codegen command
codegen regenerates the typed API clients listed in internal/registry/services.yaml: for every service with a `package`, it converts the Swagger 2.0 spec from the backend monorepo to OpenAPI 3 (specs/<package>.openapi.json) and runs a pinned oapi-codegen with internal/api/<package>/oapi-codegen.yaml.
codegen regenerates the typed API clients listed in internal/registry/services.yaml: for every service with a `package`, it converts the Swagger 2.0 spec from the backend monorepo to OpenAPI 3 (specs/<package>.openapi.json) and runs a pinned oapi-codegen with internal/api/<package>/oapi-codegen.yaml.
gendocs command
Command gendocs turns the CLI's help text into documentation, so the command tree is the only place flags and examples are written down.
Command gendocs turns the CLI's help text into documentation, so the command tree is the only place flags and examples are written down.
swagger2openapi command
swagger2openapi reads a Swagger 2.0 JSON document and writes the equivalent OpenAPI 3.0 JSON to stdout.
swagger2openapi reads a Swagger 2.0 JSON document and writes the equivalent OpenAPI 3.0 JSON to stdout.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL