---
name: lorx
description: Work with code hosted on Lorx (lorx.space, git.lorx.space) using git, the bit CLI and the Lorx API. Use when a repository's remote is on git.lorx.space, when asked to push, open or merge a change request (Lorx's pull request) on Lorx, run a repository's Lorx CI (.lorx/actions/*.yml), or check how a push's CI went.
---

# Lorx

Lorx is a git host with CI and change requests. A repository's URLs:

- HTTPS: `https://git.lorx.space/<owner>/<repo>.git`
- SSH: `git@git.lorx.space:<owner>/<repo>.git`
- Web: `https://lorx.space/<owner>/<repo>`

It is plain git: clone, commit, branch and push with git as usual. **bit** is Lorx's CLI: it runs CI locally, handles change requests, and signs git in to Lorx. Docs: https://lorx.space/docs (plain text: https://lorx.space/llms.txt).

## Before you start

1. Check for bit: `bit --version`. If it's missing and you may install software:
   `curl -fsSL https://lorx.space/install.sh | sh`. It installs to `~/.local/bin`.
2. Check sign-in: `bit auth status`. If you're not signed in:
   - with a person present, `bit auth login` (they approve in a browser);
   - with a token in `$LORX_TOKEN`, `printf %s "$LORX_TOKEN" | bit auth login --with-token`.
3. **No OS keychain** (a container or sandbox) means bit can't store a sign-in, and `bit auth` fails. Then skip bit's sign-in and use the token directly:
   - git: `https://x:${LORX_TOKEN}@git.lorx.space/<owner>/<repo>.git`
   - API: `Authorization: Bearer $LORX_TOKEN`

Never print a token, commit it, or write it into a file in the repository.

## Run CI before you push

The repository's CI is in `.lorx/actions/*.yml`. `bit run` runs it here with the engine Lorx uses, so a local pass means the push will pass too. Always run it before pushing a change.

```sh
bit ci check          # validate workflows: problems with file:line:col, exit 1 on errors
bit run               # what a push from here would run (jobs whose paths changed)
bit run <job>         # one job, and what it needs first; `workflow:job` to be exact
bit run --all         # every push job
bit run --list        # the plan only, and what the step cache would skip
bit run --json        # machine-readable plan and results (logs still go to stderr)
```

Steps whose inputs (files, command, settings) passed before are skipped, so rerunning after a small fix is cheap. Fix failures and rerun until it passes, then push. `bit run --no-cache` forces every step.

Writing or changing a workflow? The format is at https://lorx.space/docs/ci/workflows.md. In short:
- each top-level key is a job;
- a job is a command string, or a map of `run`/`steps`, `needs`, `paths`, `branches`, `matrix`, `env`, `image`, `cache`, `runner`, `timeout` and `if`;
- `secrets`, `artifacts` and `on: schedule` are accepted, but not acted on by Lorx yet.

Run `bit ci check` after every edit.

## Repositories

```sh
bit repo create <name> --push            # in a checkout: create (private), add remote `lorx`, push all
bit repo create <name> --public --push
bit clone <owner>/<repo>
bit repo list [<owner>]
```

## Change requests (pull requests)

Commands use this checkout's Lorx remote, or `--repo <owner>/<repo>` from anywhere.

```sh
git switch -c <branch> && git commit …   # work on a branch
bit cr create -t "Title" -b "Why and what" # pushes the branch if needed, then opens it
bit cr create --draft …                   # not mergeable until `bit cr ready <n>`
bit cr list --json                        # open ones; -s merged|closed|all, -A <author>
bit cr view <n> --json                    # state, mergeability, conflicting files, revisions
bit cr diff <n>                           # the change as a diff; --name-only for files
bit cr checkout <n>                       # its branch, locally
bit cr merge <n>                          # merge commit; --squash or --rebase; -d deletes the branch
bit cr merge <n> --auto                   # merge on Lorx as soon as it can
bit cr close <n> -r "why" / bit cr reopen <n> / bit cr revert <n>
```

Write a description that says why the change is made and how it was checked (what `bit run` covered). Don't merge a change request you opened unless you were asked to.

## How did CI go on Lorx?

Pushes run CI on runners registered to the account. Read a run through the API:

```sh
curl -s -H "Authorization: Bearer $LORX_TOKEN" \
  "https://git.lorx.space/api/v1/repos/<owner>/<repo>/runs?commit=$(git rev-parse HEAD)"
# (older runs: pass `next_before` back as ?before=)
# then: GET …/runs/<number>  (jobs, steps, outcomes; each job's `ran_on`)
#       GET …/runs/<number>/jobs/<job id>/log
#       POST …/runs/<number>/rerun   |   POST …/runs/<number>/cancel
```

- A run's `status` is `queued`, `running`, `passed`, `failed`, `cancelled` or `error` (the workflow didn't parse: read `problems`).
- If jobs stay `queued`, no runner that can take them is online. Say so; it isn't a failure of the change.

## The API

- Base: `https://git.lorx.space/api/v1`. Every endpoint: `https://git.lorx.space/api/v1/openapi.json`.
- Errors are `{"error":{"code","message","request_id","fields"}}`; match on `code`.
- Paging: most lists say `next_cursor` (pass it back as `?cursor=`); runs and activity say `next_before` (pass it back as `?before=`). Stop when it is null.

## Limits to respect

- Tokens can't do what needs a person's password: making tokens, adding SSH keys, changing branch rules, deleting repositories, registering runners. Ask the person to do those.
- A branch rule may refuse direct pushes to a branch such as `main`. Open a change request instead of forcing.
- `bit review` is not available yet.