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]

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

Commands:
  config [options]         get app config
  copy-assets [options]    copy static assets
  create [options]         create a new project
  debug <subject>          debug bknd
  mcp [options]            mcp server stdio transport
  run [options]            run an instance
  schema [options]         get schema
  sync [options]           sync database
  types [options]          generate types
  user [options] <action>  create/update users, or generate a token (auth)
  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:

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

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:

bknd-types.d.ts

import type { DB } from "bknd";
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" {
  interface DB extends Database {}
}

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

tsconfig.json

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

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

import type { DB } from "bknd";

type Todo = DB["todos"];

All bknd methods that involve your database schema will be automatically typed. You may use the syncTypes plugin to automatically write the types to a file.

Getting the configuration (`config`)

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

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

get app config

Options:
  -c, --config <config>  config file
  --db-url <db>          database url, can be any valid sqlite url
  --pretty               pretty print
  --default              use default config
  --secrets              include secrets in output
  --out <file>           output file
  -h, --help             display help for command

To get the configuration of your app, and to write it to a file, run the following:

npx bknd config --out appconfig.json

To get a template configuration instead, run the following:

npx bknd config --default

To automatically sync your configuration to a file, you may also use the syncConfig plugin.

Getting the secrets (`secrets`)

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

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

get app secrets

Options:
  -c, --config <config>  config file
  --db-url <db>          database url, can be any valid sqlite url
  --template             template output without the actual secrets
  --format <format>      format output (choices: "json", "env", default:
                         "json")
  --out <file>           output file
  -h, --help             display help for command

To automatically sync your secrets to a file, you may also use the syncSecrets plugin.

Syncing the database (`sync`)

Sync your database can be useful when running in code mode. When you're ready to deploy, you can point to the production configuration and sync the database. Schema mutations are only applied when running with the --force option.

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

sync database

Options:
  -c, --config <config>  config file
  --db-url <db>          database url, can be any valid sqlite url
  --seed                 perform seeding operations
  --force                perform database syncing operations
  --drop                 include destructive DDL operations
  --out <file>           output file
  --sql                  use sql output
  -h, --help             display help for command