285 lines
8.1 KiB
Plaintext
285 lines
8.1 KiB
Plaintext
---
|
|
title: "Using the CLI"
|
|
description: "How to start a bknd instance using the CLI."
|
|
icon: Terminal
|
|
tags: ["documentation"]
|
|
---
|
|
|
|
The bknd package includes a command-line interface (CLI) that allows you to run a bknd instance and perform various tasks.
|
|
|
|
```sh
|
|
npx bknd
|
|
```
|
|
|
|
Here is the output:
|
|
|
|
```sh
|
|
$ 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`.
|
|
|
|
```sh
|
|
$ 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:
|
|
|
|
```ts
|
|
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):
|
|
|
|
```sh
|
|
node --experimental-strip-types node_modules/.bin/bknd run
|
|
```
|
|
|
|
Or with `tsx`:
|
|
|
|
```sh
|
|
npx tsx node_modules/.bin/bknd run
|
|
```
|
|
|
|
### Turso/LibSQL database
|
|
|
|
To start an instance with a Turso/LibSQL database, run the following:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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`.
|
|
|
|
```sh
|
|
$ 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:
|
|
|
|
```sh
|
|
npx bknd types
|
|
```
|
|
|
|
This will generate types for your database schema in `bknd-types.d.ts`. The generated file could look like this:
|
|
|
|
```typescript title="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:
|
|
|
|
```json title="tsconfig.json"
|
|
{
|
|
"include": ["bknd-types.d.ts"]
|
|
}
|
|
```
|
|
|
|
You can then use the types by importing them from `bknd`:
|
|
|
|
```typescript
|
|
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`](/extending/plugins/#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`.
|
|
|
|
```sh
|
|
$ 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:
|
|
|
|
```sh
|
|
npx bknd config --out appconfig.json
|
|
```
|
|
|
|
To get a template configuration instead, run the following:
|
|
|
|
```sh
|
|
npx bknd config --default
|
|
```
|
|
|
|
To automatically sync your configuration to a file, you may also use the [`syncConfig`](/extending/plugins/#syncconfig) plugin.
|
|
|
|
## Getting the secrets (`secrets`)
|
|
|
|
To see all available `secrets` options, execute `npx bknd secrets --help`.
|
|
|
|
```sh
|
|
$ 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`](/extending/plugins/#syncsecrets) plugin.
|
|
|
|
## Syncing the database (`sync`)
|
|
|
|
Sync your database can be useful when running in [`code`](/usage/setup/#code-only-mode) 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.
|
|
|
|
```bash
|
|
$ 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
|
|
```
|
|
|