# Command reference

## knotless

`<url>` is a repository's `knotless://<handle or did>/<name>`. A trailing
`/` and a trailing `.git` are dropped, and any other `/` in the name is
refused. A name is 1 to 100 bytes of `[A-Za-z0-9._~-]`, not `.` or `..`.
`<at-uri>` is a pull's, issue's or comment's `at://` URI, as `pull`,
`issue`, `list` and `show` print them.

An error prints `knotless: <error>` and exits 1. One a PDS refused for want
of scope, as a login from before knotless asked for more is, adds a second
line, `knotless: your login is older than what knotless asks for now: run
`knotless login` again to allow this`. Until then, any command but `login`
and `logout` ends by printing to stderr `knotless: your login is older than
what knotless asks for now: run `knotless login <handle>` again to allow
all of it`, whether or not it failed.

Once a day, a command asks `KNOTLESS_APPVIEW` for its newest release
(`/releases/latest`) and the oldest version it asks clients to be
(`dev.knotless.describeServer`'s `client`), waiting 3 s at most, and keeps
what it said in `update.json`; an appview that does not answer leaves
what was known. With a newer release out, a command ends by printing to
stderr `knotless: knotless <latest> is out, and this is <version>. Run
`knotless upgrade` to install it.` Older than the appview asks for, any
command but `upgrade`, `login`, `logout` and `help` fails at once, saying
`knotless <version> is older than the <minimum> the appview asks for.
<reason> Run `knotless upgrade`, or set KNOTLESS_IGNORE_MINIMUM=1 to go on
anyway.` `KNOTLESS_NO_UPDATE_CHECK` turns both off. knotless-mcp over
stdio does the same: with a newer release out, its first tool's answer
ends with that line, and older than asked for, every tool fails with that
refusal.

### Accounts

| Command | |
| --- | --- |
| `login <handle> [--password-stdin]` | log in with OAuth in a browser, or with an app password read from standard input (or `KNOTLESS_PASSWORD`) |
| `logout <handle>` | drop the session, revoking its tokens |
| `upgrade` | install the newest release over this one, running the appview's `/install.sh` into `KNOTLESS_INSTALL_DIR`, or else the directory this binary is in, and printing what it said (`knotless: installing <version> for <target> into <dir>`). Refused where a package manager put it: `~/.cargo/bin` (`cargo installed knotless here: upgrade it with cargo`), a Homebrew `Cellar` or `/usr/bin`. With no appview, fails `an appview hands out releases, and none is set: set KNOTLESS_APPVIEW`; with one that hands out none, `<appview> hands out no releases` |
| `delete-data <handle> [--yes]` | delete every knotless record from your account ([storage.md](../design/storage.md#deleting-your-knotless-data)): prints your repositories, one line each, `repository <name>`, then ` (private)` and `, shared with <n>` where they apply, then each collection's count and name, tab-separated, and `<n>	spaces`; asks you to type the handle again unless `--yes`, and refuses anything else (`nothing deleted: …`); then prints `<n> deleted` as it goes, has the appview forget you, and prints `deleted <n>, and logged out`. Run again, one cut short carries on. An OAuth login from before this asks for it with a new scope: log in again |
| `email` | how many addresses you claim: `<n> addresses claimed`. Each is kept only as a hash salted with your DID, so none can be listed |
| `email add <address>` / `email remove <address>` | claim, or take back, an address your commits are authored as, printing `<address> added`, `removed` or `unchanged`; one with no `@` fails `"<address>" is no email address` |
| `profile [--name <text>] [--bio <text>] [--pronouns <text>] [--link <url> [--title <text>]]... [--avatar <file>] [--bot \| --no-bot]` | how you show on knotless, over your Bluesky profile; `''` shows Bluesky's field again, and `--link ''` its links; the avatar is a PNG, JPEG, WebP or GIF, made smaller when over 1 MB; `--bot` says the account is a bot, which its profile marks and the feed leaves out, printed as `bot: yes`, and `--no-bot` takes that back |

### Repositories

| Command | |
| --- | --- |
| `create <url> [--private] [--description <text>] [--link <url> [--title <text>]]... [--default-branch <name>] [--runner <handle>]... [--no-runner]` | create an empty repository; the default branch is `main` unless named; each `--link`, an http or https address, is one its pages show, in order, its website first, up to five, called `--title` if one follows it; `<url> already exists` if it does. Its `runners` are those `--runner` names, none with `--no-runner`, and otherwise those the appview names for new repositories (`dev.knotless.describeServer`); a repository a first push makes names those too. A private one's are made members of it and invited at the appview, so that they find it, each printed as `<handle> reads it, to run its checks: …`; one that could not be invited prints `warning: <did> was not told of it: <why>`. In an organization, says how many of its members may push to it: on a public one, its public members, as a hidden member's merges count only where readers can see them. An admin of an organization makes one in it by naming it in `<url>`, through its gateway; forking, moving or linking one there takes the organization's own login |
| `ls <handle>` | list an account's repositories |
| `refs <url>` | print the refs, in one round trip |
| `search <url> <pattern> [--rev <rev>] [--limit <n>]` | the lines holding a fixed string, in any case, at the default branch or `<rev>`, at most `<n>` (100 by default), as `path:line:text`, read from the cache mirror with no clone; an empty pattern fails `an empty search` |
| `blame <url> <path> [--rev <rev>]` | who last changed each line of a file, at the default branch or `<rev>`, read from the cache mirror with no clone: a line for each run of lines one commit last changed, as `<first>-<last>`, the commit, its author's name, when it was written (UTC) and its subject, tab-separated |
| `diff <url> <at-uri>` | the unified diff a pull would apply: its head, in whichever repository it is, against where it left its base |
| `diff <url> <base> <head>` | what `<head>` changed since it forked from `<base>`, as `git diff base...head` shows it, with no clone |
| `commit <url> -b <branch> -m <message> [options]` | commit without a checkout (below) |
| `branch <url> <name> [<from>]` | create a branch at the default branch, or at a branch or commit, and print its commit; `<url> already has a branch <name>` if it exists |
| `branch <url> <name> --delete` | delete a branch; refuses the default branch (`<name> is <url>'s default branch`) and one that does not exist (`<url> has no branch <name>`) |
| `branch <url> <name> --rename <new name>` | rename a branch, printing `renamed <name> to <new name>`: the new one starts where the old one is, each open pull into it is pointed at the new name, printed `retargeted <at-uri>`, and the old one is deleted. Refuses the default branch. Needs an appview, which lists the pulls |
| `tag <url> <name> [<from>]` | tag the default branch's commit, or that of a branch, tag or commit, and print it; `<url> already has a tag <name>` if it exists. A lightweight tag, naming the commit |
| `tag <url> <name> --delete` | delete a tag, printing `deleted <name>`; `<url> has no tag <name>` if there is none |
| `fork <url> [<name>]` | copy a repository into your account, under its name unless one is given; one's own fails `you own <url>: a fork is of someone else's repository`, and a name you already have fails `<url> already exists` |
| `star <url>` | star a public repository, printing the star's `at://` URI; one already starred keeps its star; a private one fails `<url>: a private repository can't be starred, as a star is public` |
| `unstar <url>` | take your star back, printing `unstarred`, starred or not |
| `stars [<handle>]` | the repositories you, or `<handle>`, starred, newest first: `knotless://<handle>/<name>` and when, tab-separated |
| `notifications [--peek] [--kind <kind>]` | what others did that concerns you, the latest 50, from the appview: `new` (or nothing, once seen), when, why (`star`, `follow`, `pull`, `issue`: on a repository you own, collaborate on, or that an organization you joined owns; `comment`: on your pull or issue, or one you commented on; for a review, `approve` or `changes`; `mention`: a pull, issue or comment that names you as `@handle`; `invite`: an organization's invitation you have yet to answer, with the role it offers, as `as admin`; `checks-failed`: checks failing at your pull's latest run, and `ejected`: the merge queue taking your pull out, each from the runner, with the checks that failed, as `failed test, web`), who, and the repository and title, tab-separated; marks them seen unless `--peek`. `--kind` lists only `mentions`, `reviews`, `comments`, `pulls-and-issues`, `checks` or `stars-and-follows`, and marks none seen, as that would mark seen those of other kinds before them. With no appview, fails `notifications come from an appview, and none is set: set KNOTLESS_APPVIEW` |
| `notifications settings [--on <reason>]... [--off <reason>]... [--followed-only \| --anyone]` | which notifications you hear of, kept by the appview: each reason turned on or off, and with `--followed-only` only of what accounts you follow did (`--anyone` undoes it). Prints every reason the appview gives, `<reason>`, a tab and `on` or `off`, then `from`, a tab and `anyone` or `accounts you follow`; with no flags, only prints them. A reason the appview does not give fails `"<reason>" is no reason: star, follow, …`. `notifications`, MCP and the pages leave out what you turned off. An OAuth login from before this asks for it with a new scope: log in again |
| `follow <handle>` | follow an account on knotless (a `dev.knotless.follow`, not a Bluesky follow), printing the follow's `at://` URI; one already followed keeps its follow; yourself fails `you can't follow yourself` |
| `unfollow <handle>` | take your follows of it back, printing `unfollowed`, followed or not |
| `follows [<handle>]` | the accounts you, or `<handle>`, follow, newest first: handle and when, tab-separated |
| `themes [<handle>] [--find <name>]` | themes made for the pages, from the appview (`dev.knotless.listThemes`), the latest 100: everyone's, or `<handle>`'s, or with `--find` those whose name starts with it, in any case, by name. Each its name, its maker's handle and its `at://` URI, tab-separated; with no appview, fails `themes are listed and chosen by an appview: set KNOTLESS_APPVIEW` |
| `theme check <file>` | whether every text of a palette reads at 4.5 to 1 on what it is drawn on, as the pages hold their own themes: prints `every text reads at 4.5 to 1 or more`, or fails `some text would be hard to read, each needing 4.5 to 1: textMuted on background is 1.2 to 1; …`, each named as the palette names it, or as the pages name a colour they mix from it. `<file>` is JSON, a `dev.knotless.theme#palette` or a record holding one; `-` reads stdin |
| `theme publish <name> <file> [--use]` | publishes the palette, once checked as `theme check` does, as a `dev.knotless.theme` called `<name>` (1 to 64 characters), for anyone to choose, printing its `at://` URI; `--use` draws your pages in it as `theme use` does |
| `theme use <theme>` | draws your pages in a theme, kept by the appview with your preferences, so the pages take it as you next log in to them: `system`, `light`, `dark`, `latte`, `mocha`, `dracula`, `pckt`, `plyr`, `blacksky`, one published, by `at://` URI, whose colours are copied, or a palette of your own, unpublished, from a `.json` file or `-`, checked first. Prints `drawn in <name>` |
| `theme delete <uri>` | deletes a theme you published, printing `deleted`; those who chose it keep its colours. One not yours fails `<uri> is no theme of yours` |
| `followers [<handle>]` | the accounts following you, or `<handle>`, newest first, a handle a line, as the appview counts them; with no appview, fails `an appview counts followers, and none is set: set KNOTLESS_APPVIEW` |
| `describe <url> [--description <text>] [--link <url> [--title <text>]]... [--topic <name>]... [--default-branch <name>]` | as the owner, change what a repository says it is (`''` drops it), the links its pages show (the `--link`s given replace those it had, as `profile`'s do, and `--link ''` drops them), its topics (the `--topic`s given replace those it had, each lowercased and named once, of letters, digits and dashes, at most 50 long and 20 in all; `--topic ''` drops them), and the branch its HEAD names, one of its branches once it has any, printing `description: <text>`, `default branch: <name>`, `topics: <name>, …` when it has any, and a `link: <url> (<title>)` line for each link |
| `owners <text> [--limit <n>]` | the accounts owning public repositories whose handle holds `<text>`, in any case, as the search on the appview's pages finds them (`dev.knotless.searchOwners`): those whose handle starts with it first, at most `<n>` (10 by default, at most 50), each handle and how many public repositories it owns, tab-separated; with no appview, fails `an appview finds accounts, and none is set: set KNOTLESS_APPVIEW` |
| `archive <url> [--undo]` | as the owner, make a repository read only, printing `archived <url> at <time>`, or with `--undo` writable again, printing `unarchived <url>`. While it is archived, pushes and commits to it are refused, by `knotless` and by the gateway, and so are pulls, issues and comments about it, each with `<name> is archived and read only. Its owner can unarchive it.`; runners leave it. One already as asked fails `<url> is already archived` (or `not archived`) |
| `rename <url> <new name>` | rename; the old name redirects; `<new url> already exists` if another repository has the name |
| `transfer <url> <handle or url>` / `transfer <url> --cancel` | offer a public repository to another account, or withdraw the offer |
| `accept <url>` | take a repository offered to you, its pulls and issues included |
| `delete <url> --yes` | delete a repository and everything in it: its records, and what you wrote about it (your pulls, issues, comments, labels, star and reactions on it); run again, a delete cut short carries on |
| `compact <url>` | as the owner, fold its packs into one, printing `<n> packs, <n> folded, <n> old claims dropped` |
| `storage <url> [--json]` | what it takes up on its PDS, from the pack records alone: `<n> packs, <n> objects, <size>, <size> in blobs`, or `{packs, objects, bytes, blobBytes}` |
| `mirror <url>` | sync the cache mirror and print its path |

`commit` takes:

| Option | |
| --- | --- |
| `--put <path> <file>` | write `<file>` at `<path>`; `-` reads standard input |
| `--put-exec <path> <file>` | the same, as an executable (mode 100755) |
| `--delete <path>` | remove `<path>` |
| `--edit <path> <old> <new>` | replace `<old>`, which the file must hold exactly once, with `<new>`, in the file as the branch holds it, keeping its mode; edits to one path are made in turn. A change to part of a file need not send all of it |
| `--author <name> <email>` | the author; by default your handle and `<did>@knotless.invalid`. The committer is the same as the author |
| `--base <commit>` | the commit the changes were made against; a path changed since then is a conflict |
| `--batch` | as the owner, go through the repository's gateway, which batches concurrent commits to the branch |
| `--retries <n>` | how many times to replay onto a branch that moved (default 5); only a `fetch first` refusal is replayed |
| `--json` | print `{sha, parent, attempts, changed}` instead of the commit's hash; through a gateway `attempts` is 1 |

A path is relative, with no empty, `.` or `..` segment, no NUL or newline,
and no `.git` segment in any case. A change that leaves the tree as it was
pushes nothing (`changed: false`). With `--base`, a path changed since then
fails `conflict: <paths> changed since <base>`. An edit whose `<old>` is not
in the file fails `edit <n> of <path>: old is not in the file`, and one it
holds more than once says how many times; an edit to a file not there, or
not a regular file, fails `<path>: no file there to edit`. When the branch
moved, edits are made again in the file as it is there.

### Access

| Command | |
| --- | --- |
| `delegate <handle> <gateway did>` | let a gateway write for you, so collaborators can push through it |
| `share <url> <handle> [--write]` | let an account read a private repository, or push too, printing `shared`; with `--write` before you have delegated your writes to a gateway, delegates them to the appview's first, as `delegate` does, approved in the browser, printing `delegated to <did>` before it |
| `unshare <url> <handle>` | take access away |
| `members <url>` | who may read and push, a line each: the DID, then `owner`, `write` (a collaborator), `member` (of the organization the owner is) or `read`, tab-separated |
| `org add <handle> [--admin] [--org <org>]` | invite an account to your organization, which your account is from then on (the first invitation says so), or change a member's role, which keeps how their membership shows and when they joined; `--admin` makes them an admin, who may also change the organization's members and make repositories as it. With `--org`, to an organization you are an admin of, through its gateway. Says where the invitation is kept: in the organization's space, which only it and its members read, or, on a PDS without spaces, in its public records. An invitation lapses after 7 days; inviting again starts it over. Your organization acts through a gateway, so delegate first (`knotless delegate`) |
| `org remove <handle> [--org <org>]` | take a member out, or withdraw an invitation: they no longer push to its repositories, and leave the spaces of its private ones, but those shared with them on their own |
| `org join <org> --public \| --hidden` | accept an invitation, which makes you a member: `--public`, anyone sees it, and you merge, close and label on all its repositories; `--hidden`, only its members see it, and on its public repositories you push and open pulls, but merging, closing, labelling and queueing take a public membership. Neither, and it says what each means. Again, to change which. Hidden takes a PDS with spaces |
| `org leave <org>` | stop being a member, at once, or decline an invitation; warns if the organization's gateway did not take you out of its spaces, and run again, asks it again |
| `org members [<org>] [--public]` | an organization's members, yours unless named, a line each: the handle (or DID), the role (`admin` or `member`) and the standing (`invited`, `lapsed`, `public` or `hidden`), tab-separated. The organization and its members see every one; anyone else, public members, and `--public` shows them so to whoever asks. Or that it is not an organization, and, for yours, how to make it one |
| `org list [<handle>]` | the organizations an account is a public member of, a handle a line; yours, with no handle, hidden ones too |
| `org delete --yes` | take every member out and withdraw every invitation: your account is no longer an organization. Without `--yes`, says whom it would take out |
| `protect <url> <branch> [--merges] [--queue] [--reviews <n>] [--code-owners] [--dismiss-stale]` | hold collaborators to moving the branch forward, never deleting it, and, without `--merges`, adding no merge commits; with `--queue`, pulls land on it only through the merge queue (see [queue-only branches](../design/merge-queue.md#queue-only-branches)); with `--reviews <n>` (0 to 10), a pull merges into it only once `<n>` of the owner and collaborators other than its author approve it, with `--code-owners` only once an owner of each path it changes does, and with `--dismiss-stale` only approvals of its head as it is now count (see [required reviews](../design/collaboration.md#required-reviews)). It replaces any rule the branch had |
| `unprotect <url> <branch>` | drop a branch's rule |
| `rules <url>` | the protected branches, a line each: the branch and `linear` or `merges`, then `queue` when it takes pulls only through the merge queue, then `reviews <n>`, `code owners` and `dismiss stale` as it asks for reviews, tab-separated; `protect` and `unprotect` print the same |

### Pulls and issues

| Command | |
| --- | --- |
| `pull <url> <base> <head url> <branch> <title> [-m <body>] [--image <file>]... [--draft] [--reviewer <handle>]...` | open a pull to merge `<branch>` of `<head url>` into `<base>`; `-m -` reads the body from stdin; each `--image` uploads a picture and shows it after the body, by its file's name, at the size its density says ([collaboration.md](../design/collaboration.md#pictures)); `--draft` opens it as a draft, which neither merges nor queues until marked ready; each `--reviewer`, by handle or DID, asks an account to review it, which it hears of once the pull is not a draft ([drafts and requested reviewers](../design/collaboration.md#drafts-and-requested-reviewers)). Asking yourself fails |
| `issue <url> <title> [-m <body>] [--image <file>]...` | open an issue |
| `template <url> pull [<base>]` / `template <url> issue` | what the repository asks a pull's or issue's title and body to follow ([templates](../guide/collaborating.md#write-from-the-repositorys-templates)) |
| `list <url> [--pulls \| --issues] [-q <query>]` | pulls and issues, newest first; `-q` filters them in GitHub's search words ([collaboration.md](../design/collaboration.md#filtering-pulls-and-issues)) |
| `show <url> <at-uri>` | a pull or issue and its comments, each followed by a `reactions: +1 2  heart 1` line when anyone reacted, as the appview counts them, or for a private repository as its space has them |
| `comment <url> <at-uri> <text> [--approve \| --changes] [--image <file>]... [--line <path>:<n>[-<m>][:old] <text>]...` | comment, or review: a pull only, and not one you opened. Each `--line` comments on lines of the pull's diff at its head, `:old` for lines it removes, starting a thread; sent with a `<text>` or verdict, as that review's, otherwise on their own (`<text>` may then be `''`); at most 100. Given a comment's URI, answers it in its thread |
| `resolve <url> <comment-uri>` / `unresolve <url> <comment-uri>` | resolve the thread a comment on a pull's lines starts, or open it again: its author, the pull's, the owner or a collaborator |
| `edit <url> <at-uri> [--title <title>] [-m <body> [--image <file>]...] [--draft \| --ready] [--reviewer <handle>]... [--no-reviewer <handle>]...` | change your pull, issue or comment; `-m ''` drops a pull's or issue's body, `-m -` reads it from stdin; the pictures it keeps are those the new body shows. For a pull, `--draft` makes it a draft and `--ready` marks it ready, asking its reviewers again as of now; `--reviewer` asks another account to review it and `--no-reviewer` stops asking one. Any of these on an issue or comment fails `<at-uri> is not a pull` |
| `delete-comment <url> <at-uri>` | take back your comment or review |
| `react <url> <at-uri> <content> [--undo]` | react to a pull, issue or comment with `+1`, `-1`, `laugh`, `hooray`, `confused`, `heart`, `rocket` or `eyes`, printing the reaction's `at://` URI; one already there is kept; `--undo` takes it back, printing `taken back`; on a private repository the reaction is written in its space, as a comment is |
| `close <url> <at-uri>` / `reopen <url> <at-uri>` | change an item's state |
| `label <url> <at-uri> <label>...` / `unlabel <url> <at-uri> <label>...` | as owner, collaborator or a triager of their scope, put labels on an item or take them off; prints those it carries now |
| `labels <url>` | the labels a repository defines: name, color, `exclusive` and description, tab-separated |
| `labels <url> add <name> [--color <#hex>] [--description <text>] [--exclusive]` / `labels <url> remove <name>` | as owner, define a label (or redefine it), or take one away, off everything it is on |
| `triagers <url> [add <handle> <scope>... \| remove <handle>]` | the accounts, such as a triage bot, whose labels of those scopes count, below the owner's and collaborators'; as owner, name one or stop naming it. Prints each as its DID and scopes, tab-separated. Named for a private repository, it is made a member of its space and invited, as a runner is, and `warning: <did> was not told of it: <why>` follows when the invite could not be left |
| `triagers <url> eval <handle>` | how an account's labels compare with everyone else's, one line per scope the repository defines, in the order of its labels: the scope, the pulls and issues the account put a label of it on, how many of those someone else did too, and how many of those it agreed on (everyone else's labels of the scope, worked out without the account's, are its own), tab-separated |
| `merge <url> <at-uri> [--keep-branch] [--wait <secs>] [--force]` | merge a pull; `--wait` waits for its checks, and `--force`, the owner's alone, merges past them (see [the merge gate](#the-merge-gate)). Into a branch protected with `--queue`, it queues the pull instead, unless forced |
| `merge <url> <at-uri> --queue` | put a pull in its branch's merge queue, and return, printing `queued into <base>: <n> of <of>`; takes no `--keep-branch`, `--wait` or `--force` |
| `merge <url> <at-uri> --check` | merge nothing: say whether it would merge now, how, and what you may do to it, as a pull's page's merge box shows it |
| `revert <url> <at-uri> [-m <reason>]` | as owner or collaborator, undo a merged pull: one commit on a new branch `revert/<rkey>`, cut from its target branch, and a pull of it into that branch, titled `Revert "<title>"`; prints the new pull's URI. See [reverting a pull](../design/collaboration.md#reverting-a-pull) |
| `queue <url> [--json]` | the merge queues in order, and what was ejected |
| `queue <url> --leave <at-uri>` | take a pull out of the merge queue |
| `retarget <url> <at-uri> [--base <branch>] [--head <branch>]` | point a pull at other branches; the head only by the pull's author |

What they print:

| Command | Output |
| --- | --- |
| `pull`, `issue` | the new record's `at://` URI |
| `comment` | the `at://` URI of each comment it wrote, a line each: the review first, then its comments on lines |
| `resolve`, `unresolve` | `resolved`, `unresolved` |
| `list` | a line per item: `<kind>`, `<state>`, `<uri>`, `<title>`, tab-separated |
| `show` | `<state> <kind> by <author>: <title>`, then `draft` for a draft pull, `review requested: <handles>` for one that asks for reviews, then `closed by <pull>` for an issue a pull closed, `mentioned in <pull>` for each pull whose title or body names an issue, oldest first, ending `, to close it` where it names it after a closing keyword, `reverts <pull>` for a revert, `reverted by <pull>` for a merged pull whose revert merged, then for a pull each reviewer's standing review as `review: <reviewer> <verdict> at <commit>` (the first 12 characters of the head it looked at), then for an open pull in or ejected from the merge queue `merge queue: <state> at <createdAt>` and where it stands, and for one ejected as checks failed `logs: <command>`, the `knotless checks` that reads their logs, then the body and each comment as `<author> [<verdict>]: <body>`, where a comment on lines says ` on <path>:<lines>[:old] (<uri>[, resolved])` before the colon, and an answer in a thread ` answering <uri>` |
| `merge` | the commit the branch is now at, then `deleted <branch>` and a `closed <issue>` line per issue it closed; queued instead, `<base> takes pulls through the merge queue: queued, <n> of <of>`, then where to follow it |
| `merge --queue` | `queued into <base>: <n> of <of>`, then where to follow it |
| `merge --check` | `<state>`, `<method>` and `checks <checks>`, and `reviews <passed or blocked>` when its branch asks for reviews, tab-separated, then a `missing <what>` line for each thing its reviews lack (`reviews 1 of 2`, `owners of web/: @alice or @bob`, `changes asked by @carol`; owners who are the pull's author alone add `, its author alone, whose own approval never counts, so web/ needs another owner in CODEOWNERS`), an `uncounted <why>` line for each approval that does not count (`@dan's approval does not count: only the owner's and collaborators' approvals count`), a `warning <what>` line for each CODEOWNERS line skipped, a `conflict <path>` line per file that conflicts, `deletes <branch>` for the branch it would delete, `may <what>`, `queue only` when its branch takes pulls only through the merge queue, and last why it cannot merge, in the words `merge` would refuse with, and that the caller may not merge it when it may not |
| `queue` | a line per pull: `<position>`, `<base>`, `<state>`, `<uri>`, `<title>`, tab-separated, where the state is `queued`, `pre-flight <workflows>` while the [pre-flights](workflows.md#the-merge-queue) it waits for run, comma-separated, or `<checking or landing> at <commit>`; an ejected pull has `-` and `ejected`, and a line after it with the reason; `the merge queue is empty` if it is |
| `queue --json` | each pull waiting, with its `place` and `batch`, or the `preflight` workflows it waits for |
| `queue --leave` | `left the merge queue` |
| `edit`, `delete-comment`, `close`, `reopen`, `retarget` | `edited`, `deleted`, `closed`, `open`, `retargeted` |

`merge --queue` refuses `--keep-branch`, `--wait` and `--force` (`--queue
takes none of --keep-branch, --wait and --force`), and `merge --check`
those and `--queue`. Its state is `clean`, `conflicting`, `blocked` by
its checks or its reviews, or `draft`, whatever else holds, until its
author marks it ready (`merge` and `merge --queue` refuse one, in the
words its reason gives); its checks are `passed`, `failed`, `running`, `pending` (not run at
its head merged with its base as it is now) or `none` (the repository
names no runners, or has no workflow that runs on the pull, so nothing is
waited for, or it conflicts); its method
`fastForward`, `merge` or `squash` (into a branch protected as linear).
`may` lists, comma-separated, what you may do to it: `merge` and `queue`
(the owner and collaborators, the queue only with runners), `force` (the
owner), `base` and `head` as `retarget` changes them (those who may close
it, and its author), and `rerun` (the owner, with runners). `queue` takes one flag,
`--leave` or `--json`. `show` reads an item under a minute old from its
author's repository when the appview has not indexed it yet. Where the
merge queue's `standing` lines come from is in [the merge
queue](../design/merge-queue.md).

### Checks

| Command | |
| --- | --- |
| `agents <url> [add \| remove <handle>]` | the accounts, such as a coding agent, whose pulls the runners check as they move, as code no one vouches for (see [the runner](../design/runner.md#whose-code-runs)); as owner, name one or stop naming it, printing `added` or `removed`. Prints each as its DID |
| `minutes <url>` | the minutes each runner the repository names counts for its owner's public repositories in the last 30 days, a line each: the runner, then `<n> of <allowance> min in 30 days` (adding `past it: runs go one at a time` once past), `<n> min in 30 days, no allowance`, or `nothing counted yet`, and the soonest minutes to free up. Each runner counts on its own (see [the runner](../design/runner.md)) |
| `runners <url> [add \| remove <handle>]` | the accounts whose checks of the repository readers show; `add` makes the account a member of a private repository, and invites it as `create` does (`added`, then `warning: …` if it could not be), which `remove` leaves it (`unshare` takes it back). A runner added after secrets were set has none of them, as nothing keeps their values to seal again: `warning: <did> gets the secrets set before only once each is set again: <names>`. `remove` deletes the secrets sealed to it |
| `secret <url> set <name> [--ref <pattern>]... [--runner <handle>]...` | as owner, give the repository's runners the secret `<name>`, read from stdin less one line ending, sealed to the key each publishes so only it reads it, and left at the appview (`KNOTLESS_APPVIEW`), replacing one of the same name; `--ref`, repeatable, limits it to pushes to those refs, as a trigger's `refs` match; `--runner`, repeatable, by handle or DID, gives it to those of the repository's runners alone, and takes back the copy any other of them had. Prints `sealed <name> to <runners>`. Fails if the repository names no runners, a `--runner` is not one of them, or one it seals to publishes no key (a knotless-run from before). `<name>` is a shell variable's, not starting `KNOTLESS_RUN`; the value at most 16 KiB, the refs at most 16. See [Secrets](../design/runner.md#secrets) |
| `secret <url> ls \| rm <name>` | as owner, each secret given, one line per runner, `<name>\t<runner>\t<refs, or *>\t<updated>`, never a value; or take one back from every runner, printing `removed <name>` |
| `checks <url> [--ref <name>] [--commit <sha>] [--pull <at-uri>] [--queue <branch>] [--workflow <name>] [--log] [--images <dir>] [--wait <secs>] [--json]` | what those runners report, newest first; `--ref`, of pushes to that ref and runs asked for there, in full or a branch or tag named bare, as `main` (a pull's are read with `--pull`); `--queue`, of the merge queue's batches; `--log` adds the end of each log; `--images` saves each check's pictures; `--wait` waits for runs to finish |
| `rerun <url> --ref <name> \| --pull <at-uri> [--workflow <name>]` | as owner, ask the runners to run it again, or only one of its workflows |
| `rerun <url> --ref <name> --workflow <name> [-e <name>=<value>]...` | as owner, ask for one workflow there, with variables its steps see |
| `workflows <url> [<ref>]` | the workflows at a branch or tag (the default branch), and what runs each there |

`checks` prints a line per check: `<status>`, `<workflow>`, the pull's URI
or the ref, the commit's first 12 characters, `startedAt` and any
`skipped` note, tab-separated. `--log` follows it with the log, and
`--images` ends the list with an `image` line per picture saved, then a
tab and its path, named `<workflow> <alt>.<ext>` with `/` as `-`.
`--queue` takes a bare branch name. `--commit` takes a commit's hex ID or
at least its first 4 digits, as `git log --oneline` prints them, in either
case; anything else fails with `a commit is its hex ID, or at least its
first 4 digits, not "<given>"`. `--wait` reads again every
`KNOTLESS_POLL_MS` until it has found a check and none is queued or running, or the
time is up. Up with none found, it fails with `no checks of <what was
asked> after <secs>s`, such as `commit 0838c57, ref refs/heads/main`,
rather than print nothing and exit 0. Reads that fail in a way that may pass (a connection error, a
timeout, a 5xx or a 429) are retried with a backoff of up to 60 s. The MCP `checks` tool waits at most 300 s,
and returns the pictures with `images: true`. A repository naming no
runners is an error, not an empty list. A private repository's checks,
logs and pictures are read from its runners' repos in its space, with a
space credential.

`rerun` writes a `dev.knotless.rerun` record in the owner's account and
prints its AT-URI. A bare branch or tag is taken as its full ref, and a ref
the repository lacks is refused (`<url> has no ref <name>`), as is a
repository naming no runners. It asks for one ref or one pull (`name one
ref or one pull to run again`); `-e` needs `--workflow` (`variables go
to one workflow: name it`) and a ref (`variables go to a workflow run at
a ref, not a pull's`). At most 32
variables: a name is 1 to 64 letters, digits or `_`, not starting with a
digit or with `KNOTLESS_RUN`, and a value at most 4096 bytes.

`workflows` prints the ref in full, then a line per workflow in file name
order: its name, then what runs it there, comma-separated, of `push`,
`pull` (a pull into it) and `asked` (`rerun --ref --workflow` may ask for
it: it runs on a push there, or its `asked` trigger names the ref), then,
for one that does not load, why. A ref it lacks is refused (`<url> has no
ref <name>`).

### Releases

| Command | |
| --- | --- |
| `publish <url> <package> <version> <file>... [--commit <sha>] [--check <at-uri>] [--notes <text>] [--oci <dir>]` | as owner, publish a version of a package: its files, uploaded as blobs, then its `dev.knotless.release` record, never changed after (see [releases](../design/packages.md)). Prints the record's AT-URI. `--notes -` reads the notes from stdin |
| `releases <url> [<package>]` | the versions published, by package and then highest version first |
| `download <url> <package> [<version>] [--file <name>]... [-o <dir>]` | a version's files, or the latest's, each checked against its size and SHA-256, into a directory (`.`) |

`publish` names each file by its path's last part. A package's name
follows npm's rules: lowercase letters, digits, `-`, `.`, `_` and `~`, not
first a `.` or `_`, after an optional `@scope/`, at most 214 bytes. A
version is Semantic Versioning 2.0, such as `1.4.0` or `2.0.0-rc.1`. A
release holds 1 to 64 files, by distinct names of letters, digits, `.`,
`_`, `+` and `-`, not first a `.`, and none empty. Each is split into
blobs of `KNOTLESS_CHUNK_SIZE` as a large pack is. In a runner's step,
`--commit` is `KNOTLESS_RUN_SHA` unless given. A version published before
is refused before anything is uploaded, and by the record's create if
another publish got there first: `<package> <version> is published
already: <at-uri>`. A private repository's are refused: `a private
repository's releases are not published yet`.

`--oci <dir>` publishes an image, for knotless-serve's registry at `/v2/`
([api.md](api.md#images)): the files of the OCI image layout in `dir`,
as `docker save` or `docker buildx build --output type=oci,tar=false`
leaves one, beside any named. They are its `index.json`, which must name
one manifest (`index.json names more or less than one manifest`), and
each blob under `blobs/sha256` as `sha256-<hex>`, checked against its
name (`blobs/sha256/<hex> is not the blob its name says`); the manifest
the index names must be among them (`index.json names <digest>, which is
not among the blobs`). As a release holds at most 64 files, an image
holds at most 63 blobs, its manifests, configs and layers together.

`releases` prints a line per version: the package, the version,
`createdAt`, the commit's first 12 characters (or `-`) and the files'
names, comma-separated, tab-separated.

`download` takes the package's latest, its highest version without a
pre-release part, unless a version is named, and every file unless
`--file` names some. It prints a line per file: the package, the
version and the path written, tab-separated. A file whose bytes do not
match fails with `<name>: what was read is not the file its release
names`; a version or file the release lacks with `<url> has published no
<package> <version>` (`latest` for none) or `<package> <version> has no
file <name>`.

### Shared steps

| Command | |
| --- | --- |
| `uses update [-C <dir>] [<uses>...]` | pin the shared steps the checkout's workflows use, and those they use, in `.knotless/uses.lock` (see [shared steps](../design/reusable-workflows.md)): each to the highest release its `@` takes; with `<uses>` named, only those, the rest as the lock had them |

A shared step is released as the package `@step/<step>` with `publish`,
its one file the step file and `--commit` the commit it is at. `uses
update` reads the workflows under `.knotless/workflows` in `dir` (`.`),
and takes for each `uses` the highest version that its `@` takes, of
those without a pre-release part unless the `@` has one. It prints a
line per `uses` pinned: the `uses`, the version it was pinned at (or
`-`), the version now and the commit's first 12 characters,
tab-separated. It fails, writing nothing, with `<dir> has no
.knotless/workflows`; `<url> has released no @step/<step> that @<spec>
takes`; `@step/<step> <version> names no commit it was made from`;
`@step/<step> <version> holds no <step>.yml`; `@step/<step> <version>'s
<step>.yml is not .knotless/steps/<step>.yml at <commit>`, when the file
released and the file at its commit differ; or when the step file
cannot be read at that commit.

### The merge gate

In a repository naming runners, `merge` refuses a pull until each
workflow that runs on it has passed at its head merged with its base as
it is now ([design](../design/runner.md#the-merge-gate)). It says which:

- `<pull> did not pass its checks at its head, <h12>, merged with
  <branch> at <b12>: <workflow> (<status>), ...`
- `... are still running: ...`, each still waiting for a job on its
  runner named `<workflow> (queued)`, with `` `--wait <secs>` waits for
  them ``
- `<pull> has no checks at ... of <workflows>`, then why: none has run
  yet, the newest are of an older head, or the newest are of the branch
  at another commit, and `It is not checked yet`

Each ends ``Their logs: `knotless checks <url> --pull <pull> --log`; the
owner merges past them with `--force` ``. `--force` from anyone else is
refused: `only the owner of <url> merges a pull past its checks`. Over
MCP, `merge` takes `wait` (at most 300 s) and `force`.

### Moderation and operations

| Command | |
| --- | --- |
| `hide <url> <at-uri>` / `unhide <url> <at-uri>` | as owner, hide a pull, issue or comment |
| `block <handle> [<url>]` / `unblock <handle> [<url>]` | leave out what an account writes about your repositories, or about one, printing `blocked <did>` or `unblocked <did>`; yourself fails `that is you`, another's repository `only <url>'s owner can keep accounts out of it` |
| `blocks` | the accounts you block, the latest first: handle, `all your repositories` or the repository's `knotless://` URL, and when, tab-separated. Blocks naming a private repository live in its space, and are not listed |
| `report <handle, url or at-uri> <reason> [-m <text>]` | report to the moderation service; the reason is `spam`, `violation`, `misleading`, `sexual`, `rude` or `other`; prints `report <id> sent` |
| `admin takedown <handle, url or at-uri> [--undo]` | as the appview's operator, take a subject down, or restore it; prints `taken down` or `restored` |
| `admin status <handle, url or at-uri>` | as the operator, a subject's moderation status: `taken down` or `up` |
| `admin reports [<limit>]` | as the operator, the reports received, newest first (default 50): a line per report of `<id>`, `<reporter did>`, `<reason>`, `<subject>`, `<text>`, tab-separated |
| `admin stats [--days <n>] [--json]` | as the operator, how the appview is used, day by day, from `dev.knotless.getUsage` (14 days by default) |
| `admin logs [--trace <id>] [--message <m>] [--level <l>] [--min-ms <n>] [--limit <n>]` | as the operator, the lines the appview logged, from `dev.knotless.getLogs`, one JSON line each, oldest first: a request's by its trace (up to 500, unless `--limit` says fewer), or the last (100 by default, at most 500) of a message, a level and above, or a time; one of them is needed |
| `status [<server>] [--repo <handle>/<name>] [--json]` | a `knotless-serve`'s health, from `/_status`: its feeds, index, a mirror and its disk's room; the server defaults to `KNOTLESS_APPVIEW` |

A report's reason is sent as `com.atproto.moderation.defs#reason<Name>`,
as `reasonSpam`. Its subject is a `com.atproto.admin.defs#repoRef` for a
handle or DID, and a `com.atproto.repo.strongRef` with the record's
current CID for an `at://` URI, or for a `knotless://` URL's `repo`
record. It goes to the `#atproto_labeler` service of `KNOTLESS_MODERATOR`'s
DID document, else of the appview's `/.well-known/did.json`, with a service
token from your PDS; with neither set it is an error. The `admin` commands
need an appview (`KNOTLESS_APPVIEW`) and an account it names in
`KNOTLESS_ADMIN_DIDS`: each call carries a service token from your PDS
for its method, made out to the DID in the appview's
`/.well-known/did.json`.

`status` fails with `<server> is unhealthy` when `/_status` says it is
not, and with `status takes the server's URL: KNOTLESS_APPVIEW is set empty` when it
has neither.

## knotless-serve

| Flag | Default | |
| --- | --- | --- |
| `--listen <addr>` | `127.0.0.1:2590` | where to listen |
| `--ttl <secs>` | 5 | how old a mirror may be before a read syncs it, when no feed is up; whole seconds |
| `--jetstream <wss://host>` | | a Jetstream v2 host to follow |
| `--firehose <wss://relay or pds>` | | a firehose to follow instead |
| `--index <file>` | | keep an appview index in this SQLite file |
| `--backfill <https://pds or relay>` | | at start, index every account on a PDS, or those holding knotless records on a relay |
| `--relay <https://relay>` | | backfill from this relay when the index was rebuilt (a new file, or another build's tables), and every ten minutes after |
| `--public-url <https://host>` | | the URL the server is reached at; makes it a gateway, as `did:web` of the host, and serves MCP at `/mcp` |
| `--labeler <did>` | | honour this labeler's takedowns; repeatable |
| `--default-runner <did>` | | the runner a new public repository names unless its owner names others, as `dev.knotless.describeServer` answers; one only, as each runner a repository names runs all its checks (`--default-runner names one runner`); empty, none; anything else not a DID is refused (`--default-runner takes a DID, not <value>`) |
| `--client-minimum <version>` | | the oldest client version this appview asks for, as `dev.knotless.describeServer` answers: older clients refuse to run until upgraded. For a release found to harm repositories; anything not a version is refused; empty, none |
| `--client-minimum-reason <text>` | | why, which those clients print with their refusal |
| `--web <http://app>` | | the SvelteKit app that draws the pages |
| `--releases <dir>` | | client builds to hand out under `/releases`, with `/install.sh` |
| `--stale <secs>` | 120 | how long a feed may be silent before `/_status` calls it dead; whole seconds |
| `--usage <file>` | | count requests and page views in this SQLite file, for `knotless admin stats` |
| `--logs <file>` | | keep each line logged in this SQLite file too, for `knotless admin logs`: every serve writing it, across deploys, for 30 days |
| `--logs-keep <lines>` | 500000 | how many lines at info and below `--logs` keeps, the last of them; those above stay their 30 days |
| `--check-index <file>` | | only check that the index there is of this build's tables, so starting would keep it |
| `--metrics <addr>` | | answer `/metrics` (Prometheus) and `PUT /log` (the log's level) there, apart from the rest; prints `metrics on <url>` after `listening on` |
| `--sign-up-pds <https://pds>` | `https://selfhosted.social` | the PDS where the pages send someone making an account ([Logging in](../design/serve.md#logging-in)) |
| `--oauth-url <https://host>` | `--public-url` | where the PDS sends the gateway's OAuth logins back to, when that is not `--public-url`: an https front for a server at a loopback address, as the scenarios run it |
| `--bots <dir>` | | let the accounts `KNOTLESS_BOT_DIDS` names log in at `/oauth/bot`, keeping their sessions in this config directory for `knotless-run` and `knotless-triage` ([Bots](../design/gateway.md#bots)) |

An empty `--jetstream`, `--firehose`, `--backfill` or `--default-runner` is the same as none,
so a setting such as `--firehose "$KNOTLESS_FIREHOSE"` left unset turns it
off. `--labeler` takes `--index`. `--private` is gone, and refused
(`--private is gone: knotless-serve shows a private repository to each
member who logs in to its pages (--public-url), read as them, …`): a
server people log in to shows each member their private repositories.
`--bots` takes `--public-url` (`--bots takes --public-url, where bots
log in`), and
a `--public-url` is `http(s)://host[:port]` with no path.

An unknown flag prints `unexpected <flag>` and the usage, and a flag
without its value `<flag> takes a value`; `--ttl` and `--stale` that are
not whole seconds print `--ttl takes seconds` or `--stale takes seconds`.
These exit 2. An error once started prints `knotless-serve: <error>` and
exits 1. Once bound, it prints `listening on http://<addr>`, and it stops
cleanly on SIGTERM or SIGINT.

`--check-index <file>` prints `<file>: this build keeps it`, and passes a
file that does not exist. It fails with `<file>: its tables are version
<v>, this build's <version>: starting would rebuild it` otherwise.

`/install.sh`, served with `--releases`, installs `knotless`,
`git-remote-knotless` and `knotless-mcp` for `aarch64` or `x86_64`, macOS
or Linux (musl), with curl or wget. It checks each download's SHA-256, and
moves each binary into place, so a running copy is replaced. The routes
are in the [API reference](api.md#releases).

## knotless-run

`knotless-run [flags] <handle>/<name>...` watches the repositories
named, and with `--discover` those whose records name its account as a
runner (then it needs none named), acting as `KNOTLESS_IDENTIFIER` with `KNOTLESS_PASSWORD`, or as
the account logged in with `knotless login`. A private repository takes
an OAuth login, for a space credential, and the runner's account a
member of it: `knotless create --private` and `knotless runners <url>
add` make it one, and invite it, which `--discover` reads.

| Flag | Default | |
| --- | --- | --- |
| `--executor docker \| shell` | `docker` | run steps in a container, or as the runner's user (the library's `Options::new` defaults to `shell`) |
| `--image <image>` | `debian:stable-slim` | the image for a workflow that names none |
| `--jobs <n>` | 4 | runs at once, over every repository |
| `--pull-jobs <n>` | half of `--jobs`, at least 1 | of those, how many runs other than pushes to a default branch and the batch landing next may take; at most `--jobs` |
| `--owner-jobs <n>` | all of `--jobs` | of those, how many the runs of one owner's repositories may take; at most `--jobs` |
| `--allowance <minutes>` | none | the minutes of steps each owner's public repositories' runs may take in 30 days, the runner's own account's aside; past it, that owner's runs go one at a time |
| `--private-allowance <minutes>` | none | the same for private repositories' runs, counted apart |
| `--unmetered <did>` | none | an owner whose runs, like the runner's own account's, count against neither allowance, and may take every job, past `--owner-jobs`; repeatable |
| `--step-timeout <secs>` | 1800 | the longest a step may run, and a container may take to start |
| `--run-timeout <secs>` | none | the longest a run's steps may take together; a step going when it is up is killed and the rest skipped. A run asked for by name is not held to it |
| `--cpus <n>` | none | under `docker`, the CPUs a run's container may use, as docker's `--cpus` takes them (`2`, `1.5`) |
| `--memory <GiB>` | none | under `docker`, a whole number of GiB a run's container may use, with no swap beyond it; past it the kernel kills what is running and the step fails |
| `--pids <n>` | none | under `docker`, the processes and threads a run's container may have at once |
| `--network <name>` | docker's default bridge | under `docker`, the network runs join; made if missing as a bridge whose containers cannot reach each other, used as it is if there already |
| `--runtime <name>` | docker's default (`runc`) | under `docker`, the runtime runs' containers start with, as docker's `--runtime` takes one: `runsc` runs them under gVisor, a kernel of its own between a run and the host's. The daemon must know it (see [the runner host](../../deploy/runner-host/README.md)) |
| `--trusted-runtime <name>` | `--runtime`'s | under `docker`, the runtime of a run whose code an owner `--trust` names vouches for: a push to their repository, or a pull or batch every writer of which they vouch for. `runc` spares it gVisor's cost |
| `--trust <did>` | none | an owner whose vouched-for runs start under `--trusted-runtime`; repeatable |
| `--resolv <file>` | docker's | under `docker`, a file on the docker host that runs' containers see as their `/etc/resolv.conf`. Under `runsc` on a network docker made, a run resolves no names without one: docker's resolver there is reached through NAT rules gVisor does not apply |
| `--paused <file>` | none | a JSON object of owner DIDs, or `*` for all but the runner's own account, each to why their runs are paused; read again on every pass, so editing it takes effect without a restart. A paused owner's runs are filed as `error`: `paused by this runner's operator: <why>` |
| `--keep-checks <days>` | 30 | how long the default branch's checks are kept, each workflow's newest whatever its age; the runner [prunes](../design/runner.md#pruning) its checks of no more use each hour. 0 keeps every check |
| `--sweep <secs>` | 600 | how often every repository is read again, in case an event was missed, and leftover containers removed |
| `--stop-wait <secs>` | 900 | how long a stop waits for runs going before it cancels them; 0 waits not at all |
| `--poll <secs>` | 10 | how often a private repository's space is asked whether anything was written there, which Jetstream never carries; while `KNOTLESS_APPVIEW`'s appview passes on its writes, no more often than once a minute (see [Private repositories](../design/runner.md#private-repositories)) |
| `--cache-max <GiB>` | 16 | a whole number of GiB: the size at which a cache's new base is not used, to start afresh, and the most kept layers may take in all |
| `--disk-floor <GiB>` | 20 | a whole number of GiB kept free on the disk `--caches` is on: below it, a run about to start first sheds every cache's base no run reads and every kept run's layers, then waits for room, looking every 30s; 0 keeps no floor (see [Room on the disk](../design/runner.md#room-on-the-disk)) |
| `--caches <dir>` | `<cache dir>/run/caches` | where caches' bases and runs' layers are kept; a path the docker daemon sees under the same name |
| `--secrets <file>` | | the [secrets file](workflows.md#secrets-file) |
| `--secrets-key <file>` | `secrets-key.json` beside the state file | where the runner keeps the key owners seal secrets to, made if missing, and published as its `dev.knotless.runnerKey` record (see [The runner's key](../design/runner.md#the-runners-key)) |
| `--state <file>` | `<cache dir>/run/state.json` | the state file |
| `--work <dir>` | the system's temporary directory | where checkouts go while their steps run; made if missing |
| `--jetstream <wss://host>` | `wss://jetstream2.us-east.bsky.network` | where events come from |
| `--discover` | off | also watch every public repository whose record names this runner's account in `runners`, as the appview's `listRepos?runner=` lists them and Jetstream brings them; one no longer naming it is left. Needs `KNOTLESS_APPVIEW` (see [Repositories that name it](../design/runner.md#repositories-that-name-it)) |
| `--pulls` | off | also run open pulls, at their head merged with their base, without secrets; takes `docker` |
| `--pulls-only <handle>/<name>` | none | watch that repository for its open pulls alone, never its pushes or its merge queue, which another runner runs; as there, a queued pull does not run on its own, and the rest run again as their head moves, not their base; repeatable; takes `--pulls` |
| `--queue` | off | land the repositories' [merge queues](../design/merge-queue.md) where its account may push, or where they name it and no runner that may ([Who lands a queue](../design/merge-queue.md#who-lands-a-queue)); takes `docker` |
| `--batch <n>` | 8 | with `--queue`, the most pulls in a batch |
| `--depth <n>` | 2 | with `--queue`, 2 checks the next batch on top of the one being checked; 1 turns that off; nothing else |
| `--notice <secs>` | 30 | with `--queue`, how often the owner's and collaborators' queue records are read |

`<cache dir>` is `KNOTLESS_CACHE_DIR`'s. `--jobs`, `--pull-jobs`, `--owner-jobs`, `--allowance`, `--private-allowance`,
`--sweep`, `--batch`, `--notice`, `--poll`, `--run-timeout`, `--memory`
and `--pids` take at least 1, as in `--batch takes
a number of pulls, at least 1` and `--notice takes a number of seconds, at
least 1`. `--depth 0` is refused with `--depth takes a number of batches,
at least 1`, and more than 2 with `--depth is 1 or 2: one batch at most
runs ahead`. `--pulls` and
`--queue` refuse `--executor shell` (`--pulls and --queue run code anyone
can open a pull with: they take --executor docker`), and so do `--cpus`,
`--memory`, `--pids`, `--network`, `--runtime`, `--trusted-runtime` and
`--resolv` (`--cpus, --memory, --pids, --network, --runtime,
--trusted-runtime and --resolv hold a run's container: they take
--executor docker`).
`--cpus` takes a number above 0 (`--cpus takes a number of CPUs, more
than 0, not <value>`). `--pulls` refuses
to start with `KNOTLESS_APPVIEW` set empty; `--queue` starts so, but
its reads of pulls then fail. A repository that cannot be found stops the
start: `<label>: no repository by that name this runner can read`.

A usage error exits 2 and prints the usage; an error at run time exits 1,
as `knotless-run: <error>`. Once started, the runner logs `knotless-run:
watching <repositories> as <did>` to standard error, and an error in one
repository as `knotless-run: <label>: <error>`, and goes on: the same
error again only once a minute, with how many times it was seen. Each pass
logs how long it took, and one going 5 minutes says where it is, every 5
minutes ([What a pass logs](runner-internals.md#what-a-pass-logs)). A pass that
finds a repository's key changed fails with `<label> no longer names the
repository it did`.

It follows Jetstream's `subscribeEvents` for the `dev.knotless.*`
collections, with `commit`, `identity`, `account` and `sync` events, over
the `xrpc.v1.json` websocket subprotocol, without a cursor. After a
session ends it connects again in 500 ms, doubling the wait after each
failed attempt up to 60 s, and back to 500 ms once connected. A
connection silent for 60 s gets a ping, and silent another 60 s is given
up.

What the runner keeps on disk, its containers and its volumes are in
[knotless-run internals](runner-internals.md).

## knotless-triage

`knotless-triage (--decide <url> --model <name> | --classify <command>)
--scopes <scope>,... [flags] [<handle>/<name>...]` triages the repositories
named, and with `--discover` those naming it, acting as
`KNOTLESS_IDENTIFIER` with `KNOTLESS_PASSWORD`, and reads public
repositories' issues through `KNOTLESS_APPVIEW`.

| Flag | Default | |
| --- | --- | --- |
| `--decide <url>` | | a decision model's endpoint: one taking `{model, state, questions}` with a bearer token, as TypeSafe's Jev (`https://api.typesafe.ai/v1/systemone`) or Cloudflare's Clef on Workers AI (`https://api.cloudflare.com/client/v4/accounts/<account>/ai/run/@cf/cloudflare/clef`) do. Its token is `KNOTLESS_DECISION_TOKEN` |
| `--model <name>` | | with `--decide`, the model asked, as `jev-latest`, `clef` or `clef-flash` |
| `--threshold <p>` | 0.5 | with `--decide`, the least probability, from 0 to 1, that sets a label |
| `--classify <command>` | | instead of `--decide`, a command run with `sh -c` once per issue to judge |
| `--scopes <scope>,...` | | the scopes it chooses labels of, as `kind,area` |
| `--jetstream <wss://host>` | `wss://jetstream2.us-east.bsky.network` | where events come from |
| `--sweep <secs>` | 600 | how often every repository is read, whatever events say |
| `--settle <secs>` | 5 | how long after an event the repository is read, for the appview to index the issue |
| `--timeout <secs>` | 120 | how long the classifier has for an issue before it is killed |
| `--once` | off | read each repository once, and stop |
| `--discover` | off | also triage every repository whose record names this account in `triagers`, in the scopes it names it a triager of that `--scopes` holds: those the appview's `listRepos?triager=` lists, private ones that invited it, and those Jetstream brings, at the start and every `--sweep`. One no longer naming it, or that cannot be read, is left, and found again if it still names it. Needs `KNOTLESS_APPVIEW` |

A decision model is asked one question per scope whose labels are all
exclusive, a `choice` among them named by their names after the scope,
with `none_of_these` for none, and, of any other scope, one `noul`
question per label, named by the label with `_` for each character other
than a letter or digit. Each label's description, when it has one, goes
with it. The state is the issue's `title` and `body`. A label is set when
its probability (a choice's `confidence`, a noul's `noul`) is at least
`--threshold`. The record's `judged` gives the `model` the answer names,
or `--model`, and as its `reason` each question's answer and probability,
as `kind/bug 0.91; area/web 0.10`, or `kind: none 0.80`. An answer that is
not a success, or has no `answers` (at the top, or in `result` as Workers
AI gives them), is logged as `judging failed`.

A command reads one issue as JSON on standard input: `subject` (its
AT-URI), `author` (a DID), `title`, `body` when it has one, and `labels`,
the repository's definitions of the labels to choose among. It writes
`{"labels": [...], "model": "...", "reason": "..."}` on standard output;
`model` and `reason` may be left out, and are kept to 200 and 500
characters. A name not offered is passed over, and of a scope's exclusive
labels only the first offered is set. A classifier that exits non-zero,
answers something else, or a classifier of either kind that takes longer
than `--timeout`, is logged as `judging failed`,
and the issue is asked about again at the next read. Each issue judged is
logged as `judged`, with the labels set.

A usage error exits 2 and prints the usage, as `name its scopes and a
repository, or --discover` or `name one classifier, --decide or --classify`; an error at run time exits 1, as
`knotless-triage: <error>`, as `--discover finds repositories through an
appview, and KNOTLESS_APPVIEW is set empty`. With `--discover` it logs each
repository it finds as `found` and each it leaves as `left`; a listing or
the invites it could not read, as `finding repositories failed`. Watching, it stops at the start if a
repository cannot be opened; afterwards a repository that cannot be read
is logged as `reading the repository failed`, and it goes on. With
`--once`, any such error stops it.

It follows Jetstream as knotless-run does, reconnecting in 500 ms, doubling
up to 60 s, and giving a connection up once it stays silent 60 s past a
ping. It reads every repository on connecting; an issue written about
a watched repository, or a watched owner's repository record, has it read
the repositories again after `--settle`; with `--discover`, any repository
record written has it read that repository's, to find one that names it.

## knotless-agent

`knotless-agent review --command <command> [flags] [<handle>/<name>...]`
reviews the open pulls of the repositories named, and of every repository
an `--owner` holds, that ask its account for a review, acting as `KNOTLESS_IDENTIFIER` with `KNOTLESS_PASSWORD`, and
reads public repositories' pulls through `KNOTLESS_APPVIEW`. [Reviews by
Claude](../guide/reviews.md) sets one up, and [review
agents](../design/collaboration.md#review-agents) says why it works as it
does.

| Flag | Default | |
| --- | --- | --- |
| `--command <command>` | | the command run with `sh -c` once per review, as `knotless-claude-review` |
| `--all` | off | review every open pull that is not a draft, asked or not |
| `--rounds <n>` | 3 | the most reviews of one pull, one at each head it is pushed to |
| `--timeout <secs>` | 1200 | how long the command has for a pull before it is killed |
| `--jetstream <wss://host>` | `wss://jetstream2.us-east.bsky.network` | where events come from |
| `--sweep <secs>` | 300 | how often every repository is read, whatever events say |
| `--settle <secs>` | 5 | how long after an event the repositories are read, for the appview to index the pull |
| `--once` | off | read each repository once, and stop |
| `--owner <handle\|did>` | | also watch every public repository this account holds, listed from its PDS at each read, so one it makes later is watched too. Repeat it for more accounts. An owner whose listing fails is logged as `listing an owner's repositories failed`, and its last listing stands |

It reviews a pull that is open and not a draft, that its owner, a
collaborator or a member of the owner's organization opened, and whose
`reviewers` names its account (or any, with `--all`), once at each head
commit, up to `--rounds` times. It never reviews its own. A head whose
changes against the base are those of the head it last reviewed, as after
a merge of the base into the branch, is not read again: its last verdict
is written at the new head, beginning `Carried forward:`, and counts as no
round.

The command reads one pull as JSON on standard input: `repo`
(`knotless://<owner>/<name>`), `pull` (its AT-URI), `title`, `body`,
`author` (a handle, or a DID where none resolves), `base` (the branch it
merges into), `head` (`repo`, `branch` and the `commit` it is at), `round`
(from 1), `rounds`, `earlier`, its own earlier reviews of the pull,
each `verdict`, `body` and `commit`, and `instructions`, what
`.knotless/review.md` says on the pull's base branch, when it is there. It writes `{"verdict": "approve" |
"changes", "body": "...", "lines": [...]}` on standard output, each of
`lines` `{"line": {"path", "line", "startLine", "side"}, "body"}` as
`comment --line` takes them (at most 100); `lines` may be left out. Its
standard error goes to the agent's. A command that exits non-zero,
answers something else, or takes longer than `--timeout`, is logged as
`reviewing failed`, and the pull is read again at the next read. A review
written is logged as `reviewed`, with its verdict. One whose head moves as
the command reads it is read again at the new head, and nothing is
written of the first answer.

`knotless-claude-review` (`crates/knotless-agent/claude-review`, in the
server image at `/usr/local/bin`) is such a command: Claude Code, headless,
reading the pull through `knotless-mcp --read-only`, logged in as the
agent, and following `instructions` and `KNOTLESS_REVIEW_PROMPT` besides
its own rules. It takes `CLAUDE_CODE_OAUTH_TOKEN` (from `claude
setup-token`) or `ANTHROPIC_API_KEY`, `KNOTLESS_REVIEW_MODEL` for
Claude's `--model`,
`KNOTLESS_MCP` for the `knotless-mcp` to run and `CLAUDE` for the `claude`.

A usage error exits 2 and prints the usage, as `name its command and a
repository, or --owner`; an error at run time exits 1, as `knotless-agent: <error>`.
Watching, it stops at the start if a repository cannot be opened;
afterwards one that cannot be read is logged as `reading the repository
failed`, and it goes on. With `--once`, any such error stops it.

It follows Jetstream as knotless-triage does. It reads every repository
on connecting; a pull written about a watched repository or any of an
owner's, a repository record an owner writes, or a ref pushed by an
account whose pull asks it, has it read the repositories again after
`--settle`.

## Environment

### Identity and login

| Variable | Default | |
| --- | --- | --- |
| `KNOTLESS_IDENTIFIER` | the last login | the account to act as |
| `KNOTLESS_PASSWORD` | | an app password, instead of OAuth: `KNOTLESS_IDENTIFIER`'s, used only to log in as that account, and only when it has no stored session that still refreshes |
| `KNOTLESS_BROWSER` | the system's | the command an OAuth login opens its page with |
| `KNOTLESS_SERVICE` | | the PDS every identity is served by, skipping DID resolution |
| `KNOTLESS_PLC_URL` | `https://plc.directory` | the PLC directory |
| `KNOTLESS_HANDLE_RESOLVER` | `well-known:https,https://public.api.bsky.app` | where handles are resolved, in order: `well-known:<scheme>` for `/.well-known/atproto-did`, or a service URL for XRPC |
| `KNOTLESS_DID_WEB_SCHEME` | `https` | the scheme `did:web` resolves over |
| `KNOTLESS_IDENTITY_TTL_SECS` | 3600 | how long a resolved identity is cached |
| `KNOTLESS_CA_CERTS` | | a PEM bundle of extra CAs to trust, such as a local network's own |

### Servers

| Variable | Default | |
| --- | --- | --- |
| `KNOTLESS_APPVIEW` | `https://knotless.dev` | the `knotless-serve` index that lists pulls and issues on public repositories; set empty, there is none. `knotless-serve`'s `/mcp` reads its own index before the default |
| `KNOTLESS_MODERATOR` | the appview's | the DID of the moderation service reports go to, by its `#atproto_labeler` service |
| `KNOTLESS_ADMIN_DIDS` | | on `knotless-serve`, the accounts that operate it, comma-separated: the admin methods take their service tokens, for the `admin` commands |
| `KNOTLESS_BOT_DIDS` | | on `knotless-serve` with `--bots`, the accounts that may log in at `/oauth/bot`, comma-separated |
| `RUST_LOG` | `info` | what `knotless-serve` and `knotless-run` log, as JSON lines on stderr: `debug`, or `info,knotless::outgoing=debug` for each call made, `knotless::git=debug` for each git command |
| `KNOTLESS_SLOW_MS` | 1000 | on `knotless-serve` and `knotless-run`, how slow a request served or made, or a git command, is before it is logged at warn, and on `knotless-serve` a tenth of it, an index's SQL statement; on `knotless-run`, a pass taking this long logs `pass ended` at info rather than debug |

### Storage

| Variable | Default | |
| --- | --- | --- |
| `KNOTLESS_INLINE_MAX` | 192 KiB | the largest pack kept inline in its record |
| `KNOTLESS_CHUNK_SIZE` | 4 MB, or the PDS's blob limit if smaller | the size of a large pack's, or a release file's, blob parts |
| `KNOTLESS_COMPACT` | `background` | when to compact: `background` (a detached `knotless compact`), `inline` (before the push returns) or `off` |
| `KNOTLESS_COMPACT_THRESHOLD` | 32 | the packs, counting the push's own, at which the owner's `git push` starts a compaction |
| `KNOTLESS_COMPACT_GRACE_SECS` | 600 | how old a pack must be to be compacted away |
| `KNOTLESS_CLAIM_GRACE_SECS` | 86400 | how old a claim must be to be dropped |

### Client

| Variable | Default | |
| --- | --- | --- |
| `KNOTLESS_TIMEOUT_SECS` | 60 | a request's timeout; connecting times out after 10 s, and an idle connection is dropped after 4 s. A handle's `/.well-known/atproto-did` and a `did:web` document get 3 s, as atproto's resolvers do |
| `KNOTLESS_POLL_MS` | 10000 | how often `--wait`, on `checks` and `merge`, reads checks again |
| `KNOTLESS_CONFIG_DIR` | `$XDG_CONFIG_HOME/knotless`, or `~/.config/knotless` | where sessions are kept |
| `KNOTLESS_CACHE_DIR` | `$XDG_CACHE_HOME/knotless`, or `~/.cache/knotless` | where mirrors and caches are kept |
| `KNOTLESS_NO_UPDATE_CHECK` | | set, the appview is not asked for its newest release or the oldest version it asks for |
| `KNOTLESS_IGNORE_MINIMUM` | | set, run although older than the appview asks for |
| `KNOTLESS_INSTALL_DIR` | the directory the binary is in | where `knotless upgrade` installs |

A number that does not parse is its default. Every process shares one
HTTP client, so requests reuse connections.

The config directory holds `sessions/<did>.json` (mode 0600), `me` (the
last account logged in), `credentials/` (space credentials) and, on a
gateway, `oauth-client-key`. The cache directory holds:

| File | |
| --- | --- |
| `identity.json` | handle or DID to DID and PDS, for `KNOTLESS_IDENTITY_TTL_SECS` |
| `handles.json` | DID to verified handle, as long |
| `servers.json` | each PDS's blob limit, as long |
| `keys.json` | each repository's key, and whether it was found public or in a space; never expires |
| `emails.json` | the accounts whose first-push email claim was already looked up here |
| `update.json` | the appview's newest release and the oldest version it asks for, and when it was asked, for a day |
| `mirrors/` | the bare mirrors and their lock files |
| `tmp/` | scratch repositories and indexes, removed when done |

Each JSON file is written whole and renamed into place. A missing or
unreadable one reads as empty.

### Install script

| Variable | Default | |
| --- | --- | --- |
| `KNOTLESS_INSTALL_DIR` | `$HOME/.local/bin` | where the binaries go |
| `KNOTLESS_VERSION` | the latest | which release |