# bit command reference

Every bit command and option, from bit's own help (bit 0.1.7).

This page is generated from `bit --help` (bit 0.1.7). Every command also prints its own help with `--help`.

Commands that talk to Lorx find the host the same way: the `--host` given, else `LORX_HOST`, else the host you signed in to, else `git.lorx.space`. Commands about a repository use this checkout's Lorx remote unless you pass `--repo owner/name`.

## bit auth

Sign in to a Lorx host, see who you are, sign out

```text
Usage: bit auth <COMMAND>

Options:
  -h, --help  Print help
```

### bit auth login

Sign in: approve this device in the browser, or paste an access token

```text
Usage: bit auth login [OPTIONS] [HOST]

Arguments:
  [HOST]  e.g. git.lorx.space (the default) or http://localhost:4040

Options:
      --with-token          Read a personal access token from stdin instead of signing in with the browser
      --no-browser          Print the link instead of opening the browser
      --signing-key <FILE>  A public key to add for signing commits (default: ~/.ssh/id_ed25519.pub if present)
      --no-signing-key      Do not offer an SSH key for signing
  -h, --help                Print help
```

### bit auth status

Which hosts you are signed in to, and as whom

```text
Usage: bit auth status

Options:
  -h, --help  Print help
```

### bit auth logout

Sign out of a host and forget its credential

```text
Usage: bit auth logout [HOST]

Arguments:
  [HOST]  

Options:
  -h, --help  Print help
```

## bit clone

Clone a Lorx repository (owner/name) with git

```text
Usage: bit clone [OPTIONS] <REPO> [DIR]

Arguments:
  <REPO>  
  [DIR]   

Options:
      --host <HOST>  The host to clone from (default: LORX_HOST, then the host you signed in to, then git.lorx.space)
  -h, --help         Print help
```

## bit import

Bring history from another forge onto Lorx

```text
Usage: bit import <COMMAND>

Options:
  -h, --help  Print help
```

### bit import github

A GitHub repository's pull requests, with their commits and conversations, as change requests of the same numbers. Reads GitHub with GITHUB_TOKEN or `gh auth token` (never sent to Lorx). Running it again adds only what is new

```text
Usage: bit import github [OPTIONS] <REPO>

Arguments:
  <REPO>  On GitHub: owner/name

Options:
      --to <TO>      On Lorx: owner/name (default: yours, with the same name)
      --host <HOST>  
  -h, --help         Print help
```

## bit repo

Repositories: create one (and push a checkout to it), list them

```text
Usage: bit repo <COMMAND>

Options:
  -h, --help  Print help
```

### bit repo create

Create a repository under your account. Inside a git checkout (or with --source), the checkout gets a remote for it, and --push pushes every branch and tag

```text
Usage: bit repo create [OPTIONS] <NAME>

Arguments:
  <NAME>  The new repository's name

Options:
      --public                     Visible to everyone (the default is private)
      --private                    Only you (the default)
  -d, --description <DESCRIPTION>  A one-line description
      --source <SOURCE>            The checkout to connect (default: the current directory) [default: .]
      --remote <REMOTE>            The name of the remote to add or repoint [default: lorx]
      --push                       Push every branch and tag once created
      --host <HOST>                The host (default: LORX_HOST, then the host you signed in to, then git.lorx.space)
  -h, --help                       Print help
```

### bit repo list

List an account's repositories (yours by default)

```text
Usage: bit repo list [OPTIONS] [OWNER]

Arguments:
  [OWNER]  

Options:
      --host <HOST>  
  -h, --help         Print help
```

## bit cr

Change requests (Lorx's pull requests): open, list, view, check out, diff, merge, close, reopen and revert them

```text
Usage: bit cr [OPTIONS] <COMMAND>

Options:
      --repo <OWNER/NAME>  The repository, as owner/name (default: this checkout's Lorx remote)
      --host <HOST>        The Lorx host (default: LORX_HOST, else the hosts you signed in to and then git.lorx.space, matched against this checkout's remotes)
  -h, --help               Print help
```

### bit cr create

Open a change request from the current branch, pushing it first if the remote's copy is missing or behind (git push -u).

The title and description default to the branch's commit when it has exactly one; with several, your editor opens (git's editor: GIT_EDITOR, core.editor, VISUAL or EDITOR).

```text
Usage: bit cr create [OPTIONS]

Options:
      --base <BASE>
          The branch to merge into (default: the repository's default branch)

      --repo <OWNER/NAME>
          The repository, as owner/name (default: this checkout's Lorx remote)

      --host <HOST>
          The Lorx host (default: LORX_HOST, else the hosts you signed in to and then git.lorx.space, matched against this checkout's remotes)

  -t, --title <TITLE>
          The title (default: the single commit's subject, else asked in the editor)

  -b, --body <BODY>
          The description (default: the single commit's body)

  -F, --body-file <FILE>
          Read the description from a file, or from stdin with -

  -d, --draft
          Open it as a draft, which cannot merge until marked ready

  -h, --help
          Print help (see a summary with '-h')
```

### bit cr list

List change requests: number, title, head → base, author, state, last update

```text
Usage: bit cr list [OPTIONS]

Options:
      --repo <OWNER/NAME>  The repository, as owner/name (default: this checkout's Lorx remote)
  -s, --state <STATE>      open (drafts included), draft, merged, closed or all [default: open] [possible values: open, draft, merged, closed, all]
  -A, --author <AUTHOR>    Only those opened by this username
      --host <HOST>        The Lorx host (default: LORX_HOST, else the hosts you signed in to and then git.lorx.space, matched against this checkout's remotes)
  -L, --limit <LIMIT>      At most this many [default: 30]
      --json               Print the API's JSON instead of a table
  -h, --help               Print help
```

### bit cr view

Show a change request: state, author, branches, whether it merges cleanly (and which files conflict), revisions, recent timeline and description

```text
Usage: bit cr view [OPTIONS] <NUMBER>

Arguments:
  <NUMBER>  

Options:
      --json               Print the API's JSON
      --repo <OWNER/NAME>  The repository, as owner/name (default: this checkout's Lorx remote)
      --host <HOST>        The Lorx host (default: LORX_HOST, else the hosts you signed in to and then git.lorx.space, matched against this checkout's remotes)
  -h, --help               Print help
```

### bit cr checkout

Fetch a change request's head branch and switch to it locally

```text
Usage: bit cr checkout [OPTIONS] <NUMBER>

Arguments:
  <NUMBER>  

Options:
  -b, --branch <BRANCH>    The local branch to use (default: the head branch's name)
      --repo <OWNER/NAME>  The repository, as owner/name (default: this checkout's Lorx remote)
  -f, --force              Reset the local branch to the head even if it has commits the head does not
      --host <HOST>        The Lorx host (default: LORX_HOST, else the hosts you signed in to and then git.lorx.space, matched against this checkout's remotes)
  -h, --help               Print help
```

### bit cr diff

Show a change request's changes as a diff (the head against where it left the base)

```text
Usage: bit cr diff [OPTIONS] <NUMBER>

Arguments:
  <NUMBER>  

Options:
      --name-only          Only the names of the changed files
      --repo <OWNER/NAME>  The repository, as owner/name (default: this checkout's Lorx remote)
      --color <COLOR>      Colour the diff: auto (on a terminal, unless NO_COLOR), always or never [default: auto] [possible values: auto, always, never]
      --host <HOST>        The Lorx host (default: LORX_HOST, else the hosts you signed in to and then git.lorx.space, matched against this checkout's remotes)
  -h, --help               Print help
```

### bit cr merge

Merge a change request on the server, or arm it to merge itself (--auto)

```text
Usage: bit cr merge [OPTIONS] <NUMBER>

Arguments:
  <NUMBER>  

Options:
      --merge              A merge commit (the default)
      --repo <OWNER/NAME>  The repository, as owner/name (default: this checkout's Lorx remote)
      --host <HOST>        The Lorx host (default: LORX_HOST, else the hosts you signed in to and then git.lorx.space, matched against this checkout's remotes)
      --squash             One commit with the whole change
      --rebase             Replay each commit onto the base
  -d, --delete-branch      Delete the head branch after merging (and your local copy, if it holds nothing more)
      --auto               Merge on the server as soon as it can (open, not a draft, merging cleanly), even with this machine off. Merges at once if it already can
      --disable-auto       Disarm auto-merge
  -s, --subject <SUBJECT>  The merge or squash commit's title (default: one naming the change request)
  -b, --body <BODY>        The merge or squash commit's message body
  -h, --help               Print help
```

### bit cr close

Close a change request without merging it

```text
Usage: bit cr close [OPTIONS] <NUMBER>

Arguments:
  <NUMBER>  

Options:
  -r, --reason <REASON>    Why, shown on its timeline
      --repo <OWNER/NAME>  The repository, as owner/name (default: this checkout's Lorx remote)
      --host <HOST>        The Lorx host (default: LORX_HOST, else the hosts you signed in to and then git.lorx.space, matched against this checkout's remotes)
  -h, --help               Print help
```

### bit cr reopen

Reopen a closed change request

```text
Usage: bit cr reopen [OPTIONS] <NUMBER>

Arguments:
  <NUMBER>  

Options:
      --repo <OWNER/NAME>  The repository, as owner/name (default: this checkout's Lorx remote)
      --host <HOST>        The Lorx host (default: LORX_HOST, else the hosts you signed in to and then git.lorx.space, matched against this checkout's remotes)
  -h, --help               Print help
```

### bit cr ready

Mark a draft ready for review (or, with --undo, turn it back into a draft)

```text
Usage: bit cr ready [OPTIONS] <NUMBER>

Arguments:
  <NUMBER>  

Options:
      --repo <OWNER/NAME>  The repository, as owner/name (default: this checkout's Lorx remote)
      --undo               Turn it back into a draft
      --host <HOST>        The Lorx host (default: LORX_HOST, else the hosts you signed in to and then git.lorx.space, matched against this checkout's remotes)
  -h, --help               Print help
```

### bit cr revert

Open a change request that takes back a merged one: one commit on a new branch

```text
Usage: bit cr revert [OPTIONS] <NUMBER>

Arguments:
  <NUMBER>  

Options:
      --repo <OWNER/NAME>  The repository, as owner/name (default: this checkout's Lorx remote)
  -t, --title <TITLE>      The new request's title (default: Revert "<title>")
  -b, --body <BODY>        Said after "Reverts #n." in its description
      --host <HOST>        The Lorx host (default: LORX_HOST, else the hosts you signed in to and then git.lorx.space, matched against this checkout's remotes)
  -d, --draft              Open it as a draft
  -h, --help               Print help
```

## bit run

Run the workflows in .lorx/actions/ here, with the engine the server uses: what a push from here would run (only jobs whose paths changed), or the jobs named (`job`, or `workflow:job`) and what they need. Steps whose inputs passed before are skipped, and a step several jobs share runs once

```text
Usage: bit run [OPTIONS] [JOBS]...

Arguments:
  [JOBS]...  Jobs to run (with what they need). Default: what a push would run

Options:
      --all              Every push job, whatever changed
      --no-cache         Run every step, even ones that passed with the same inputs (still remembered)
      --list             Show the plan (and what the cache would skip) without running anything
      --json             Print the plan and the results as JSON (output still goes to stderr as it runs)
      --file <FILE>      One workflow file instead of every one in .lorx/actions/
  -w, --workflow <NAME>  Only this workflow (.lorx/actions/<name>.yml)
  -h, --help             Print help
```

## bit ci

The workflows in .lorx/actions/, without running them

```text
Usage: bit ci <COMMAND>

Options:
  -h, --help  Print help
```

### bit ci graph

Draw the plan as a graph: jobs as nodes, needs as edges, levels as ranks, and what the step cache would skip. Paste Mermaid into Markdown (or a mermaid.live page) to see it

```text
Usage: bit ci graph [OPTIONS] [JOBS]...

Arguments:
  [JOBS]...  Jobs to draw, with what they need (`job` or `workflow:job`). Default: what a push from here would run

Options:
      --all              Every push job, whatever changed
      --format <FORMAT>  mermaid (default), dot or json [default: mermaid] [possible values: mermaid, dot, json]
  -w, --workflow <NAME>  Only this workflow
  -h, --help             Print help
```

### bit ci check

Check the workflows in .lorx/actions/: their problems with line and column (as compilers print them), and the plan a push makes. Exits 1 when any has errors

```text
Usage: bit ci check [OPTIONS]

Options:
      --file <FILE>  One workflow file instead of every one in .lorx/actions/
      --json         
  -h, --help         Print help
```

## bit review

Review your changes here, before you push: what changed that other code can see (public API, routes, API fields, tables, migrations), and what the review engine found. The same engine the server runs; facts are cached, so unchanged files are not read again

```text
Usage: bit review [OPTIONS]

Options:
      --base <REV>          Compare against this commit instead of HEAD
      --staged              Only the staged changes
      --commit <REV>        A commit against its parent, instead of your changes
      --json                Print the review as JSON
      --all                 Show every fact change, internal ones (signatures, calls, complexity) too
      --fail-on <SEVERITY>  Exit 1 when a finding is at least this severe (info, low, medium, high, critical)
      --no-cache            Read every file again instead of using cached facts
      --ci                  In a CI job: review the job's commit (LORX_HEAD) against the run's base (LORX_BASE), both set by the runner. With no base (a run started by hand, a default branch's first push) it says so and passes
  -h, --help                Print help
```

## bit runner

Make this machine a runner: it takes CI jobs from your repositories on Lorx and runs them here, with the same engine as bit run

```text
Usage: bit runner <COMMAND>

Options:
  -h, --help  Print help
```

### bit runner register

Register this machine, with a one-time token from Settings, then Runners (on your account or on one repository)

```text
Usage: bit runner register [OPTIONS] --token <TOKEN> [HOST]

Arguments:
  [HOST]  The host (default: LORX_HOST, then the host you signed in to, then git.lorx.space)

Options:
      --token <TOKEN>    The `lorx_rr_…` registration token [env: LORX_RUNNER_TOKEN=]
      --name <NAME>      What to call it (default: this machine's name)
      --labels <LABELS>  Labels it offers, comma-separated (its os and arch are always added). Jobs that ask for `runner: <label>` go to a runner with that label
  -h, --help             Print help
```

### bit runner run

Take jobs and run them, until Ctrl-C (once: finish the job in hand; twice: stop now)

```text
Usage: bit runner run [OPTIONS]

Options:
      --once                           Run one job, then stop
      --idle-exit <IDLE_EXIT>          Stop after this long with no job (90s, 15m, 2h): for a cloud machine that powers off when idle, so it costs nothing until Lorx starts it again
      --slots <SLOTS>                  Jobs to run at once (default: a quarter of the cores, at most one per 8 GB of memory, at least one)
      --disk-max <DISK_MAX>            The most the kept checkouts and caches may take on disk (500M, 30G, 1T); the least recently used go past it [default: 50G]
      --disk-min-free <DISK_MIN_FREE>  Room to leave free on the disk: the least recently used checkouts and caches go to keep it [default: 10G]
  -h, --help                           Print help
```

### bit runner status

Show which host this runner is registered with, and its labels

```text
Usage: bit runner status

Options:
  -h, --help  Print help
```

## bit upgrade

Upgrade bit to the latest version (or --version), checked against the release's SHA256SUMS. At most once a day bit also says, after a command, when a newer one is out (BIT_NO_UPDATE_CHECK=1 turns that off)

```text
Usage: bit upgrade [OPTIONS]

Options:
      --version <VERSION>  A version to install instead of the latest (can go back to an older one)
      --check              Only say whether a newer version is out
  -h, --help               Print help
```

## bit setup

Get this machine ready: find git (and say how to install it), check the name and email your commits use, set the defaults Lorx relies on, and sign in. Shows what is there now before changing anything

```text
Usage: bit setup [OPTIONS] [HOST]

Arguments:
  [HOST]  The host to sign in to (default: LORX_HOST, then the host you signed in to, then git.lorx.space)

Options:
  -y, --yes                      Accept every proposal without asking (for scripts)
      --check                    Only report what's set and what isn't; change nothing. Exits 1 if something needs doing
      --name <NAME>              The name your commits show (git's user.name)
      --email <EMAIL>            The email your commits use (git's user.email)
      --default-branch <BRANCH>  The branch new repositories start on (default: main)
      --no-login                 Don't sign in
      --no-browser               Print the sign-in link instead of opening the browser
  -h, --help                     Print help
```
