> ## 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.
# Working with branches
> Create, open, share, compare, extend and discard a branch
Branches are in beta.
You manage branches with [`bijection branch`](/branches/cli) or from the
[Branch page](/branches/console) of the Bijection console. This page walks
through a branch's life from the command line.
## Choosing the parent
`bijection branch` acts on the deployment you select, the same way other
commands do: your dev deployment by default, `--prod` for production, or
`--deployment ` for another one. That deployment is the branch's
**parent**. Every lifecycle command, including those for an existing branch,
runs against the parent.
Branch commands refuse a branch URL as the selected deployment. A branch's own
admin key only works on the branch, and the parent always refuses it.
## Creating a branch
```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection branch create what-if
```
```text Output theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
Branch what-if (open)
URL: https:///branch/what-if/
(yours only, valid until 2026-09-25T13:16:34.000Z)
Fork of: live at 1790298994575745257 (2026-09-25T01:16:34.000Z)
Owner: admin
Expires: 2026-09-28T01:16:34.000Z
To deploy to this branch, print its admin key with `bijection branch status what-if --show-admin-key`.
```
The branch forks live at its current revision, shown after `Fork of:`. That
revision is the branch's **basis**, and it never moves.
* A branch **key** is 1 to 40 lowercase letters, digits or hyphens, starting
with a letter or digit.
* Pass `--empty` to start from an empty deployment instead of live data.
* Pass `--ttl-hours ` to choose when the branch expires. The default is 3
days, and the longest is 30 days (720 hours).
* Running `create` again with the same key, parent and owner returns the
existing branch. It does not create a new one with a later basis.
## Opening a branch
A branch has its own URL, `https:///branch//`.
Use it wherever you would use a deployment URL: in a client, in the
[console](/branches/console), or with the CLI.
A branch link is **personal**. It admits only the person it was issued to,
and it is valid for 12 hours, never past the branch's expiry. Every request
checks it again. Print a fresh link at any time with
`bijection branch status `.
### Deploying code to a branch
To deploy to a branch, you need its admin key. Only administrators receive one.
```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection branch status what-if --show-admin-key
```
```text Output {7-10} theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
Branch what-if (open)
URL: https:///branch/what-if/
(yours only, valid until 2026-09-25T13:16:34.000Z)
Fork of: live at 1790298994575745257 (2026-09-25T01:16:34.000Z)
Owner: admin
Expires: 2026-09-28T01:16:34.000Z
Target this branch with:
BIJECTION_SELF_HOSTED_URL= BIJECTION_SELF_HOSTED_ADMIN_KEY=
or:
bijection deploy --url --admin-key
```
Then deploy as you would to any deployment:
```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection deploy --url "" --admin-key ""
```
The new code runs only on the branch. To change live, deploy to live the
ordinary way. [Applying](/branches/apply-and-rebase) a branch never deploys
code.
### Running functions and operations on a branch
[`bijection run`](/cli/reference/run) works against the branch URL too.
Operations run as a user, so pass the user's identity with `--identity`:
```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection run items:add '{"name": "durian"}' \
--url "" --admin-key "" \
--identity '{ tokenIdentifier: "issuer|alice" }'
```
Remember which identity you used. Applying and rebasing replay the operations
invoked under one identity at a time.
### Open and closed branches
A branch loads the first time it receives a request. A branch with no requests
and no connected clients for 10 minutes is closed. Its data is kept, and the
next request loads it again.
A closed branch runs nothing. Its [scheduled functions](/scheduling/scheduled-functions)
run late, when it next opens. A [cron job](/scheduling/cron-jobs) whose runs
were due while the branch was closed runs once, and the other missed runs are
skipped.
## Sharing a branch
A branch is visible only to its owner and to administrators until you share it.
Share it with users by their token identifier (`issuer|subject`, see
[auth in functions](/auth/functions-auth)), not a JWT:
```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection branch share what-if "https://auth.example.com|alice"
```
A user you share with opens the branch with their own sign-in and gets their
own link. Sharing admits them to the branch, never to more data: their own
permissions still govern every read.
```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection branch unshare what-if "https://auth.example.com|alice"
```
Unsharing takes effect at once. Every open connection to the branch closes,
and users who are still admitted reconnect.
Only the branch's owner or an administrator can share, unshare, extend, rebase
or discard a branch.
## Comparing with live
`compare` runs one query on the branch and on live **at the branch's basis**,
so any difference is the branch's doing, not live moving on.
```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection branch compare what-if items:list --args '{"category": "fruit"}'
```
```text Output theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
Rows: 1 added, 1 removed, 1 changed, 4 unchanged.
Added on the branch:
+
Removed on the branch:
-
Changed (parent -> branch):
~
qty: 2 -> 20
The parent is compared at the branch basis; live has moved 2h past it since (basis 1790298994575745257, head 1790306194575745257).
```
When both results are arrays of documents, `compare` matches them by `_id` and
lists the documents added, removed and changed, field by field. Any other
result is compared as one value and reported as identical or different.
The query runs as you. Pass `--identity` to run it as a user, and `--json` for
the full results.
## Listing and inspecting branches
```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection branch list
bijection branch status what-if
```
`list` shows every branch you can open. `status` shows one branch, how far
you have applied it to live, and a fresh link.
## Extending a branch
```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection branch extend what-if --ttl-hours 48
```
`extend` sets the expiry to the given number of hours **from now**, up to 30
days. The basis does not move. A branch whose expiry has passed can no longer
be extended.
A branch that expires stops serving requests, and the deployment discards it
within about a minute.
## Discarding a branch
```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection branch discard what-if
```
Discarding deletes everything committed on the branch, and its links stop
working. What you already applied to live stays applied.
An open branch of live makes your deployment keep its history since the
branch's basis. Discard branches you're done with.