Instances from the CLI

One command line, no repository, no code. Instances are things you make when you need one and delete when you do not, locally or in your own Cloudflare account, with the same commands for each.

bun i -g @voidbase-cloud/voidbase      # or: npm i -g @voidbase-cloud/voidbase
voidbase version

Local instances

This is the same job the standalone executable does, for people who would rather install from npm than download a binary. The difference is that it remembers what you have made, so a second instance does not mean finding where you put the first.

Local means wherever the CLI is running. That is usually a laptop, but it is just as often a container in a compose file, a CI job that needs a real backend for its tests, or a desktop app that ships voidbase inside it. Nothing here talks to Cloudflare and none of it needs an account.

voidbase local new blog

created "blog" in ~/.voidbase/instances/blog (pb_hooks/main.pb.js, .gitignore, pb_secrets/main.ts)
superuser admin@example.com / k3f8s2m1qzA1

next: voidbase local start blog   (the API on 8090, the panel at http://127.0.0.1:8090/_/)

The instance is a directory holding its own database, hooks and configuration, and a row in ~/.voidbase/instances.json recording its name and port. Nothing is sent anywhere. Set VOIDBASE_HOME and both the registry and the default directory move with it, which is what an image or an app bundle wants. Pass --dir to put it where you want it, --port to pick the port, and --email with --password to choose the superuser rather than have one generated.

voidbase local ls

3 local instance(s), from ~/.voidbase/instances.json:
  blog                 :8090   running      2 MB  ~/.voidbase/instances/blog
  shop                 :8091   stopped    941 kB  ~/.voidbase/instances/shop
  workshop             :8092   stopped     14 MB  ~/.voidbase/instances/workshop

Each instance keeps the port it was given, so they never collide and the address stays the same between runs. voidbase local start blog runs one, and with no name it starts the first.

voidbase local rm workshop            # forget it, keep the data
voidbase local rm workshop --purge    # and delete the directory, after typing the name back

Removing an instance forgets it. The directory stays where it is until --purge says otherwise, and that asks you to type the name back before deleting a database.

A local instance is the same shape as a project: the same pb_hooks, pb_migrations and pb_secrets. Moving from one to the other is moving a directory into a repository, so nothing you write here is throwaway.

On your Cloudflare account

The same idea, one command further. Everything below needs one API token, and one command prints the link that creates it with the right permissions already selected.

voidbase token                        # prints the link that creates the token
export VOIDBASE_DEPLOY_CF_API_KEY=...   # paste it here

Create one

Run this in an empty directory. It is not a project and it does not become one.

voidbase deploy --name blog-api
voidbase deploy --name blog-api --domain api.example.com

That creates the Worker, its database, its file storage, its job queue and its realtime object, deploys the server into it, and prints the address. With a hostname you own on the same account, name it and the instance answers there as well.

The first superuser is created with a generated password, saved to pb_data/.superuser-credentials in the directory you ran the command from. That file is the one thing the command leaves behind, so keep it or sign in and change the password.

See what you have

voidbase instances

3 instance(s) on Example Ltd:
  blog-api                         release 0.7.0  updated 2026-09-08
  staging-api                      release 0.7.0  updated 2026-09-04
  workshop-demo                    release 0.6.2  updated 2026-08-30

Delete one

This takes the Worker and everything it owns: the database and its contents, the bucket and its files, the queue, and any custom domain pointing at it. It prints that list and waits for the name to be typed back, and in a script it refuses unless --yes says you already decided.

voidbase destroy workshop-demo

There is no undo and no backup is taken. Take one from the admin panel's Backups screen first if the data matters.

Updating

voidbase update

A global install reinstalls itself at the newest published version. Your local instances are directories of data and configuration, not copies of the program, so they are all on the new version the next time you start one. Nothing is migrated and nothing is lost.

Instances in your Cloudflare account are the other case. Those run a copy of voidbase that was uploaded when you created them, so updating the CLI changes what the next deploy would carry, not what is answering requests. voidbase deploy from the same directory puts the new version live.

voidbase update --check changes nothing. It prints the version you are on and the newest one, and exits 1 when you are behind and 2 when it could not find out, which is what a pipeline reads. --to 0.9.0 goes to a particular version rather than the newest, and --dry-run prints the command it would run without running it.

You do not have to remember to check. Any voidbase command mentions a new release once a day, from an answer cached under ~/.voidbase. It never speaks in CI or when the output is not a terminal, and VOIDBASE_NO_UPDATE_CHECK=1 silences it everywhere. Every release is written up in the release notes.

When this stops being enough

The moment you want an endpoint of your own, a handler that runs when a record changes, or a schema you keep in version control rather than clicking into the panel, you want a voidbase project. It is the same instance with a repository around it.

Found something wrong on this page?

Fix it yourself. The link below opens this file in GitHub's editor and forks the repository for you if you need one, and your change becomes a pull request without leaving the browser.

Improve this page Report it instead Ask a question