@nbt-dev/nbt

The nbt CLI and runtime for nbt-dev — a schema-first backend platform for web development.

Install

npm i -g @nbt-dev/nbt

Workflow

npx @nbt-dev/nbt init my-app         # scaffold a new project; vendors core auth into nbt/auth
npx nbt list                         # list available standard modules
npx nbt add crm email                # vendor standard cartridges into nbt/
npx nbt update crm email             # refresh vendored modules without deleting migrations
# ...edit nbt/<cart>/schema.nbt (entities, indexes, @route decls)…
npx nbt dev                          # boot the runtime + live-reload local carts on save
npx nbt migrate create billing -m "initial" --baseline # first migration from the schema
npx nbt status                       # what persistent changes are unrecorded?
npx nbt generate                     # typed TS clients for the local cartridge set

npx nbt config set-context prod --instance https://customer.nbt.dev
npx nbt config set-context local --instance http://127.0.0.1:8080
npx nbt config use-context prod      # select a named NbtInstance
npx nbt login                        # authenticate directly with that instance
npx nbt version                      # show client + selected console versions
npx nbt get cartridges               # kubectl-style instance inventory table
npx nbt get crm:Contact -o json      # paginated JSON for scripts and code agents
npx nbt get crm:Contact --limit 50 --offset 50  # bounded next page
npx nbt deploy                       # incremental plan + apply (non-production)
npx nbt deploy --env prod --plan     # stage an exact production plan
npx nbt deploy --env prod --apply <plan-id> --yes

Evals are authored as *.nbt.yaml manifests inside a cart and applied to an instance the same way, so what the assistant is measured against lives beside what it operates on:

npx nbt evals apply                  # compile this project's manifests, apply to the target
npx nbt evals apply --prune -f sales # and drop what the sales cart no longer ships
npx nbt evals get -o tree            # by `group` label, with each case's last result
npx nbt evals describe large-list-bounded   # resolves the fixtures and datasets it reuses
npx nbt evals run -l suite=ghl       # run locally in a real browser; records to the instance
npx nbt evals run --models a,b,c     # same cases per model; a side-by-side matrix
npx nbt evals run --gateway prod --max-cost 2.50   # spend prod's key, capped
npx nbt evals run --remote --follow  # queue it on the instance and watch a runner execute it
npx nbt evals runner                 # serve that queue: claim queued runs and execute them
npx nbt evals results --last         # per-case pass/fail, checks, judge score

apply recompiles first — the generated content/ artifacts are never applied stale. run needs the browser runner (NBT_EVALS), and posts its report to the target, so an instance accumulates the same history whether a run was triggered locally or on the console.

--models runs the selection once per model and records ONE run with a result per case per model, so nbt evals results tells them apart by a MODEL column. --gateway takes a URL or a context name and routes every model call — agent and judge — through that instance's gateway, so its sealed provider key spends and its ledger counts; the run records what it cost and the ceiling it ran under (--max-cost, itself capped by the console's NBT_EVAL_MAX_COST_MICROS).

--remote enqueues instead of executing; a nbt evals runner process — the same runner, in daemon form — claims the run and executes it over the identical code path. It refuses a target whose console or editor build differs from the one it would boot, since a score from a different build measures a different product (--allow-drift overrides, and says so). nbt doctor reports whether a runner has checked in and how deep the queue is.

Named instance contexts are stored in ~/.nbt/config.json; exact-origin credentials remain in ~/.nbt/credentials.json. Remote target precedence is explicit --instance or compatibility --host/--port, active context, then nbt.json.instance. Run from anywhere inside the project — nbt walks up to find nbt.json.

Entity lists are bounded to 50 records by default (maximum 200). JSON list output is an envelope with items, returned, limit, offset, hasMore, and nextOffset; use --offset to request the next page. Record-by-id JSON remains the record object itself.

Standard cartridges use a shadcn-style ownership model: nbt add <name> copies their source into your configured carts directory. The local copy is visible and editable, nbt generate follows that local cartridge set, and nbt deploy ships it to the configured runtime as one release.

Global plugins remain registry packages. A project that imports plugin entities declares an exact build/runtime dependency without moving the plugin under the project:

{
  "pluginDependencies": {
    "ghl": "0.1.1"
  }
}

nbt build resolves the pinned schema from a matching workspace checkout or the nbt.dev registry cache. nbt dev installs a matching workspace plugin before local carts. nbt deploy installs or forward-upgrades the exact registry release before applying dependent carts and refuses rollbacks.

npx nbt up                                  # boot using nbt.json dev port
npx nbt up --port 8080 --data-dir ./data    # explicitly override port/data dir
npx nbt up --help                           # daemon boot flags

Run npx nbt --help or npx nbt <command> --help for the full surface.

Platform

linux/x64 only for now. macOS / arm64 are not yet published.