Using the CLI

The bknd package includes a command-line interface (CLI) that allows you to run a bknd instance and perform various tasks.

npx bknd

Here is the output:

$ npx bknd
Usage: bknd [options] [command]

⚡ bknd cli v0.13.0

Options:
  -V, --version          output the version number
  -h, --help             display help for command

Commands:
  user <action>          create/update users, or generate a token (auth)
  types [options]        generate types
  schema [options]       get schema
  run [options]          run an instance
  debug <subject>        debug bknd
  create [options]       create a new project
  copy-assets [options]  copy static assets
  config [options]       get default config
  help [command]         display help for command

​

Starting an instance (run)

To see all available run options, execute npx bknd run --help.

$ npx bknd run --help
Usage: bknd run [options]

Options:
  -p, --port <port>      port to run on (default: 1337, env: PORT)
  -m, --memory           use in-memory database
  -c, --config <config>  config file
  --db-url <db>          database url, can be any valid libsql url
  --db-token <db>        database token
  --server <server>      server type (choices: "node", "bun", default: "bun")
  --no-open              don't open browser window on start
  -h, --help             display help for command

To order in which the connection is determined is as follows:

1. --db-url
2. --config or reading the filesystem looking for bknd.config.[js|ts|mjs|cjs|json]
3. --memory
4. Environment variables DB_URL and DB_TOKEN in .env or .dev.vars
5. Fallback to file-based database data.db

​

File-based database

By default, a file-based database data.db is used when running without any arguments. You can specify a different file name or path using the --db-url option. The database file will be created in the current working directory if it does not exist.

npx bknd run --db-url file:data.db

​

Using configuration file (bknd.config.*)

You can create a configuration file on the working directory that automatically gets picked up: bknd.config.[js|ts|mjs|cjs|json]

Here is an example of a bknd.config.ts file:

import type { BkndConfig } from "bknd/adapter";

export default {
   // you can either specify the connection directly
   connection: {
      url: "file:data.db",
   },
   // or use the `app` function which passes the environment variables
   app: ({ env }) => ({
      connection: {
         url: env.DB_URL,
      }
   })
} satisfies BkndConfig;

The app function is useful if you need a cross-platform way to access the environment variables. For example, on Cloudflare Workers, you can only access environment variables inside a request handler. If you’re exclusively using a node-like environment, it’s safe to access the environment variables directly from process.env.

If you’re using npx bknd run, make sure to create a file in a file format that node can load, otherwise you may run into an error that the file couldn’t be found:

[INF] 2025-03-28 18:02:21 Using config from bknd.config.ts
[ERR] 2025-03-28 18:02:21 Failed to load config: Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'bknd.config.ts' imported from [...]
    at packageResolve (node:internal/modules/esm/resolve:857:9)
    at [...] {
  code: 'ERR_MODULE_NOT_FOUND'
}

If you still want to use a .ts extension, you can start the CLI e.g. using node (>=v22.6.0):

node --experimental-strip-types node_modules/.bin/bknd run

Or with tsx:

npx tsx node_modules/.bin/bknd run

​

Turso/LibSQL database

To start an instance with a Turso/LibSQL database, run the following:

npx bknd run --db-url libsql://your-db.turso.io --db-token <your-token>

The --db-token option is optional and only required if the database is protected.

​

In-memory database

To start an instance with an ephemeral in-memory database, run the following:

npx bknd run --memory

Keep in mind that the database is not persisted and will be lost when the process is terminated.

​

Generating types (types)

To see all available types options, execute npx bknd types --help.

$ npx bknd types --help
Usage: bknd types [options]

generate types

Options:
  -o, --outfile <outfile>  output file (default: "bknd-types.d.ts")
  --no-write               do not write to file
  -h, --help               display help for command

To generate types for the database, run the following:

npx bknd types

This will generate types for your database schema in bknd-types.d.ts. The generated file could look like this:

import type { DB } from "bknd/core";
import type { Insertable, Selectable, Updateable, Generated } from "kysely";

declare global {
  type BkndEntity<T extends keyof DB> = Selectable<DB[T]>;
  type BkndEntityCreate<T extends keyof DB> = Insertable<DB[T]>;
  type BkndEntityUpdate<T extends keyof DB> = Updateable<DB[T]>;
}

export interface Todos {
  id: Generated<number>;
  title?: string;
  done?: boolean;
}

interface Database {
  todos: Todos;
}

declare module "bknd/core" {
  interface DB extends Database {}
}

Make sure to add the generated file in your tsconfig.json file:

{
   "include": [
      "bknd-types.d.ts"
   ]
}

You can then use the types by importing them from bknd/core:

import type { DB } from "bknd/core";

type Todo = DB["todos"];

All bknd methods that involve your database schema will be automatically typed.