> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Command-line interface for managing Bijection projects and functions

The Bijection command-line interface (CLI) is your interface for managing Bijection
projects and Bijection functions.

To install the CLI on macOS or Linux, run:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
curl -fsSL https://bijection.com/install.sh | sh
```

It installs `~/.bijection/bin/bijection` and needs no Node.js: the CLI manages
its own toolchain. See [Install Bijection](/get-started/install) for PATH setup,
supported platforms, upgrading with `bijection upgrade` and uninstalling.

The available CLI commands are:

* `bijection init` — Create a new Bijection project from a template
* `bijection login` — Log this machine in to Bijection
* [`bijection dev`](/cli/reference/dev) — Develop against a dev deployment, watching for changes
* [`bijection deploy`](/cli/reference/deploy) — Deploy to a production or preview deployment
* [`bijection run`](/cli/reference/run) — Run a function or evaluate an inline readonly query on your deployment
* [`bijection import`](/cli/reference/import) — Import data from a file to your deployment
* [`bijection dashboard`](/cli/reference/dashboard) — Open the console in the browser
* [`bijection docs`](/cli/reference/docs) — Open the docs in the browser
* [`bijection logs`](/cli/reference/logs) — Watch logs from your deployment
* [`bijection export`](/cli/reference/export) — Export data from your deployment to a ZIP file
* [`bijection env`](/cli/reference/env) — Set and view environment variables
* [`bijection data`](/cli/reference/data) — List tables and print data from your database
* [`bijection deployment`](/cli/reference/deployment) — Manage deployments
* [`bijection project`](/cli/reference/project) — Manage projects
* [`bijection codegen`](/cli/reference/codegen) — Generate backend type definitions
* `bijection upgrade` — Upgrade bijection to the latest release
* [`bijection update`](/cli/reference/update) — Print instructions for updating the bijection package
* [`bijection logout`](/cli/reference/logout) — Log out of Bijection on this machine
* [`bijection function-spec`](/cli/reference/function-spec) — List function metadata from your deployment
* [`bijection insights`](/cli/reference/insights) — Show health insights for your deployment
* [`bijection mcp`](/cli/reference/mcp) — Manage the Model Context Protocol server for Bijection \[BETA]
* [`bijection ai-files`](/cli/reference/ai-files) — Manage Bijection AI files

## Configure

### Create a new project

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection init my-app
```

creates `my-app/` with the `bijection/` directory, the home for your query and
mutation functions, holding a sample schema, query and mutation, plus
`bijection.json`, `.gitignore` and a README. Without a directory argument it
works in the current directory, so you can run it inside an existing app; it
never overwrites existing files. `--template` chooses the template:

* `backend` (default): the backend alone. It needs no Node.js or npm; the CLI
  writes `node_modules/bijection` for your editor's types.
* `react-vite`: also a React app built with Vite.
* `nextjs`: also a Next.js app.

The `react-vite` and `nextjs` templates install the app's dependencies with your
package manager (pnpm, bun, yarn or npm).

### Log in

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection login
```

logs this machine in to your Bijection account, once per machine, and stores
the credential in `~/.bijection/config.json`.

<Note>
  Bijection's hosted service is not yet open for public sign-up, and the CLI
  has no default management service. Before running `bijection login`, set
  `BIJECTION_MANAGEMENT_URL` to the management service URL you were given, in
  your shell's startup file so that every later `bijection` command sees it too:

  ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  export BIJECTION_MANAGEMENT_URL=https://<your management service>
  ```
</Note>

### Create a deployment

The first time you run

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection dev
```

in a project, it creates a new Bijection project and your dev deployment. It
then creates:

1. `.env.local` with `BIJECTION_DEPLOYMENT` variable: This is the main
   configuration for your Bijection project. It is the name of your development
   deployment.
2. `bijection/_generated/`: the typed API of your functions.

### Recreate project configuration

Run

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection dev
```

in a project directory without a set `BIJECTION_DEPLOYMENT` to configure a new or
existing project.

### Log out

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection logout
```

Remove the existing Bijection credentials from your device, so subsequent commands
like `bijection dev` can use a different Bijection account.

## Develop

### Run the Bijection dev server

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection dev
```

Watches the local filesystem. When you change a
[function](/functions/overview) or the [schema](/database/schemas), the
new versions are pushed to your dev deployment and the
[generated types](/generated-api/index) in `bijection/_generated` are updated. By
default, logs from your dev deployment are displayed in the terminal.

It's also possible to
[run a Bijection deployment locally](/cli/local-deployments-for-dev) for
development.

### Open the console

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection dashboard
```

Open the [Bijection console](/dashboard/overview).

### Open the docs

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection docs
```

Get back to these docs!

### Run Bijection functions

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection run <functionName> [args]
```

Run a public or internal Bijection query, mutation, or action on your development
deployment.

Arguments are specified as a JSON object.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection run messages:send '{"body": "hello", "author": "me"}'
```

Add `--watch` to live update the results of a query. Add `--push` to push local
code to the deployment before running the function.

Use `--prod` to run functions in the production deployment for a project.

#### Run an inline query

You can also evaluate a readonly inline query on your deployment:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection run --inline-query 'await ctx.db.query("messages").take(5)'
```

For multi-statement queries, use an explicit `return`:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection run --inline-query 'const firstMessage = await ctx.db.query("messages").first(); console.log(firstMessage?._id); return firstMessage;'
```

If you need full control, you can pass a full module source that exports a
default query:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection run --inline-query 'export default query({ handler: async (ctx) => { console.log("Write and test your query function here!"); return await ctx.db.query("YOUR_TABLE_NAME").take(10); }, })'
```

The function call is also completely sandboxed, so it can only read data and
cannot modify the database or access the network.

Use `--component <path>` to run the inline query inside a mounted component. Use
`--prod` to run the inline query on the production deployment for a project.

### Tail deployment logs

You can choose how to pipe logs from your dev deployment to your console:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
# Show all logs continuously
bijection dev --tail-logs always

# Pause logs during deploys to see sync issues (default)
bijection dev

# Don't display logs while developing
bijection dev --tail-logs disable

# Tail logs without deploying
bijection logs
```

Use `--prod` with `bijection logs` to tail the prod deployment logs instead.

### Import data from a file

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection import --table <tableName> <path>
bijection import <path>.zip
```

See description and use-cases:
[data import](/database/import-export/import).

### Export data to a file

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection export --path <directoryPath>
bijection export --path <filePath>.zip
bijection export --include-file-storage --path <path>
```

See description and use-cases:
[data export](/database/import-export/export).

### Display data from tables

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection data  # lists tables
bijection data <table>
```

Display a simple view of the
[console data page](/dashboard/deployments/data) in the command line.

The command supports `--limit` and `--order` flags to change data displayed. For
more complex filters, use the console data page or write a
[query](/database/reading-data/reading-data).

The `bijection data <table>` command works with
[system tables](/database/advanced/system-tables), such as `_storage`, in
addition to your own tables.

### Show deployment health insights

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection insights
bijection insights --details
bijection insights --prod
```

Show health insights for a Bijection deployment over the last 72 hours. Reports
[OCC (Optimistic Concurrency Control)](/error#write-conflict-optimistic-concurrency-control) conflicts and resource limit
issues that may indicate performance problems.

Add `--details` to include recent events for each insight. Use `--prod` to check
the production deployment, `--preview-name <name>` for a preview deployment, or
`--deployment-name <name>` for a specific deployment.

### Read and write environment variables

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection env list
bijection env get <name>
bijection env set <name> <value>
bijection env remove <name>
```

See and update the
[deployment environment variables](/production/environment-variables). You can
alternatively use the
[settings page on the console](/dashboard/deployments/settings#environment-variables).

Tip: to avoid secrets from ending up in your terminal shell history, you can
pass the value via stdin, from a file, or interactively.

Useful commands:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
# Set a value interactively
bijection env set API_KEY

# Set from MacOS clipboard
pbpaste | bijection env set API_KEY
# Windows PowerShell
Get-Clipboard | bijection env set API_KEY

# Read a value from a file
bijection env set PUBLIC_KEY --from-file key.pub

# Set multiple variables via a file
bijection env set --from-file .env.defaults

# Save environment variables to a file
bijection env list >> .env.bijection  # append
bijection env list >  .env.bijection  # overwrite

# Update values after editing them locally:
bijection env set --force < .env.bijection
```

Note: to set variables on your production deployment, pass `--prod`.

## Deploy

### Deploy Bijection functions to production

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection deploy
```

The target deployment to push to is determined like this:

1. If the `BIJECTION_DEPLOY_KEY` environment variable is set (typical in CI), then
   it is the deployment associated with that key.
2. If the `BIJECTION_DEPLOYMENT` environment variable is set (typical during local
   development), then the target deployment is the production deployment of the
   project that the deployment specified by `BIJECTION_DEPLOYMENT` belongs to. This
   allows you to deploy to your prod deployment while developing against your
   dev deployment.

This command will:

1. Run a command if specified with `--cmd`. The command will have BIJECTION\_URL (or
   similar) environment variable available:
   ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
   bijection deploy --cmd "npm run build"
   ```
   You can customize the URL environment variable name with
   `--cmd-url-env-var-name`:
   ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
   bijection deploy --cmd 'npm run build' --cmd-url-env-var-name CUSTOM_BIJECTION_URL
   ```
2. Typecheck your Bijection functions.
3. Regenerate the [generated code](/generated-api/index) in the `bijection/_generated`
   directory.
4. Bundle your Bijection functions and their dependencies.
5. Push your functions, [indexes](/database/reading-data/indexes/indexes),
   and [schema](/database/schemas) to production.

Once this command succeeds the new functions will be available immediately.

### Deploy Bijection functions to a [preview deployment](/production/multiple-deployments#using-preview-deployments)

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection deploy
```

When run with the `BIJECTION_DEPLOY_KEY` environment variable containing a
[Preview Deploy Key](/cli/deploy-key-types#deploying-to-preview-deployments),
this command will:

1. Create a new Bijection deployment. `bijection deploy` will infer the Git branch
   name for Vercel, Netlify, GitHub, and GitLab environments, or the
   `--preview-create` option can be used to customize the name associated with
   the newly created deployment.
   ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
   bijection deploy --preview-create my-branch-name
   ```

2. Run a command if specified with `--cmd`. The command will have BIJECTION\_URL (or
   similar) environment variable available:

   ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
   bijection deploy --cmd "npm run build"
   ```

   You can customize the URL environment variable name with
   `--cmd-url-env-var-name`:

   ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
   bijection deploy --cmd 'npm run build' --cmd-url-env-var-name CUSTOM_BIJECTION_URL
   ```

3. Typecheck your Bijection functions.

4. Regenerate the [generated code](/generated-api/index) in the `bijection/_generated`
   directory.

5. Bundle your Bijection functions and their dependencies.

6. Push your functions, [indexes](/database/reading-data/indexes/indexes),
   and [schema](/database/schemas) to the deployment.

7. Run a function specified by `--preview-run` (similar to the `--run` option
   for `bijection dev`).

   ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
   bijection deploy --preview-run myFunction
   ```

See the [Vercel](/production/hosting/vercel#preview-deployments) or
[Netlify](/production/hosting/netlify#deploy-previews) hosting guide for
setting up frontend and backend previews together.

### Update generated code

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection codegen
```

The [generated code](/generated-api/index) in the `bijection/_generated` directory
includes types required for a TypeScript typecheck. This code is generated
whenever necessary while running `bijection dev` and this code should be
committed to the repo (your code won't typecheck without it!).

In the rare cases it's useful to regenerate code (e.g. in CI to ensure that the
correct code was checked it) you can use this command.

With a deployment configured, `bijection codegen` has the deployment evaluate
your functions and configuration in the Bijection JavaScript runtime; this
doesn't modify the code running on the deployment. Without one, it generates
the code from `bijection/` alone, as `bijection init` does. A project with
`bijection/bijection.config.ts`, or with `codegen.staticApi` or
`codegen.staticDataModel` in `bijection.json`, needs a deployment's analysis:
run `bijection dev` first.