Command-line tools

noy-db · ships with create-noy-db — every scaffolded project has it; elsewhere pnpm add -D create-noy-db (or pnpm dlx create-noy-db noy-db …)

One command line since 0.10.0-pre.1. Everything that used to live under a second bin, noydb from @noy-db/cli, moved here; @noy-db/cli still installs, and every old spelling prints the new one and runs it, so nothing breaks — but there is one name to learn.

Project
  add <collection>                             Scaffold a new collection store + page
  add <@noy-db/package> [--dev] [--dry-run]    Install a package, wire it, print the trust boundary
  add --list [to|in|on|as|by|at]               The landscape — every package, by layer
  user add <userId> <role> [options]           Grant a new user access to a vault
  user rotate [options]                        Rotate DEKs for a vault
  backup <target> [options]                    Dump a vault to a file
  doctor [config] [--mode=prod] [--fix]        Readiness checks: secret, recovery, topology, capsule, deps, hygiene
  doctor crypto                                In-memory crypto round-trip check

Pods (.noydb files)
  pod inspect <file.noydb>                     Print the bundle header (no secret)
  pod verify  <file.noydb>                     Verify bundle integrity (no secret)
  describe <file.noydb> [options]              YAML/JSON schema audit (needs the secret)

Configuration
  config validate <file.js|mjs>                Sanity-check a NoydbOptions file
  config scaffold [--profile=<id>]             Topology skeleton → stdout, .env template → stderr
  config profiles                              List the ten topology profiles

Running
  monitor <file.js|mjs> [--interval=ms]        Live store metrics (the store must be metered)
  inspect <file.js|mjs> --vault=<name> [...]   Terminal inspector (installs on demand)

Renamed spellings

Doctor

noy-db doctor answers "is this project ready?" without a secret. Checks carry stable ids by group — NOY-S secret handling, NOY-R recovery, NOY-T topology, NOY-C capsule, NOY-D dependencies, NOY-H hygiene — and each finding names the fix:

noy-db doctor — mode dev, 6 check group(s)
  ✗ NOY-D001  `@noy-db/hub` is not a dependency of this project  (./package.json)
      → add it: `pnpm add @noy-db/hub`
  1 error · 0 warn · 0 info

--mode=prod tightens what counts as an error (a secret in a tracked file, no recovery enrolment for an owner, a plaintext capsule). --json emits the report for CI; --fail-level=warn makes warnings fail the step; --fix applies the safe fixes (today: ignoring .env). Satellites can register their own checks by exporting noydbDoctorChecks from their root entry.

Add

noy-db add <package> installs a @noy-db/* package with the package manager your lockfile implies, wires it where a config can be edited (an in-nuxt module into nuxt.config), prints the import to paste otherwise, and states the trust boundary the layer crosses:

$ noy-db add to-aws-s3 --dry-run
dry: pnpm add @noy-db/to-aws-s3

to- The store sees ciphertext only. It cannot read your records, and it cannot run a query.

import { toAwsS3 } from '@noy-db/to-aws-s3'

add --list [prefix] is the catalog by layer. It is fetched from this site (/catalog.json, generated from the feature registry) and falls back to the copy shipped with the CLI, so it works offline.

Offline pod forensics

pod inspect prints the header a .noydb pod discloses to anyone holding the file — no secret involved:

noy-db pod inspect acme.noydb

{
  "formatVersion": 1,
  "handle": "037VE50R64H6BS9Z4KHDCXWQ6B",
  "bodyBytes": 531,
  "bodySha256": "2c6366a64a37d734955496c29397967689f068dea63aebec2ac1a47354346f40"
}

pod verify recomputes the integrity hashes (still no secret — it checks the ciphertext, it cannot read it). describe goes further and does decrypt — pass --user and --secret (or NOYDB_SECRET) and it emits a YAML/JSON audit of collections, fields, and schemas, with --schemas full|sidecar for JSON Schema output. Exit codes are scripting-friendly: 0 ok, 1 internal, 2 usage, 3 auth failure.

Config tools

config validate sanity-checks a NoydbOptions file before you ship it. config profiles lists the ten deployment topologies; config scaffold emits a starting config for one of them (A is local-only single-user):

noy-db config scaffold --profile=A > noydb.config.mjs

// ── noydb config (profile A) ───────────────────
// Local-only single-user. No cloud.

import { createNoydb } from '@noy-db/hub'
import { toFile } from '@noy-db/to-file'

export default {
  store:  toFile({ dir: process.env.NOYDB_DATA_DIR ?? './data' }),
  user:   process.env.NOYDB_USER ?? 'owner',
  secret: process.env.NOYDB_SECRET,
}

The matching .env template goes to stderr, so the redirect above keeps the two halves apart.

For TypeScript configs, run under a TS-capable runtime: npx tsx $(which noy-db) config validate foo.ts.

Live metrics

noy-db monitor <config> renders a live dashboard of operation counts and timings for a store that is already wrapped in to-meter — storage-side observability without touching record content. The config supplies the metered store; monitor no longer wraps it for you.

See also

• in-devtools · in-devtools-tui — the live-vault inspector pair that noy-db inspect opens.
• bundle — the .noydb container format pod inspect/pod verify/describe operate on.
• Where can noy-db run? — the topologies the scaffold profiles map to.