Reference

<!-- Generated by notusbase/ops/reference.sh from the code. Do not edit: change the code or the texts in notusbase/reference/ and run the script. -->

Everything that exists, in one page: the commands and their options, what a function can call, the modules, the test kit, notusbase.json and every environment variable. The lists come from the code of this version, and a test keeps the page and the code equal. For how to use each piece, with the reasons, read the guide and the rules.

• Commands
• Functions
• Examples that run
• Modules
• Test kit
• notusbase.json
• Environment variables

Commands

notusbase <command> --help prints the same text, and notusbase help <topic> prints a part of this page from inside the binary, with the topics commands, functions, examples, modules, kit, config, variables and rules (the rules). A command that talks to a server (--url, --key, --dir) takes the address from --url, from NOTUSBASE_URL or from notusbase.json, and the deploy key from --key, from NOTUSBASE_DEPLOY_KEY or from the pb_data in --dir.

Options of every command

notusbase backup-check

Restores the backup alongside and compares it with the live database.

Asks the server that is up to prove its backup: it restores the backup beside the database and compares the copy with the live data, table by table, without stopping. On a large database it takes minutes. The server needs NOTUSBASE_BACKUP.

It prints the result as JSON and exits with an error when the check did not pass or gave up midway. The server also runs it by itself, once a day; --last prints the result of the last one, without running another.

notusbase backup-check [flags]

notusbase backup-check
notusbase backup-check --last
# where the dashboard and deploy are on a port of their own
notusbase backup-check --url http://localhost:8091

notusbase backup-s3-status

Shows what can be restored from the bucket.

Prints what the bucket holds, without a server: each chain with its segments, the size of its base, and the first and last instant it can restore to. It reads the NOTUSBASE_S3_* variables.

notusbase backup-s3-status

notusbase backup-s3-status

notusbase bundle

Only bundles, without deploying.

Bundles convex/ into one file, as notusbase deploy would send it, and stops there: no _generated, no tsc, no server. It prints nothing when all is well. The tests and the bench serve the file with NOTUSBASE_TEST_BUNDLE.

notusbase bundle [flags]

notusbase bundle
notusbase bundle --output tmp/bundle.js

notusbase capacity

Shows the database size against the limit, the growth, the writer and the next step.

Prints how far the server that is up is from its limits: the size of the database against the limit, how much it grows a day and when it reaches the limit, how busy the writer is, the open sessions, the size of each table, and the next step to take, when there is one. The growth needs NOTUSBASE_BACKUP on the server: each daily check of the backup stores one point.

notusbase capacity [flags]

notusbase capacity
# for a script
notusbase capacity --json

notusbase certificate

Lists the client certificates (name, subject, validity), as JSON, never the key.

Prints the client certificates stored on the server, as JSON: name, subject, issuer, notBefore, notAfter and sha256 of each. The key and the password never leave the server. notAfter is when to renew.

notusbase certificate [flags]

notusbase certificate

notusbase certificate remove

Deletes a certificate.

Deletes the certificate of that name from the server. It prints nothing, also when there was none. A function that asks for it fails from then on, saying how to store it again.

notusbase certificate remove <name>

notusbase certificate remove company

notusbase certificate set

Stores a PKCS#12 certificate (A1) for fetchWithCertificate and signXml. The password comes from the terminal or stdin.

Stores a client certificate (a PKCS#12 file, .pfx) on the server under a name, for the functions that call fetchWithCertificate and signXml with that name. The same name again replaces the file, and new requests use the new one.

The password of the file is never an argument: in a terminal it is asked for twice, without echo; otherwise it is read from stdin, one line. The server opens the file with it before storing, so a wrong password is refused. The name takes letters, digits, _ and -, and the file up to 64 KB. It prints what was stored, as notusbase certificate does.

notusbase certificate set <name> <file.pfx>

# asks for the password of the file
notusbase certificate set company ./company.pfx
# the password from a file, one line
notusbase certificate set company ./company.pfx < password.txt

notusbase check

Checks the database integrity.

Checks the integrity of the database file of a pb_data and prints ok, or what it found, exiting with an error. The server may be up. Use it instead of sqlite3, which does not know the functions the indexes of NotusBase use and cannot run the check.

Without --dir or NOTUSBASE_DIR it uses the dir of notusbase.json, in this folder or in one above (saying which file when it is above), or else pb_data here. A folder with no data.db is refused, with its full path: start the server there first (notusbase dev or serve), or pass the project's folder.

notusbase check [flags]

notusbase check
notusbase check --dir /var/lib/notusbase/pb_data

notusbase codegen

Generates the _generated folder.

Writes what the editor, tsc and an AI need to see the project as the binary does, without a server. Run it in the project folder; it prints nothing when all is well. It writes only what changed:

• convex/_generated, the types of api, internal and the data model, from the modules and schema.ts;
• node_modules/notusbase-modules, the modules inside the binary with their pages. npm install deletes that folder, which is why the postinstall of a project runs this command;
• kit.mjs, when a notusbase wrote it and nobody edited it; the rules between the marks of CLAUDE.md; and convex/tsconfig.json when it is missing.

notusbase dev and notusbase deploy do the same before bundling. It refuses components.* with no convex/convex.config.ts to install them, and an import of a module from a path that does not exist, saying the right one.

notusbase codegen [flags]

# after replacing the binary, or after npm install
notusbase codegen

notusbase copy

Copies production from its backup in one step: masked to develop, isolated to reproduce a bug or rehearse a deploy, or as the homologation.

Copies production from its backup (--backup, the folder of the chains, or --s3) into a new folder, in one step, and leaves it fit for one of three uses. Run it in the project folder.

• development: to develop with data that looks real. The personal data is always masked, and the copy starts with the engine of notusbase dev (redeploys on save), with email captured and fetch only to the names in NOTUSBASE_FETCH_HOSTS. It lives in ./tmp/copy-development-<date>; notusbase dev --dir starts it again.
• isolated: no crons, jobs, network, _env, backup or alerts. Real data unless --mask. --function runs the function that failed, with --args and --as (the id of the account). --rehearse runs deploy --plan, the deploy of this folder and the project's rehearse.mjs (with NOTUSBASE_REHEARSAL_URL and NOTUSBASE_REHEARSAL_DATA), prints a report and deletes the copy, also on failure. Real data loses exactly what staging loses (below), and is deleted at the end unless --keep.
• staging: the homologation, with real data unless --mask. It goes without the production rows of _env, the client certificates, the file and backup S3, SMTP and the OAuth2 client secrets, and with new token secrets; the shared rows of _env stay and are listed. It is prepared in --folder, not started: it runs as its own service with serve --env staging. --replace renews it, building the new copy beside the old one.

The mask replaces emails, phones, names, CPF and CNPJ by field name (and by the mask key of notusbase.json), empties credentials, sessions and _env, replaces the vectors of a vector index by random ones, and sweeps every other text for addresses, phones, documents and the values it replaced. Ids, dates, amounts and timestamps stay. A name typed in free text that no name field holds stays: the output lists those fields. The fakes reach nobody: @example.test addresses and phones that start with 10. Storage files do not come along in a masked copy.

The copy is marked: it never starts as production, and one with real data never starts as development. It refuses production's outlets in the environment (NOTUSBASE_ENV=production, SMTP, webhooks, alerts) and states the space it needs before it starts.

notusbase copy development|staging|isolated [flags]

# develop with production's data masked, from the bucket
notusbase copy development --s3
# the function that failed, with what the customer sent, as that customer, on a masked copy
notusbase copy isolated --mask --function tasks:create --args @args.json --as k17abc
# rehearse the deploy of this folder on a copy of the backup, deleted at the end
notusbase copy isolated --rehearse --backup /var/backups/notusbase
# the homologation on the production server, renewed over the old one
notusbase copy staging --backup /var/backups/notusbase --folder /srv/notusbase-staging --replace

notusbase cron

Lists the crons from crons.ts, with the next run and the last one.

Lists the crons of crons.ts on the server that is up, one per line: the name, the schedule, the next run and the last one, with the time in UTC. It changes nothing. --json prints the same as a list of objects. To run one now, use notusbase cron run.

notusbase cron [flags]

notusbase cron
# for a script
notusbase cron --json

notusbase cron run

Runs the cron now, without waiting for its time. The next occurrence follows the schedule. Shows the id of the job it created.

Runs a cron of crons.ts now, by its name, on the server that is up. It schedules one run for this moment, prints the id of the job, {"id":"..."}, and does not wait for it to end; the cron's next occurrence stays where it was. It is refused while the last run of that cron has not finished, and when the name is not in the deployed crons.ts. notusbase sql "select name, next from _crons" lists the names.

notusbase cron run <name>

notusbase cron run cleanup

notusbase deploy

Generates types, checks, bundles and deploys the functions; --rollback goes back to a saved deploy.

Sends the functions of this project to a server that is running. Run it in the project folder. In order:

1. writes convex/_generated and what follows the binary in the project, as notusbase codegen does;
2. runs tsc when the project has it in node_modules, and stops on a type error (--skip-typecheck skips it);
3. bundles convex/;
4. sends the bundle. The server checks the new schema.ts against the data that exists and refuses the deploy, changing nothing, when a document does not fit. Otherwise it creates tables, columns and indexes and swaps the code with no downtime.

It prints one plan: line for each thing it changed in the database, then version N live, or no change when the bundle is the one already live. A variable the code reads as process.env.NAME that has no value on the server is a warning; set it with notusbase env set.

--plan does steps 1 to 3, then asks the server what the deploy would change and what it would refuse. Nothing is deployed, and the command exits with an error when the deploy would be refused, so a script can test it.

The server keeps the last bundles. --history lists them, newest first, and --rollback deploys the previous one again, or the one whose number is given. A rollback passes through the same checks, gets a new version number, changes no data and does not touch the files in convex/: the next notusbase deploy sends your folder again. --rollback --plan shows what it would do.

The server is the one at --url, NOTUSBASE_URL or the url of notusbase.json, in that order. The key comes from --key or NOTUSBASE_DEPLOY_KEY; without them it is derived from the pb_data at --dir, which works on the server's own machine. A server on another machine has to be reached over https. Every command with these three options finds the server this way.

notusbase deploy [number] [flags]

# to the local server of notusbase.json
notusbase deploy
# what it would change in the database, deploying nothing
notusbase deploy --plan
# to another machine, with the key that `notusbase deploy-key` printed there
NOTUSBASE_DEPLOY_KEY=... notusbase deploy --url https://admin.example.com
# the saved bundles, then back to the previous one, or to one of them
notusbase deploy --history
notusbase deploy --rollback
notusbase deploy --rollback 12 --plan

notusbase deploy-key

Shows this pb_data's deploy key.

Prints the deploy key of a server, from its pb_data. Run it on the server's machine; no server has to be up, but it must have started once. The key opens everything the commands do: deploy, run, variables, export.

On the server's own machine the commands find the key without this. It is for another machine: put the output in NOTUSBASE_DEPLOY_KEY there, or pass it as --key. The key is derived from the secret in pb_data and does not change while that file stays.

Without --dir or NOTUSBASE_DIR it uses the dir of notusbase.json, in this folder or in one above (saying which file when it is above), or else pb_data here. A folder with no data.db is refused, with its full path: start the server there first (notusbase dev or serve), or pass the project's folder.

notusbase deploy-key [flags]

notusbase deploy-key
notusbase deploy-key --dir /var/lib/notusbase/pb_data

notusbase dev

Starts the server and redeploys the functions on every change.

The development server: run it in the project folder and leave it running. It writes convex/_generated, bundles convex/, starts the server with its data in pb_data and deploys. From then on every file saved in convex/ is deployed again, with the same checks as notusbase deploy, and the result is a line that starts with dev:. tsc runs after each deploy and only reports: a type error does not hold the deploy.

The address is the url of notusbase.json, or --http. The dashboard is at /_/ of the same address.

What it turns on that notusbase serve does not, all of it for development:

• the client receives the message and the stack of an error, and the console.log lines of the call;
• login with the users collection and open sign-up, unless NOTUSBASE_AUTH_COLLECTIONS is set (NOTUSBASE_SIGNUP=0 closes signup);
• actions may fetch this machine (127.0.0.1 and ::1), and any origin may call the server;
• no email is sent.

What dev deploys lives in memory. A notusbase serve on the same pb_data has no functions until a notusbase deploy.

notusbase dev [flags]

# in the project folder, until Ctrl-C
notusbase dev
# on another port, without changing notusbase.json
notusbase dev --http 127.0.0.1:3490

notusbase env

Lists the variables and the environment of each. The values only come with --values.

Lists the variables on the server, one row per line: the name and the environment it belongs to (production, staging, development, or all for a row every environment sees). They are what the functions read as process.env.NAME. The values only come with --values, as the ones this server uses; mind where the output goes. --env shows the rows of one environment.

env set and env remove take effect on the next call of a function, with no deploy and no restart. The code loads again for it, so a value a file copied from process.env when it loaded is the new one too, and so is the key of a client created at the top of a file. Calls already running finish as they were. The first call in each isolate after the change pays for loading the code.

notusbase env [flags]

notusbase env
notusbase env --env staging
notusbase env --values --url https://admin.example.com

notusbase env list

The same as notusbase env.

The same as notusbase env.

notusbase env list [flags]

notusbase env list --env production

notusbase env remove

Deletes a variable, in the server's environment or the one in --env.

Deletes one variable from the server, in the environment the server runs as, or the one in --env. A function that reads it gets undefined, or the shared row, from the next call on.

notusbase env remove <name>

notusbase env remove STRIPE_SECRET_KEY
notusbase env remove --env all APP_URL

notusbase env set

Sets a variable, in the server's environment or the one in --env. Without the value on the command line, where it would stay in the shell history, it is asked for in the terminal or read from stdin: notusbase env set KEY < key.txt.

Sets one variable on the server, replacing the value it had, in the environment the server runs as, or the one in --env (all for a row every environment sees). When a name has both, the row of the server's environment wins. The next call of a function already reads it as process.env.NAME: no deploy, no restart.

Without the value on the command line, where it would stay in the shell history, it is asked for in the terminal or read from stdin.

notusbase env set <name> [value]

notusbase env set STRIPE_SECRET_KEY < key.txt
notusbase env set --env staging STRIPE_SECRET_KEY sk_test_123
notusbase env set --env all APP_URL https://app.example.com --url https://admin.example.com

notusbase export

Saves tables and files to a zip in the npx convex export format.

Saves the data of the server that is up to a zip, in the format of npx convex export: one folder for each table of the deployed schema.ts, with its documents as JSON lines, the stored files, and the tables of each Convex component under _components/<name>/. It is read at one instant, while the server keeps serving. It prints the file and its size.

Left out: the accounts of the login collection, the variables, the certificates and what is scheduled.

The zip goes into another NotusBase with notusbase import, and into Convex with npx convex import.

notusbase export <file.zip> [flags]

notusbase export backup.zip
notusbase export backup.zip --url https://admin.example.com

notusbase import

Loads a zip from notusbase export or npx convex export. Without --replace, the tables must be empty.

Loads a zip into the server that is up: one from notusbase export, or one from npx convex export, with the same ids, references and files. Deploy first: each table of the zip has to be in the deployed schema.ts. The documents go in one transaction, all or none, and the files after it.

Without --replace each table of the zip has to be empty on the server. With it, the tables that are in the zip are emptied and loaded again; the others are not touched.

The tables of a Convex component (_components/<name>/ in the zip) go into that component's own tables when convex/convex.config.ts installs it, with the same ids; notusbase export writes them back the same way.

What the server does not take is named and nothing is loaded: a table outside schema.ts, a Convex system table, the tables of a component the project does not install. --skip leaves tables and components out.

It prints how many documents went into each table, the files, and what was skipped.

notusbase import <file.zip> [flags]

# into empty tables
notusbase import backup.zip
# over what is there, in the tables of the zip
notusbase import backup.zip --replace
# a Convex export: without the login tables, and without a component the project does not install
notusbase import convex.zip --skip authAccounts,authSessions,_components/resend

notusbase init

Create a project: schema, a query, a mutation, a test, tsconfig and package.json.

Writes a project into the folder (the current one, when none is given) and prints the next steps. It installs nothing and starts no server: npm install comes next.

The plain project is package.json, notusbase.json, convex/schema.ts with one table, convex/tasks.ts with a query and a mutation, convex/tsconfig.json, kit.mjs and a test.mjs that npm test runs. It also gets .gitignore, CLAUDE.md (the rules for writing a system, for an AI) and .mcp.json, when the folder does not have them, and convex/_generated.

It overwrites nothing. When one of its files is already in the folder it stops, names them and creates none.

--port is the port of the local server, written as the url of notusbase.json: notusbase dev listens there and the other commands find the server there. Give each project on the same machine its own.

notusbase init [dir] [flags]

# a new project in a new folder
notusbase init my-app
# with its server on another port
notusbase init my-app --port 3490
# in the current folder
notusbase init

notusbase job

Lists the scheduled functions (runAfter, runAt, crons), with the id that job run takes.

Lists the scheduled functions on the server that is up (runAfter, runAt and the runs of crons), with the id that notusbase job run takes. --view picks which: scheduled (pending and running, the default), failed, done or canceled; --function keeps the jobs of one function. It changes nothing. --json prints a list of objects.

notusbase job [flags]

notusbase job
# the ones that failed, of one function
notusbase job --view failed --function tasks:create

notusbase job run

Brings a pending job to now, without waiting for its time. The id comes from notusbase job.

Brings one scheduled run (runAfter, runAt) to now, by its id, on the server that is up. Only a pending job moves: one that started, ended or was cancelled is refused. The id is on the dashboard, in Logs → Scheduled, and notusbase cron run prints the one it creates.

notusbase job run <id>

notusbase job run 0193a5c2e4b87d10

notusbase logs

Follows the functions live. With --since, shows the past, from pb_data/notusbase.log, and exits; with the local server stopped, reads the file in --dir. Times in UTC.

Prints what the functions wrote with console.log and the errors they threw, one line each: the time in UTC, module:function and the text.

Without --since it follows the server live, from now on, until Ctrl-C. With --since it reads the past from the log the server keeps on disk, prints the last --limit lines that match, oldest first, and exits. --since takes 30m, 1h, 2d or a date in RFC 3339.

--function keeps one function (tasks:create) or one module (tasks). --text keeps the lines with that text. An error the client received as [Request ID: ...] Server Error can be pasted whole in --text: the id finds the line with the detail.

notusbase logs [flags]

# live, until Ctrl-C
notusbase logs
# the last hour of one module
notusbase logs --since 1h --function tasks --limit 50
# the detail of an error the client received
notusbase logs --since 1d --text '[Request ID: 3f9c2a7d81e04b56] Server Error'

notusbase mcp

Development MCP server, for an AI to see and work with the local server: functions, schema, logs, run, SQL, schedule, deploy and rollback. Speaks MCP over stdin and stdout; needs Node.

Starts the development MCP server, for an AI that writes the system to see the local server and work with it. An MCP client runs this command and speaks to it over stdin and stdout: notusbase init writes the .mcp.json that tells it so. It needs Node 22 or newer.

It only talks to a server on this machine, the one of notusbase.json, and refuses any other address. Its tools list the functions and the schema, read the logs, run a function, read the database with SQL, show the names of the variables, show and run what is scheduled, deploy and roll back, and print these pages (docs). All but docs need notusbase dev up.

notusbase mcp

# what an MCP client runs, in the project folder
notusbase mcp

notusbase metrics-key

Shows the key that only opens the metrics.

Prints the key that opens only the metrics of a server (/api/notusbase/metrics, in the Prometheus format), from its pb_data. It is the one to give to a monitor, which then cannot deploy or read data. Run it on the server's machine, after the server has started once.

Without --dir or NOTUSBASE_DIR it uses the dir of notusbase.json, in this folder or in one above (saying which file when it is above), or else pb_data here. A folder with no data.db is refused, with its full path: start the server there first (notusbase dev or serve), or pass the project's folder.

notusbase metrics-key [flags]

notusbase metrics-key
notusbase metrics-key --dir /var/lib/notusbase/pb_data

notusbase promote

Turns the replica into the new primary and starts the server.

Turns the replica in that folder into the primary. It refuses when the primary still answers, when there is no address to check it (--primary or NOTUSBASE_ALERT_PRIMARY), when the standby's check failed, when what came by the direct copy does not apply, when a stored file a row points to is missing here (--accept-missing-files goes on without them), or when another server writes to the bucket: once the replica stops, promote watches the primary's beat for its write lease plus 2 s (about 32 s). --force skips the watch, not the wait, never the bucket. Of two promotions at once the second refuses; a provider without If-None-Match cannot promote. It stops the replica, takes the bucket from the old primary, applies what is left from the bucket and the direct copy, checks the database and starts notusbase serve with the options after --. The old primary stops on reading the new epoch; until then its client writes are lost. Cut off from the bucket, it stops when its write lease runs out (30 s with a direct standby; promote waits for it), else never. A planned switchover loses nothing: stop the primary cleanly (it sends its last point and files to the bucket, marked final), then --planned refuses unless the standby has that point before the epoch and the primary did not start again since.

There is no way back: promoting by mistake takes a healthy primary down. It needs NOTUSBASE_BACKUP, for the new primary to have a backup from its first minute. --no-serve prepares the folder and stops there. --check quick runs quick_check before serving and integrity_check after. Once the server listens it runs NOTUSBASE_PROMOTE_HOOK, which moves the route; if the hook fails, promote again on the folder redoes it.

notusbase promote <dir> [-- serve options] [flags]

# after --, the options the old primary's serve had
notusbase promote /var/lib/notusbase/replica -- --http 127.0.0.1:8090 --admin-http 127.0.0.1:8091
# only prepare the folder
notusbase promote /var/lib/notusbase/replica --no-serve

notusbase replica

Follows the bucket as a standby server, serving nothing.

Keeps a standby copy of a server in a folder, fed by the bucket the primary writes to. It runs until it is stopped and serves nothing: no functions, no dashboard, no crons. It reads the same NOTUSBASE_S3_* variables as the primary. The folder is the replica's own and must not hold a database.

With NOTUSBASE_ALERT_PRIMARY set, it also watches the primary and receives from it directly, a fraction of a second behind instead of the bucket's minutes; the bucket still gives it the base of each chain.

notusbase replica-status shows how far behind it is, and notusbase promote turns it into the primary.

notusbase replica <dir>

notusbase replica /var/lib/notusbase/replica

notusbase replica-status

Shows the replica lag.

Prints where the replica is: the last point it applied and how long ago, the last point in the bucket, the last contact with the bucket, its last check, and whether the direct copy was in step at the primary's last answer. It reads only the folder, so it works with the bucket out of reach.

notusbase replica-status <dir>

notusbase replica-status /var/lib/notusbase/replica

notusbase restore

Rebuilds the database, the files, the published code and the deploy key from NOTUSBASE_BACKUP.

Rebuilds a database from the local backup, the folder a server writes with NOTUSBASE_BACKUP. No server is involved: it reads the first folder and writes the second, which must not have a data.db. Without --until it goes to the last point of the backup; with it, to that instant.

It prints the chain it restored from and how many stored files came back, and checks the integrity of the result. The new folder is then a pb_data: start it with notusbase serve --dir. The deployed bundle comes back too. So does .notusbase_secret, from which the deploy key is derived: into a folder with no secret it brings the key of the server the backup came from, and says so with a warning. That is right for the same server coming back and wrong for a copy: a production backup restored into staging would carry the production key. For a copy, --new-secret gives the folder a key of its own and leaves the backup's out. --with-secret matters only when the folder already has a secret, and replaces it.

notusbase restore <backup dir> <new dir> [flags]

notusbase restore /var/backups/notusbase pb_data.new
# a copy of production for staging, with a deploy key of its own
notusbase restore /var/backups/notusbase pb_data.staging --new-secret
# as it was at an instant
notusbase restore /var/backups/notusbase pb_data.new --until 2026-11-06T12:00:00Z

notusbase restore-check

Restores the newest backup into a new folder, compares it with the live database and starts it isolated.

Asks the server that is up to prove that its backup restores: it runs restore of the newest local chain and, with S3, restore-s3 downloading for real, each into a new folder; compares the copy with the live database the same way as backup-check; checks the _storage files by size and SHA-256; starts the copy in isolated mode until it answers; and deletes the folder. It runs at low priority and needs free disk for a copy of the database (twice that with S3); without it, it does not run and says so. The server needs NOTUSBASE_BACKUP.

It prints the result as JSON and exits with an error when the check did not pass or ended without a verdict. The server also runs it by itself, once a week (NOTUSBASE_RESTORE_CHECK_HOURS); --last prints the last attempt and when one last passed, without running another.

notusbase restore-check [flags]

notusbase restore-check
notusbase restore-check --last

notusbase restore-s3

Rebuilds the database and files from the bucket.

Rebuilds a server's data from the bucket, on a new machine or after a lost disk: the database, the stored files, the secret and the deployed bundle, so the deploy key stays the same, with a warning saying so. For a copy that is not that server, --new-secret gives the folder a key of its own instead. The folder must not have a database. It reads the same NOTUSBASE_S3_* variables as the server that wrote the backup, the key that seals it (NOTUSBASE_S3_KEY) among them.

Without --until it goes to the last point in the bucket; with it, to that instant. It ends by printing the point it reached. The folder is then a pb_data: start it with notusbase serve --dir.

notusbase restore-s3 <new dir> [flags]

notusbase restore-s3 /var/lib/notusbase/pb_data
notusbase restore-s3 /new/folder --until 2026-11-06T12:00:00Z

notusbase run

Runs a function, including internal ones, and prints its answer as JSON; if the function fails, exits with 1. A large argument comes from @file or, with -, from stdin. With --as, runs as a user.

Runs a deployed function on the server and prints what it answered, as JSON. It runs as the administrator: internal functions too, and ctx.auth has no user. A mutation really writes and an action really runs.

The argument is one JSON object. Without it the function gets {}. @file reads the object from a file, and - from stdin, for one too large for a command line.

It prints {"status":"success","value":...}, or {"status":"error","errorMessage":...} when the function threw; under notusbase dev the message carries the detail and the console.log lines come along. The exit code tells whether the server took the call, not whether the function passed: read status.

notusbase run <module:function> [JSON args | @file | -] [flags]

notusbase run tasks:list
notusbase run tasks:create '{"text": "hi"}'
# a large argument, from a file or from stdin
notusbase run imports:load @args.json
cat args.json | notusbase run imports:load -

notusbase serve

Starts the web server (default to 127.0.0.1:8090 if no domain is specified).

The server as it runs in production: it serves the functions that the last notusbase deploy sent and the dashboard at /_/, and never watches a folder. It needs no project folder, only its data, pb_data or --dir. Without --http the address is the url of notusbase.json when there is one, or 127.0.0.1:8090.

On 127.0.0.1 everything is on one port. An address that others reach is refused unless the dashboard, the deploy and the metrics are moved to a port of their own with --admin-http; behind a reverse proxy it also takes --behind-proxy and --origins. The refusal says which option is missing.

Signup is closed on every start, and login only counts for the collection named in NOTUSBASE_AUTH_COLLECTIONS (users). An error reaches the client as [Request ID: ...] Server Error, and the detail goes to notusbase logs. notusbase help variables lists what else the environment sets: backup, limits, alerts.

The first start prints no superuser: notusbase superuser upsert creates the one who opens the dashboard.

notusbase serve [domain(s)]

# on this machine, one port
notusbase serve
# login with the users collection, on a port of its own
NOTUSBASE_AUTH_COLLECTIONS=users notusbase serve --http 127.0.0.1:3490
# behind a reverse proxy on the same machine: the apps on one port, the dashboard and deploy on another
notusbase serve --http 127.0.0.1:8090 --admin-http 127.0.0.1:8091 --behind-proxy --origins https://example.com

notusbase sql

Reads the database with SQL, read-only and with a time limit; to avoid competing for CPU, use nice.

Reads the database with one SQL statement and prints one JSON object for each row, one per line. It opens the file in pb_data (--dir) itself, read-only, so it works with the server up or stopped, and only on the server's machine. Anything that writes is refused, and so is reading a secret: the values in _env, the password and tokenKey of the login collections, _params.value (settings, SMTP password included), _collections.options (token secrets), _otps.password and the _certificates table. Name the other columns instead of *.

Each table of schema.ts is a table with the same name; a field that is optional, a union or an object is stored as JSON, read with json_extract. The tables of NotusBase start with _: _crons, _jobs, _storage.

A query is cut at --timeout and at --max-rows. A long read on a live database holds back its maintenance: for a heavy report, query a restored copy instead.

Without --dir or NOTUSBASE_DIR it uses the dir of notusbase.json, in this folder or in one above (saying which file when it is above), or else pb_data here. A folder with no data.db is refused, with its full path: start the server there first (notusbase dev or serve), or pass the project's folder.

notusbase sql <query> [flags]

notusbase sql "select count(*) from tasks"
# the crons the server knows, and when each runs next
notusbase sql "select name, next from _crons"
notusbase sql "select * from tasks" --max-rows 100 --timeout 30s

notusbase superuser

Manage superusers.

notusbase superuser create

Creates a new superuser.

notusbase superuser create EMAIL [PASSWORD]

# the password is asked for in the terminal, or read from stdin
notusbase superuser create [email protected]

notusbase superuser delete

Deletes an existing superuser.

notusbase superuser delete

notusbase superuser delete [email protected]

notusbase superuser ips

Updates the superuser IPs whitelist setting (the IPs/subnets arguments must be space separated; leave empty to clear the whitelist restriction).

notusbase superuser ips

# only these addresses may sign in as a superuser; with no address, any may
notusbase superuser ips 127.0.0.1 10.0.0.0/24
notusbase superuser ips

notusbase superuser otp

Creates a new OTP for the specified superuser.

notusbase superuser otp

# a one-time code to sign in to the dashboard as that superuser
notusbase superuser otp [email protected]

notusbase superuser update

Changes the password of a single superuser.

notusbase superuser update EMAIL [PASSWORD]

# the password is asked for in the terminal, or read from stdin
notusbase superuser update [email protected]

notusbase superuser upsert

Creates, or updates if email exists, a single superuser.

The superuser is who opens the dashboard at /_/. It goes into the database in pb_data, which the server creates on its first start: run this in the project's folder, or in one under it, or point --dir at the server's pb_data. The other superuser commands find the folder the same way.

Without --dir or NOTUSBASE_DIR it uses the dir of notusbase.json, in this folder or in one above (saying which file when it is above), or else pb_data here. A folder with no data.db is refused, with its full path: start the server there first (notusbase dev or serve), or pass the project's folder.

notusbase superuser upsert EMAIL [PASSWORD]

# creates the owner of the dashboard, or changes the password; it asks for the password
notusbase superuser upsert [email protected]
notusbase superuser upsert [email protected] --dir /var/lib/notusbase/pb_data

notusbase user

Accounts in the login collection.

notusbase user add

Creates an account in the login collection, even with signup closed. The password comes from the terminal or stdin.

Creates an account for someone who signs in to your system, in the login collection (users), already verified. It works with sign-up closed, which is how notusbase serve starts. The server has to be up.

The password is never an argument. In a terminal it is asked for twice, without echo; otherwise it is read from stdin, one line. It prints account EMAIL created in COLLECTION.

It is refused when the server counts no collection as login (start it with NOTUSBASE_AUTH_COLLECTIONS=users; notusbase dev already does) and when the account exists: the password is then changed in the dashboard. The owner of the server is another thing, notusbase superuser.

notusbase user add <email> [flags]

# asks for the password
notusbase user add [email protected]
# the password from a file, one line
notusbase user add [email protected] < password.txt

notusbase vacuum

Compacts the database, with the server stopped. Search is rebuilt at startup.

Compacts the database of a pb_data; from then on the running server gives deleted space back by itself. Stop the server first. Search is rebuilt when it starts.

Without --dir or NOTUSBASE_DIR it uses the dir of notusbase.json, in this folder or in one above (saying which file when it is above), or else pb_data here. A folder with no data.db is refused, with its full path: start the server there first (notusbase dev or serve), or pass the project's folder.

notusbase vacuum [flags]

notusbase vacuum
notusbase vacuum --dir /var/lib/notusbase/pb_data

notusbase version

Shows the binary version.

Prints one line, notusbase VERSION, PocketBase VERSION. It needs no project and no server.

notusbase version [flags]

notusbase version

Functions

What a function receives and what it imports. The API is Convex's: the convex package of the project gives the types and the client, and the server answers the same calls. Each table lists the names the running code has; "In" says which kind of function has it. Where the behavior differs from Convex, Migrating from Convex says how, and Limits per function has the ceilings.

The context: ctx

The first argument of every handler.

ctx.db

Every method that takes an id also takes the table first, as in the newer versions of Convex: get(id) or get("tasks", id). The second form fails when the id is from another table.

ctx.db.query(table)

A read is a chain: where to read from (withIndex, withSearchIndex or the whole table), then filter and order, and one method that ends it. Nothing is read until the last one. The chain can also be consumed with for await.

The index range: withIndex(name, (q) => ...)

The q of withIndex. The fields come in the order of the index: zero or more eq, then at most one lower and one upper bound on the next field.

The search filter: withSearchIndex(name, (q) => ...)

The q of withSearchIndex. One search, then eq on the index's filterFields. The words are joined by OR, the last one also matches as a prefix, case and accents do not count, and up to 16 words count. As in Convex, a search reads its 1,024 best results, and .filter() runs on those: asking for more outside paginate (a take above what they give, a collect, or a for await that goes past them) fails with "Search query scanned too many documents (fetched 1024)", and the pages end there. A subscription to a search runs again on any write to a row its eq filters select, before or after the write, whether or not the row has the words: wider than Convex, which runs it again only for a row that matches the search.

The filter: .filter((q) => ...)

The q of filter. Every method takes values or other expressions and returns an expression.

ctx.db.system

Two tables: _scheduled_functions, with what ctx.scheduler created, and _storage, with the files. Read only.

ctx.auth

ctx.scheduler

In a mutation the job is part of the transaction: if the mutation fails, nothing was scheduled.

ctx.storage

ctx.meta

convex/server

What import ... from "convex/server" gives inside convex/. The server answers this import itself. The functions themselves (query, mutation, action, the internal ones and httpAction) are imported from ./_generated/server, which notusbase dev writes with the types of your schema.

defineTable(...)

Each method returns the table, so they chain. The server creates tables, columns and indexes at startup and on deploy, and never drops a table or a column.

cronJobs()

convex/crons.ts exports the list as default. Every method takes a name, unique in the file, the schedule, the function and its arguments. Times are UTC.

httpRouter()

convex/http.ts exports the router as default. The routes answer on the public port, at the root.

convex/values

This import is the convex package of the project, unchanged. The list is from the version the tests use, 1.49.0.

Validators: v

Used in args:, in returns: and in the fields of defineTable. A value that does not match stops the call with ArgumentValidationError or ReturnsValidationError, and stops a write with the name of the field.

Examples that run

Each block below is a function from notusbase/reference/examples.ts. The test suite deploys the file on a real engine and, for each example, calls seed and then the function with {}, and compares what comes back with the // => line. An example that stops working fails the suite. All of them use this schema and this beginning of file:

// convex/schema.ts
export default defineSchema({
  things: defineTable({ n: v.number(), text: v.string(), tags: v.optional(v.record(v.string(), v.number())) })
    .index("by_n", ["n"]).searchIndex("by_text", { searchField: "text", filterFields: ["n"] }),
});

// convex/examples.ts
import { paginationOptsValidator } from "convex/server";
import { ConvexError, v } from "convex/values";
import { api, internal } from "./_generated/api";
import { action, internalMutation, mutation, query } from "./_generated/server";

export const seed = mutation({
  args: {},
  handler: async (ctx) => {
    for (const thing of await ctx.db.query("things").collect()) await ctx.db.delete(thing._id);
    await ctx.db.insert("things", { n: 1, text: "a red apple" });
    await ctx.db.insert("things", { n: 2, text: "a green apple", tags: { fresh: 1 } });
    await ctx.db.insert("things", { n: 3, text: "a blue door" });
  },
});

export const sweep = internalMutation({
  args: { below: v.number() },
  handler: async (ctx, { below }) => {
    const old = await ctx.db.query("things").withIndex("by_n", (q) => q.lt("n", below)).take(100);
    for (const thing of old) await ctx.db.delete(thing._id);
    return old.length;
  },
});

Reading through an index

The range goes inside withIndex, so only the documents in it are read. order and take come after.

export const fromTwo = query({
  args: {},
  handler: async (ctx) => {
    const things = await ctx.db.query("things").withIndex("by_n", (q) => q.gte("n", 2)).order("desc").take(10);
    return things.map((thing) => thing.n);
  },
});
// => [3, 2]

first, unique and filter

first and unique return null when nothing matches. filter runs on each document the index gave.

export const one = query({
  args: {},
  handler: async (ctx) => {
    const lowest = await ctx.db.query("things").withIndex("by_n").first();
    const two = await ctx.db.query("things").withIndex("by_n", (q) => q.eq("n", 2)).unique();
    const none = await ctx.db.query("things").withIndex("by_n", (q) => q.eq("n", 9)).unique();
    const doors = await ctx.db.query("things").filter((q) => q.eq(q.field("text"), "a blue door")).collect();
    return { lowest: lowest?.n, two: two?.text, none, doors: doors.length };
  },
});
// => {"lowest": 1, "two": "a green apple", "none": null, "doors": 1}

Pages

One paginate per query. The client sends cursor: null first and then the continueCursor it received; usePaginatedQuery does this by itself.

export const page = query({
  args: { paginationOpts: paginationOptsValidator },
  handler: async (ctx, { paginationOpts }) => {
    return await ctx.db.query("things").withIndex("by_n").paginate(paginationOpts);
  },
});

export const twoPages = action({
  args: {},
  handler: async (ctx): Promise<{ first: number[]; firstIsDone: boolean; second: number[]; secondIsDone: boolean }> => {
    const first = await ctx.runQuery(api.examples.page, { paginationOpts: { numItems: 2, cursor: null } });
    const second = await ctx.runQuery(api.examples.page, { paginationOpts: { numItems: 2, cursor: first.continueCursor } });
    return { first: first.page.map((t) => t.n), firstIsDone: first.isDone, second: second.page.map((t) => t.n), secondIsDone: second.isDone };
  },
});
// => {"first": [1, 2], "firstIsDone": false, "second": [3], "secondIsDone": true}

Text search

The index is declared with searchIndex in the schema. The result comes with the best match first.

export const apples = query({
  args: {},
  handler: async (ctx) => {
    const found = await ctx.db.query("things").withSearchIndex("by_text", (q) => q.search("text", "apple")).take(10);
    return found.map((thing) => thing.n).sort();
  },
});
// => [1, 2]

Text search with a filter and a limit

eq narrows to a field listed in filterFields, and take stops at the limit.

export const greenApple = query({
  args: {},
  handler: async (ctx) => {
    const found = await ctx.db.query("things").withSearchIndex("by_text", (q) => q.search("text", "apple").eq("n", 2)).take(1);
    return found.map((thing) => thing.text);
  },
});
// => ["a green apple"]

Ids

An id is a string that starts with the name of its table. normalizeId checks a string that came from outside.

export const ids = query({
  args: {},
  handler: async (ctx) => {
    const thing = (await ctx.db.query("things").first())!;
    return {
      startsWithTable: thing._id.startsWith("things:"),
      same: ctx.db.normalizeId("things", thing._id) === thing._id,
      otherTable: ctx.db.normalizeId("things", "users:abc"),
      byTable: (await ctx.db.get("things", thing._id))?.n,
    };
  },
});
// => {"startsWithTable": true, "same": true, "otherTable": null, "byTable": 1}

patch, v.record and returns

patch keeps the fields it does not name. returns is checked like args: a value outside it fails the call.

export const tag = mutation({
  args: {},
  returns: v.object({ tags: v.record(v.string(), v.number()), text: v.string(), hasN: v.boolean() }),
  handler: async (ctx) => {
    const thing = (await ctx.db.query("things").withIndex("by_n", (q) => q.eq("n", 2)).unique())!;
    await ctx.db.patch(thing._id, { tags: { ...thing.tags, ripe: 2 } });
    const after = (await ctx.db.get(thing._id))!;
    return { tags: after.tags!, text: after.text, hasN: "n" in after };
  },
});
// => {"tags": {"fresh": 1, "ripe": 2}, "text": "a green apple", "hasN": true}

An error the client can read

Only ConvexError carries data to the client. Here the function catches its own error to show what the client gets in error.data.

export const refuse = query({
  args: {},
  handler: async () => {
    try {
      throw new ConvexError({ code: "NOT_ALLOWED", reason: "not a member" });
    } catch (error) {
      return error instanceof ConvexError ? error.data : null;
    }
  },
});
// => {"code": "NOT_ALLOWED", "reason": "not a member"}

Running later

The job is created in the same transaction as the write. ctx.db.system shows it waiting.

export const later = mutation({
  args: {},
  handler: async (ctx): Promise<{ name: string; args: unknown[]; state: string }> => {
    const id = await ctx.scheduler.runAfter(60_000, internal.examples.sweep, { below: 2 });
    const job = (await ctx.db.system.get(id))!;
    return { name: job.name, args: job.args, state: job.state.kind };
  },
});
// => {"name": "examples.js:sweep", "args": [{"below": 2}], "state": "pending"}

Calling one function from another

Inside a mutation, runMutation and runQuery are part of the same transaction.

export const sweepNow = mutation({
  args: {},
  handler: async (ctx) => {
    const removed: number = await ctx.runMutation(internal.examples.sweep, { below: 3 });
    const left: number[] = await ctx.runQuery(api.examples.fromTwo, {});
    return { removed, left };
  },
});
// => {"removed": 2, "left": [3]}

An action

An action has no ctx.db: it reads and writes through other functions, each in a transaction of its own.

export const fromOutside = action({
  args: {},
  handler: async (ctx): Promise<number[]> => {
    await ctx.runMutation(internal.examples.sweep, { below: 2 });
    return await ctx.runQuery(api.examples.fromTwo, {});
  },
});
// => [3, 2]

Crons

A convex/crons.ts with a default export. After the deploy, the test finds both names in the server's cron table.

import { cronJobs } from "convex/server";
import { internal } from "./_generated/api";

const crons = cronJobs();
crons.interval("every five minutes", { minutes: 5 }, internal.examples.sweep, { below: 0 });
crons.cron("weekdays at nine", "0 9 * * 1-5", internal.examples.sweep, { below: 0 });
export default crons;

Modules

Modules ship inside the binary and enter a project in three steps: the tables in convex/schema.ts (import { xTables } from "notusbase-modules/x/schema"), a file convex/x.ts with export * from "notusbase-modules/x", and the route in convex/http.ts when the module has one. A module that is not enabled creates no table and does not enter the bundle.

The lists are the export lines of each module, with the comment the source has above each one. How to use a module, with examples, is in its README.

certificates

Client certificate (A1) for banks and government APIs: fetch with mutual TLS and XML signatures. A library: no tables, no functions. README.

• fetchWithCertificate(): fetch that presents a stored client certificate in the TLS handshake (mutual TLS). Same arguments and result as fetch. Actions only.
• signXml(): Signs an XML document with a stored certificate: enveloped XMLDSig, RSA-SHA256, C14N 1.0, the certificate in KeyInfo, Signature without a prefix. Returns the signed document. Actions only.

email

Transactional email written in the mutation's transaction and sent through the queue, by the panel's SMTP or Resend; under notusbase dev it is captured in the table. Templates with typed variables, a shared layout and a preview in the panel. README.

• new Html(readonly value: string): HTML that is already safe: what html, raw and button return. Anything else interpolated in html is escaped.
  • .toString(): The HTML text, so an Html can go wherever a string goes.
• escapeHtml(): Escapes & < > " ' so a value can go into HTML text or a quoted attribute.
• html(): Tagged template for email HTML. Every interpolated value is escaped, except what is already Html (another html, raw, button). Arrays are joined, and null, undefined and false print nothing, so a list mapped to html pieces and a piece behind cond && both work.
• raw(): Marks a text as HTML that goes in as it is, without escaping. Only for HTML you wrote, never for a variable.
• button(): A link that looks like a button in every email client (a table with inline styles). The URL must start with http://, https:// or mailto:; anything else throws, so a javascript: from a variable never becomes a link.
• layout(): The default layout: a centered card 560 px wide, with name at the top and footer at the bottom, inline styles only (email clients drop <style>), and the hidden preheader that inboxes show next to the subject.
• template(): Declares a template. Keep it in any file and list it in new Email({ templates: { name: template } }).
• new Email(private options: EmailOptions<T> = {}): Transactional email. send writes the request to email_messages in the caller's transaction and queues the delivery, with retries, through SMTP (the panel's) or Resend, chosen by the EMAIL_PROVIDER app variable. Under notusbase dev, and on a server outside production (--env), nothing goes out: the email stays captured in the table. Enabling: it needs the queue module too. Spread queueTables and emailTables (from notusbase-modules/queue/schema and notusbase-modules/email/schema) into defineSchema, and create convex/queue.ts (export * from "notusbase-modules/queue";) and convex/email.ts (export * from "notusbase-modules/email";). No http route.
  • .send(): Writes the request and joins the queue. Runs in a mutation or action. In a mutation it is the mutation's transaction: if the mutation fails, nothing goes out. In an action it is a mutation of its own. Returns the document id in email_messages. With template, renders that template with data in the layout first; data is required here, the example only serves render and the preview. Throws on an invalid address, subject, sender, size (512 KiB) or template variable, or if the queue module is not enabled.
  • .render(): Renders a template without sending: { subject, html, text?, preheader? }. data defaults to the template's example. Runs anywhere, also in a test. Throws on an unknown name or a variable that does not match args.
  • .previews(): The two internal queries the dashboard's Email screen calls: templates lists the names, variables and examples, and preview renders one. Export them from convex/email.ts, next to the module.
  • .status(): Returns the EmailStatus of a message, or null if it does not exist. Runs in a query, mutation or action.
• Values: passwordReset, accountInvite
• Functions the module registers, called through the exports above and with notusbase run, never by a client: email:enqueue, email:get, email:status, email:list, email:attempt, email:finish, email:completed, email:reportFailure, email:deliver

queue

Queue with a parallelism limit, retries with growing backoff and a notification on completion. README.

• vOnCompleteArgs(): Argument validators for the onComplete mutation: { workId, context, result }. Pass the validator of the context you gave to enqueue*.
• new Queue(...): Work queue: limits how many tasks run together, retries with growing backoff and tells you when a task ends. Enqueueing is part of the caller's transaction: if the mutation rolls back, the task never existed. Enabling: spread queueTables (from notusbase-modules/queue/schema) into defineSchema, and create convex/queue.ts with export * from "notusbase-modules/queue";. No http route.
  • .enqueueAction(): Enqueues an action and returns the task id. Runs in a mutation or action. The function is stored by name. Options: retry (overrides the queue's), onComplete (a mutation that receives { workId, context, result }), context (passed to onComplete), runAfter (ms from now) or runAt (timestamp). With retry, the action runs at least once, so it has to be idempotent.
  • .enqueueMutation(): Enqueues a mutation and returns the task id. Same options as enqueueAction. The mutation runs exactly once, in the same transaction that marks the task done; a failure undoes everything it did.
  • .cancel(): Cancels a task. A pending one leaves at once; one that already started finishes, with no retry. Runs in a mutation or action. Returns nothing.
  • .cancelAll(): Cancels the queue's pending tasks. Runs in a mutation or action. Tasks already running are not touched.
  • .status(): Returns the task's TaskStatus (pending, running, success, failed or canceled, with attempts), or null if it no longer exists. Runs in a query, mutation or action.
• Values: vResult
• Functions the module registers, called through the exports above and with notusbase run, never by a client: queue:reportFailure, queue:dispatch, queue:runMutation, queue:load, queue:finish, queue:runAction, queue:enqueue, queue:cancel, queue:status, queue:cancelAll

Test kit

kit.mjs is one file of plain Node, copied into the project by notusbase init. It starts a server on a disposable folder, deploys the project and gives the test a few commands. The list is the export lines of the file and what each one returns, with the comments of the source. How to write a test with it is in the kit README.

kitVersion

The notusbase version that wrote this file. Empty inside the notusbase repository, where the kit is used in place. The kit warns once when the binary it runs is another version.

sleep(ms)

Waits ms milliseconds.

waitUntil(check, what, ms = 5000)

Repeats check every 10 ms until it returns true, or fails saying what did not arrive. Use it after waitJobs and for anything a subscription delivers: a client.query right after a job may still answer with the result the client holds.

freePort()

A free port on 127.0.0.1, chosen by the system.

repoRoot(dir)

The root of the repository dir is in (where .git is), or dir itself.

findNotusBase()

The binary: the NOTUSBASE variable, or notusbase on the PATH.

duration(text)

Milliseconds from "2h", "1h30m", "500ms", "3d", "1w" or a number of milliseconds.

serverAt({ url, dataDir, notusbase = findNotusBase(), env = {}, cwd, log } = {})

Commands and routes of a running server, with the deploy key read from pb_data. Also works for a server another script started, such as the one from npm start.

Returns an object with:

• url: The server address, such as http://127.0.0.1:53211.
• dataDir: The server's pb_data.
• notusbase: The binary in use.
• environment: The environment the kit gives the binary.
• cli: Runs notusbase <args> in the project folder and returns its output; a failure becomes an exception with what the command said. t.cli("sql", "--dir", t.dataDir, "select 1").
• admin: Calls /api/notusbase/<path> with the deploy key, as the CLI does. The exception carries status.
• signIn: Signs in as an existing user of the users collection. id is the subject in the functions.
• deploy(project, { skipTypecheck = false } = {}): Generates the types, runs tsc and deploys the project's convex/ folder.
• envSet(name, value): Sets a process.env variable on the server. null deletes it.
• run(fn, args = {}): Runs a function, internal ones included, like notusbase run. Returns the value; an error becomes an exception, with data when the function threw a ConvexError.
• waitJobs({ function: fn, ms = 10000 } = {}): Waits for the jobs that are already due (runAfter, runAt and the crons' own) to finish. A job set for after the deadline does not count. Returns how many jobs there are in each state.
• advance(time, { wait = true, ms = 10000 } = {}): Advances the server clock (the scheduler and the functions' Date.now()) and waits for what came due to finish: runAfter/runAt jobs and due crons, which run once each. Only on a server the kit started with the test clock (NOTUSBASE_TEST_CLOCK=1). wait: false only advances. Returns how many jobs are in each state.
• now(): The server's "now", in ms: the real one plus what advance added.
• runCron(name, { ms = 10000 } = {}): Fires a cron now, without waiting for its time or touching its next occurrence, and waits for its job to finish. Jobs the cron function schedules are left for waitJobs.
• user(email = `test-${randomBytes(4).toString("hex")}@kit.local`, password = randomBytes(18).toString("base64url")): Creates a user in the users collection through a test superuser, whether signup is open or closed, and signs in.
• log(n = 40): The last lines of the server log, when the kit started it.

start({ notusbase = findNotusBase(), dataDir, port, env = {}, origins = [], log, cwd, timeout = 20000, dev = false, echo = false } = {})

Starts notusbase serve and waits for it to respond. By default with login on the users collection and the WAL sync every 1 s. With dev, starts notusbase dev in the cwd folder: it deploys on start, redeploys on every saved file and accepts any origin. stop() stops the server and waits for it to exit.

Returns an object with:

• everything serverAt() returns
• port: The port the server listens on.
• child: The server process.
• stop(): Stops the server and waits for it to exit; after 10 s, kills it.

setup({ project, name, dir, port, notusbase, server = {}, env = {}, user, skipTypecheck = false } = {})

Test environment: a throwaway folder, a server on a free port, the project deployed and a signed-in user.

Returns an object with:

• everything start() returns
• dir: The throwaway folder, with pb_data and notusbase.log.
• project: The project folder, as an absolute path.
• deployOutput: What notusbase deploy printed: the deployed line and, with a schema change, the plan.
• user: Creates a user in the users collection through a test superuser, whether signup is open or closed, and signs in.
• client: The ConvexClient of the convex package, signed in as the default user: t.client.query(api.x.y, args), .mutation, .action, .onUpdate. It does not print to the console: a refused call arrives as the exception, with e.data when the function threw a ConvexError.
• addUser: Creates another user and returns a client signed in as them.
• anonymous(): A client with no login.
• emails({ status = "captured", ms } = {}): The emails the email module captured, oldest first: { id, to, from?, subject, html, text?, template?, redact?, status, attempts, queuedAt, doneAt }. Waits for the due jobs first, so the send has gone through the queue. status changes the status read (sent, failed, queued, or null for all).
• close: Closes the clients and stops the server. Always call it, in finally.

startApp(o)

Development start: server, functions, variables and the Vite screen, until the screen exits or Ctrl-C arrives.

notusbase.json

In the project folder, next to convex/. notusbase init writes it, and every command run from that folder reads it, so that the options are not repeated. An option on the command line wins over the file. The file goes into git, and for that reason it has no deploy key. A key that is not in this table stops the command, naming it.

Environment variables

These are all the environment variables the code reads: the binary, PocketBase, the operations scripts, the CLI and the MCP server. They tell an operator what is in effect without reading Go.

The server reads the environment only at startup: after changing notusbase.env, run systemctl restart notusbase. The file follows the systemd format, not the shell's: one KEY=value per line, spaces inside a value are kept without quotes (NOTUSBASE_ADMIN_HOSTS=a.com, localhost), surrounding quotes are dropped, and nothing is executed. update.sh and doctor.sh read it the same way, so do not load it with source. doctor.sh warns when the running process started with a different notusbase.env.

"Secret: yes" means the value never appears in logs, script output or reports. doctor.sh only says whether it is set.

The process.env seen by your functions is a different thing: it comes from the _env table, edited in the dashboard or with notusbase env, not from these variables.

Starting the server

Set these in the package's notusbase.env, or in the environment of the compose file. The systemd unit passes NOTUSBASE_HTTP and NOTUSBASE_ORIGINS to the command line, and the server reads NOTUSBASE_DIR itself.

Local backup

See Backup.

S3 and standby

See Backup to S3 and Standby.

Alerts

The red warnings of the status screen, sent out in a single message. See Alerts without Prometheus.

Limits per function

Convex's limits, with its messages. The full table is in Limits per function. Only time and memory are set here; the ceilings on reads, writes, scheduling and ArrayBuffer, and the conflict tries, are fixed (item 203).

Engine

Concurrency and memory. The numbers are in Limits per function.

Public port

Per-IP caps.

"use node" and fetch

See "use node".

Development and diagnostics

Not for production. doctor.sh flags the first three.

CLI and MCP

On the machine of whoever publishes, not on the server.

npm package

On the machine of whoever installs notusbase from npm, not on the server. doctor.sh does not know them.

Operations scripts

Read by the scripts that ship with the package, not by the binary.

PocketBase

Read by PocketBase itself. NotusBase sets none of them; they are listed so that a version upgrade shows a new one.

Tests only

Read only in *_test.go files, or by the server as NOTUSBASE_TEST_<name>: a value that is fixed in production and that the tests and the bench still change. The server writes a warning to the log the first time it uses one. None of them is for production. They serve as the list of what the tests accept; Only the bench and the soak set six more: NOTUSBASE_TEST_NODE_MEM_MB and NOTUSBASE_TEST_NODE_STALL_S (the Node process ceilings, 1024 and 60, which the smoke test lowers), NOTUSBASE_TEST_NODE_PERMISSION (off drops --permission so the smoke test tries the kernel fence alone), NOTUSBASE_TEST_BACKUP_HOURS (the age that starts a new backup chain, 24; the soak uses 1), NOTUSBASE_TEST_PPROF (an address for /debug/pprof and /debug/vars, for the long test) and NOTUSBASE_TEST_MALLOC_TRIM_SECONDS (how often the free memory goes back to the system, 60; 0 turns it off).

Not counted

These do not start with NOTUSBASE_ or PB_, or are not read by NotusBase:

• MALLOC_ARENA_MAX=2, in the systemd unit: with 2 arenas, the free memory that glibc holds on to stops growing. It costs throughput: on 20 CPUs, 23% fewer reads than the glibc default. With the 60 s malloc_trim, it is the combination that uses the least memory. doctor.sh checks it.
• NOTUSBASE, in the MCP server: the path to the binary, notusbase from PATH by default.
• Variables of the bench and the long test, read by the project's own scripts and not by the server: NOTUSBASE_PORT, NOTUSBASE_RUN, NOTUSBASE_TOOLS, NOTUSBASE_BIN, NOTUSBASE_TEST_DIR, PB_TUNED and PB_HOOKS_DIR. Each one is documented in the script that reads it.
• PocketBase's --encryptionEnv, which encrypts the settings with a variable of any name: NotusBase does not use it.