CLI

The Norcube CLI (norcube, alias nrc) exposes Backup under the nrc backup command group. It covers the whole path from a database to a proven backup: adding data sources, creating and attaching policies, running a backup now, org-wide backup listings, downloading backups, restoring them, restore tests (on demand or automated) and pausing and resuming, all scriptable. Every flag of every command is in the generated CLI reference.

Every command supports --org <slug> to override the organization, --profile <name> to use another profile, -o table|json|yaml|text for output and --query to pick fields (see output and scripting). Setup is the standard CLI login:

nrc login
nrc org use <slug>
nrc backup datasources list     # sanity check

# a second account (say, a client's), in its own profile
nrc login --profile client-acme
nrc backup datasources list --profile client-acme

Datasources

# list, with optional name filter
nrc backup datasources list
nrc backup datasources list --search prod
nrc backup datasources list --all-pages -o text --query "[?!isActive].id"

# details for one datasource (-o json for every field)
nrc backup datasources get <id>

# master switch: stop/start all scheduled backups for a database
nrc backup datasources pause          # interactive picker in a TTY
nrc backup datasources pause <id>
nrc backup datasources resume <id>

The list shows name, engine, environment, active state, and ID. pause/resume toggle the datasource's active flag. The semantics are in Pause and resume: future scheduling stops, queued and running jobs still finish, and there's no catch-up on resume.

Add or change a datasource

# the connection string comes from a file...
nrc backup datasources create --name prod-db --engine postgres --environment prod \
  --connection-uri-file db.uri

# ...or from standard input (-), never from the command line
printenv DATABASE_URL | nrc backup datasources create --name prod-db \
  --engine postgres --environment prod --connection-uri-file -

# change only what you pass
nrc backup datasources update <id> --name prod-db-eu
nrc backup datasources update <id> --connection-uri-file new.uri   # replaces the stored credentials

--engine is postgres or mongodb, --environment one of prod, staging, dev or test, and --region defaults to eu-central-1. The connection string is only ever read from a file or standard input, so it stays out of shell history and process listings; it's stored encrypted and never shown again. A role that can read every table is enough for backups (see connect a database for the network side and the egress IP to allow).

A new datasource backs nothing up until a policy is attached (next section). The CLI doesn't run the connection test; use Test connection in the dashboard, or run a first backup with --wait and let its result answer the question.

Policies

# every backup policy of the organization
nrc backup policies list

# create one (it backs nothing up until it's attached)
nrc backup policies create --name Nightly --schedule "0 2 * * *" --timezone Europe/Prague \
  --retention-days 30 --keep-last 30 --destination <destinationId>

# change it: every datasource it's attached to follows from its next run
nrc backup policies update <policyId> --schedule "0 3 * * *"
nrc backup policies update <policyId> --retention-days 90 --keep-last 90

# the storage destinations a policy can name
nrc backup destinations list
nrc backup destinations list --managed -o json --query "[0].id"

create needs --name, --schedule (a cron expression), --timezone (an IANA name such as Europe/Prague or UTC), --retention-days, --keep-last and --destination; --method and --compression are optional. update changes only the flags you pass. Retention works as described in backup policies: a backup is deleted once it's older than --retention-days and isn't one of the newest --keep-last. --retention-days 0 keeps backups forever, which the dashboard doesn't allow.

destinations list shows Norcube-managed storage and your own buckets (--managed and --own filter them). Adding a bucket of your own happens in the dashboard.

Attachments

# attach a policy: the scheduler starts backing the datasource up on its schedule
nrc backup policies attach --datasource <id> --policy <policyId>
nrc backup policies attach --datasource <id> --policy <policyId> --priority 2 --paused

# what's attached to a datasource (policy, enabled, priority, destination)
nrc backup policies list --datasource <id>

# pause/resume one attachment (other policies keep running)
nrc backup policies pause  --datasource <id> --policy <policyId>
nrc backup policies resume --datasource <id> --policy <policyId>

# detach: destructive, so it confirms (or takes --yes for scripts)
nrc backup policies detach --datasource <id> --policy <policyId> --yes

--paused attaches without scheduling anything until you resume it. --priority orders a datasource's attachments; a run-now backup uses the highest-priority enabled one unless you name another. Detach semantics are the same as the dashboard's: future runs stop, existing archives and job history stay. See Attach a policy.

Run a backup now

nrc backup jobs run --datasource <id>                       # queue it and return
nrc backup jobs run -d <id> --policy <policyId> --wait      # wait for the result
nrc backup jobs run -d <id> -o json --query jobId

# one job, by id
nrc backup jobs get <jobId> --datasource <id>
nrc backup jobs get <jobId> -d <id> -o json --query jobStatus

jobs run is the CLI's Run backup now: it queues a backup outside the schedule, using the attached policy you name with --policy or the datasource's highest-priority enabled one. It counts towards your Backup usage like a scheduled run. With --wait the command follows the job until it finishes and exits 1 (error code job_failed, with the job as details in the JSON error) when it didn't succeed, so a script can stop on a failed backup. Ctrl-C stops waiting, not the backup; --wait-timeout (default 2 hours) gives up waiting with exit code 7 while the job keeps running.

Backups (org-wide job history)

The dashboard shows jobs per datasource; the CLI lists them across the whole organization, which is the tool for "did anything fail last night?":

nrc backup jobs list                          # newest first, all datasources
nrc backup jobs list --datasource <id>        # repeatable to filter several
nrc backup jobs list --page-size 100 --cursor <c> # manual paging
nrc backup jobs list --all-pages --max-items 5000 -o json

Columns: datasource, status, restore-test verdict, trigger (schedule/manual), started, duration, size, job ID. The TEST column shows the latest restore test of each backup (passed, passed (warnings), failed, testing…, or a dash when never tested). With -o json the output pipes straight into jq:

# every failed job, with its error-relevant fields
nrc backup jobs list -o json \
  | jq '[.[] | select(.jobStatus == "failed")]'

# the same without jq
nrc backup jobs list -o json --query "[?jobStatus=='failed']"

When more pages exist, the CLI prints the next cursor on stderr (a hint in table output, nextCursor=<cursor> with -o json), so it never corrupts piped JSON.

Download a backup

# to a local file, named after the backup object
nrc backup jobs download <jobId> --datasource <id>
nrc backup jobs download <jobId> -d <id> -o json   # {path, bytes, sha256}

# stream to stdout and straight into a restore
nrc backup jobs download <jobId> -d <id> --file - | gunzip | pg_restore -d "$DSN"

The backend issues a short-lived presigned URL and the CLI streams the bytes directly from storage. Postgres artifacts are pg_dump custom-format archives (restore with pg_restore); MongoDB artifacts are mongodump archives (restore with mongorestore --archive). Both are compressed according to the policy's compression setting, so adjust the decompression step to match (gunzip, zstd -d, or none). Backups in customer-managed buckets can't be downloaded this way, because Norcube holds no read credentials for your bucket; fetch the object from your own storage instead.

Restore a backup

# into a fresh database next to production
nrc backup restores create -d <id> --backup <jobId> \
  --mode new_database --target-uri-file admin.uri --target-database app_restored --wait

# into the database a connection string names (a new, empty server)
nrc backup restores create -d <id> --backup <jobId> --mode new_server --target-uri-file target.uri

# roll the datasource back to a backup: replaces its data
nrc backup restores create -d <id> --backup <jobId> --mode overwrite --yes

# follow restores
nrc backup restores list --datasource <id>
nrc backup restores get <restoreId>
nrc backup restores get <restoreId> -o json --query status

--mode is one of the three target modes:

Target connection strings are read from a file (- for standard input), never from the command line, and are stored encrypted and used once.

A restore changes data, so create shows what it's about to do and asks first. --yes answers for scripts; without a terminal (CI, a pipe) --yes is required and the command refuses to run without it. With --wait it follows the restore and exits 1 (job_failed) if it failed; the default --wait-timeout is 6 hours.

create doesn't run the dashboard wizard's target check, so an unreachable or read-only target shows up as a failed restore; restores get prints its error summary. The full restore log is in the datasource's Restore history in the dashboard. restores list --tests lists restore tests instead of restores.

Restore tests and restore health

# org-wide restore health, one row per datasource
nrc backup health
nrc backup health -o json

# test the newest successful backup, now, and wait for the verdict
nrc backup restore-tests run --datasource <id> --wait

# or test one specific backup
nrc backup restore-tests run <jobId> -d <id>
nrc backup restore-tests run <jobId> -d <id> -o json --query restoreJobId

# the history of tests, automated and on-demand, with their verdict
nrc backup restore-tests list --datasource <id>
nrc backup restore-tests list -d <id> -o json --query "[?status=='failed'].id"

health aggregates recent restore tests per datasource: pass rate, warnings, and when the last test ran. A datasource that has never been tested shows a dash, never a fake 0%.

restore-tests run queues an on-demand test of the backup you name, or of the datasource's newest successful backup when you don't. The verdict lands in the TEST column of nrc backup jobs list and in health. With --wait the command waits for the verdict and exits 1 (job_failed) unless the test passed (passed with warnings counts as passed), which makes it a CI gate:

# in CI (NORCUBE_TOKEN set to a CI token with backup.verify):
# fail the pipeline if the newest backup doesn't restore
nrc backup restore-tests run -d "$DS_ID" --wait --wait-timeout 1h

Automated restore-test settings

nrc backup restore-tests settings get --datasource <id>

# cadence: pick one of --every, --schedule or --sample
nrc backup restore-tests settings update -d <id> --every 7
nrc backup restore-tests settings update -d <id> --schedule "0 4 * * 0" --timezone Europe/Prague --level l2
nrc backup restore-tests settings update -d <id> --sample 25%

# target: Norcube-managed (default) or a scratch server of yours
nrc backup restore-tests settings update -d <id> --target customer_scratch --scratch-uri-file scratch.uri
nrc backup restore-tests settings update -d <id> --target managed_ephemeral

# off and on again, keeping the settings
nrc backup restore-tests settings update -d <id> --disable
nrc backup restore-tests settings update -d <id> --enable

These are the dashboard's automated test settings. update changes only what you pass. --every N tests one in every N successful backups, --schedule tests on a cron schedule (in --timezone), and --sample tests a random share (0.25 or 25%); setting any of them turns automated tests on. The scratch connection string comes from --scratch-uri-file (- for standard input) and must not point at the server being backed up. --level is the validation depth (l1 or l2); l3 with --validation-query can be saved, but the custom-query rung doesn't run yet.

Scripting patterns

# maintenance window: pause, do the work, resume
nrc backup datasources pause "$DS_ID"
./run-migration.sh
nrc backup datasources resume "$DS_ID"

# back up before a risky deploy, and stop if the backup fails
nrc backup jobs run -d "$DS_ID" --wait && ./deploy.sh

# export full history before deleting a datasource
nrc backup jobs list --datasource "$DS_ID" --all-pages -o json > history.json

Non-interactive environments need explicit arguments: commands that would open a picker error out without one, and commands that change or destroy data (restores create, policies detach) require --yes when there's no terminal to confirm on.

CI tokens

A CI token with any Backup scope can run the list and get commands and health. On top of that, backup.write allows jobs run and backup.verify allows restore-tests run, so a pipeline can back up before a deploy or gate on a restore test without being able to change anything else. Everything else that changes something (datasources, policies, attachments, restores, restore-test settings) and jobs download needs a person signed in with nrc login; a CI token is refused with a 403 (exit code 5).

What stays in the dashboard (or API)

• Deleting datasources, policies and backups.
• Adding your own storage buckets as destinations.
• The connection test and the restore wizard's target check.
• Reading and downloading restore and restore-test logs.
• Notifications and the audit log.

Use the dashboard, or call the API directly; nrc api backup … sends any request with your CLI session (see calling any API).