CLI

The Norcube CLI ships as one binary with two names — norcube and the short alias nrc. The platform-level commands are documented here; the product command groups have their own pages: LangSync CLI and Backup CLI.

Global behaviour

Every command supports:

• --org <slug-or-id> — run against a specific organization without changing your active one.
• -o, --output table|json|yaml — table (default, human) or machine formats for scripting.
• --no-pager — long tables normally page through less ($NORCUBE_PAGER / $PAGER override); this disables it.

The CLI also checks for new releases in the background (cached a day; disable with NORCUBE_NO_UPDATE_CHECK=1) and prints a one-line notice when an upgrade is available.

Login and identity

nrc login            # opens the browser; --force to re-authenticate
nrc whoami           # who am I, which org is active, which API host
nrc logout           # clears tokens and identity

login starts a loopback handshake: it opens app.norcube.com/cli-login in your browser, you approve while signed in, and the browser hands a separate CLI session back to the local process. Nothing to paste. The session's refresh token is stored in your OS keyring (service name norcube — that's what the macOS Keychain prompt is about), never in a file; short-lived access tokens are minted from it per product and organization automatically, including transparent refresh-token rotation.

Because the CLI session is independent of your browser session, logging out of the web app doesn't disconnect the CLI, and vice versa — nrc logout is what clears the CLI side.

Organizations

nrc org list                 # all your orgs; * marks the active one
nrc org use <slug-or-id>     # set the active org
nrc org switch               # interactive picker
nrc org current              # print the active org
nrc org create "Acme Inc" [--slug acme] [--set-active=false]

The active organization is what every product command targets by default. It's persisted in the CLI config, shown by whoami, and overridden per-invocation with --org. Sensible scripting default: org create auto-activates the new org in interactive shells but not in scripts, so automation never silently changes your state — pass --set-active explicitly to choose.

Note that LangSync project directories can pin their own organization via .langsync.json, which beats the active org inside that tree — see org resolution.

Configuration

nrc config show          # resolved URLs + login state — first stop when debugging
nrc config path          # where the config file lives
nrc config reset-urls    # restore per-service API URLs to defaults

Config lives in a TOML file (~/.config/norcube/config.toml on Linux, ~/Library/Application Support/norcube/config.toml on macOS), storing service URLs, your identity, and the active org — but never tokens (those are keyring-only). Every service URL can be overridden via environment for staging/self-hosted setups: NORCUBE_AUTH_URL, NORCUBE_LANGSYNC_URL, NORCUBE_SNAPDB_URL, NORCUBE_DOMAINRADAR_URL, NORCUBE_BILLING_URL, NORCUBE_WEB_APP.

config show prints the resolved values after flags, environment, and file are merged — the answer to "why is the CLI hitting the wrong host?".

Upgrading

nrc upgrade              # self-update from GitHub releases

The updater verifies the release's SHA-256 checksum before swapping the binary, and it's package-manager aware: a Homebrew-installed norcube tells you to brew upgrade norcube instead (override with --force).

Errors you'll actually see

Exit codes are boring on purpose: 0 success, 1 anything else.

Related

• LangSync CLI — namespaces, marks, project sync.
• Backup CLI — datasources, policies, org-wide job history.
• Tokens — the JWT model the CLI automates.