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 create, issue create, pull list, issue list and pull 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. One the login asked for, but its PDS did not grant, adds knotless: your login asks for this, but your PDS did not grant it instead, and for a write in a space goes on to say why: a PDS grants writes in a space as the lexicon knotless publishes for its type listed them when you logged in, so once that lists the collection, knotless login again grants it. 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.

Every command is knotless <group> <action> [<url>] [arguments], and the groups are singular nouns: account, repo, branch, tag, pull, issue, comment, label, triager, queue, run, workflow, runner, agent, secret, release, mod, admin, org, theme and notification. Only login, logout, upgrade and status stand alone. An action that has an opposite takes --undo (repo star --undo), never a command of its own. knotless-mcp offers each command as the tool <group>_<action> (repo_star, pull_merge), with the same arguments: MCP tools lists them by group. A command with no tool acts on this machine: login, logout, upgrade, repo mirror, workflow pin and release download.

The names the commands had before groups (knotless pull, knotless merge, knotless checks, and the rest) still work for one release, but usage does not list them. The old names say what each became.

Session and setup

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
status [<server>] [--repo <handle>/<name>] [--json]	a knotless-serve's health, from /_status: its feeds, index, a mirror, its disk's room and its code search index; the server defaults to KNOTLESS_APPVIEW

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.

account

Command
account delete-data <handle> [--yes]	delete every knotless record from your account (storage.md): 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
account delegate <handle> <gateway did>	let a gateway write for you, so collaborators can push through it
account 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
account 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
account email add <address> / account 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
account follow <handle> [--undo]	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. With --undo, take your follows of it back, printing unfollowed, followed or not
account follows [<handle>]	the accounts you, or <handle>, follow, newest first: handle and when, tab-separated
account 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
account search <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

repo

Command
repo 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
repo list <handle>	list an account's repositories
repo 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
repo edit <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 --links given replace those it had, as account profile's do, and --link '' drops them), its topics (the --topics 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
repo rename <url> <new name>	rename; the old name redirects; <new url> already exists if another repository has the name
repo 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)
repo 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
repo transfer <url> <handle or url> / repo transfer <url> --undo	offer a public repository to another account, or with --undo withdraw the offer
repo accept <url>	take a repository offered to you, its pulls and issues included
repo share <url> <handle> [--write] [--undo]	let an account read a private repository, or push too, printing shared, and leave it an invite at the appview (KNOTLESS_APPVIEW), by which an agent watching your repositories (knotless-agent --owner) finds it; with --write before you have delegated your writes to a gateway, delegates them to the appview's first, as account delegate does, approved in the browser, printing delegated to <did> before it. With --undo, take access away
repo 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
repo star <url> [--undo]	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. With --undo, take your star back, printing unstarred, starred or not
repo stars [<handle>]	the repositories you, or <handle>, starred, newest first: knotless://<handle>/<name> and when, tab-separated
repo compact <url> [--due]	as the owner, fold its packs into one, printing <n> packs, <n> folded, <n> old claims dropped, <n> deleted refs' records dropped: the last, the records clients before deletes removed them left of deleted refs, once a day old. With --due, as the owner's git push runs it, only once it holds KNOTLESS_COMPACT_THRESHOLD packs; under that, it counts them and folds nothing
repo 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}
repo mirror <url>	sync the cache mirror and print its path
repo refs <url>	print the refs, in one round trip
repo tree <url> [<path>] [--rev <rev>] [--json]	a directory's entries at the default branch or <rev>, from the cache mirror with no clone: a line each of the mode, blob or tree, the object's SHA, its size (- for a tree) and its name, tab-separated
repo read <url> <path> [--rev <rev>]	a file's bytes at the default branch or <rev>, from the cache mirror with no clone, printed as they are
repo log <url> [--rev <rev>] [--path <path>] [--limit <n>] [--json]	the commits reachable from the default branch or <rev>, newest first, optionally only those touching <path>, at most <n> (20 by default), from the cache mirror with no clone: a line each of the commit's first characters, when it was written, its author's name and its subject, tab-separated
repo 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
repo 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
repo diff <url> <base> <head>	what <head> changed since it forked from <base>, as git diff base...head shows it, with no clone
repo commit <url> -b <branch> -m <message> [options]	commit without a checkout (below)
repo site <url> [<dir>] [--fallback <path>] [--not-found <path>] [--commit <sha>] [--check <at-uri>] [--down]	as owner, deploy <dir> as the repository's website: its files, uploaded as blobs but for those the live site holds already, then its dev.knotless.site record, replaced (see pages). Prints uploaded <n> of <m> files, then the address it is served at, https://<owner>.knotless.page/<repo>/. --fallback names the page a single-page app answers every other page with, --not-found the one a missing path gets, with 404; each must be one of the files. --commit is KNOTLESS_RUN_SHA unless given. With no <dir>, the live site: its address, files, commit and when it was deployed, tab-separated, or <url> has no site. --down takes it down, printing taken down. A site holds 1 to 2,000 files, each path at most 512 bytes, and no links. A private repository's site is kept in its space and served to its members at https://<repo key>-<plc id>.private.knotless.page/; an owner with no did:plc fails a private site's owner is named by a did:plc

repo 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 whom git commits as here (user.name, user.email), or, where git has none, 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.

branch

Command
branch create <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 delete <url> <name>	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 rename <url> <name> <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
branch protect <url> <branch> [--merges] [--queue] [--reviews <n>] [--code-owners] [--dismiss-stale] [--gate <handle>...]	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); 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, and with --gate <handle>, given once for each, it waits for that account's review of its head, its request for changes blocking it, though it may not write (see gates) (see required reviews). It replaces any rule the branch had
branch protect <url> <branch> --undo	drop a branch's rule
branch 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, dismiss stale and gate <did> for each gate as it asks for reviews, tab-separated; branch protect prints the same

tag

Command
tag create <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 delete <url> <name>	delete a tag, printing deleted <name>; <url> has no tag <name> if there is none

pull

A pull's <at-uri> is the one pull create and pull list print.

Command
pull create <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); --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). Asking yourself fails
pull list <url> [-q <query>]	pulls, newest first; -q filters them in GitHub's search words (collaboration.md)
pull 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
pull diff <url> <at-uri>	the unified diff a pull would apply: its head, in whichever repository it is, against where it left its base
pull template <url> [<base>]	what the repository asks a pull's title and body to follow, into the default branch or <base> (templates)
pull 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
pull close <url> <at-uri> / pull reopen <url> <at-uri>	change an item's state, as its author, the owner or a collaborator; refuses an item that is not there, a merged pull and a state it is in already
pull label <url> <at-uri> <label>... [--undo]	as owner, collaborator or a triager of their scope, put labels on a pull or take them off with --undo; prints those it carries now
pull assign <url> <at-uri> <handle>... [--undo]	as owner or collaborator, assign a pull to accounts, or with --undo take them off it; prints those it is assigned to now (collaboration.md)
pull 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
pull ask-review <url> <at-uri> <handle>... [--undo]	ask accounts to review a pull, or with --undo stop asking them: as its author, in the pull, as pull edit --reviewer does, or as owner or collaborator, in your own record. Each stops asking only those it asked, and is told who asked when it did not. A required reviewer, a gate of the rule protecting the pull's base, is asked of every pull and stays asked until the rule stops naming it, so unasking one fails. Prints those asked now
pull dismiss-review <url> <at-uri> <handle or review at-uri> [<reason> | -m <reason>]	as owner or collaborator, dismiss that reviewer's standing review of a pull, named by handle or by the review's at:// URI, saying why (- reads the reason from stdin; -m <reason> may stand for it): a comment naming it, so it counts for nothing, for or against, until they review again. Prints the comment's URI; pull show then marks the review , dismissed
pull retarget <url> <at-uri> [--base <branch>] [--head <branch>]	point a pull at other branches; the head only by the pull's author
pull 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). Into a branch protected with --queue, it queues the pull instead, unless forced
pull merge <url> <at-uri> --queue	put a pull in its branch's merge queue, and return, printing queued into <base>: <n> of <of>; refused unless the branch it lands on is protected with --queue; takes no --keep-branch, --wait or --force
pull merge <url> <at-uri> --auto [--undo]	set a pull to merge by itself once its checks pass, on a branch with no merge queue, printing set to merge when its checks pass, at <head>: the runner that lands the repository's queues merges it then, keeping its branch. A push by anyone who may not merge it, or retargeting it, cancels it; --undo cancels it, as the pull's author may too. Takes none of --queue, --check, --keep-branch, --wait and --force (see merge when checks pass)
pull 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
pull 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
pull update-branch <url> <at-uri>	as owner or collaborator, merge an open pull's base into its branch, in the repository itself, and push it; where both sides only added lines at the same place, the base's come first. Prints merged its base into <branch>: <commit>, then both sides only added lines in <path>: the base's come first for each such file, or <branch> holds its base already. Refused on any other conflict, naming its paths. See updating a pull's branch

issue

Command
issue create <url> <title> [-m <body>] [--image <file>]...	open an issue
issue list <url> [-q <query>]	issues, newest first; -q filters them in GitHub's search words
issue template <url>	what the repository asks an issue's title and body to follow
issue show, issue edit, issue close, issue reopen, issue label, issue assign, issue react	as pull show, pull edit, pull close, pull reopen, pull label, pull assign and pull react are, for an issue; the arguments are the same, less the pull's --draft, --ready, --reviewer and --no-reviewer, which fail <at-uri> is not a pull

comment

Command
comment add <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
comment edit <url> <comment-uri> [-m <body> [--image <file>]...]	change your comment; -m - reads the body from stdin; the pictures it keeps are those the new body shows
comment delete <url> <at-uri>	take back your comment or review
comment react <url> <comment-uri> <content> [--undo]	react to a comment, as pull react does to a pull
comment resolve <url> <comment-uri> [--undo]	resolve the thread a comment on a pull's lines starts, or with --undo open it again: its author, the pull's, the owner or a collaborator

label

Command
label list <url>	the labels a repository defines: name, color, exclusive and description, tab-separated
label define <url> <name> [--color <#hex>] [--description <text>] [--exclusive]	as owner, define a label (or redefine it) on the repository
label delete <url> <name>	as owner, take a label away, off everything it is on

triager

Command
triager list <url>	the accounts, such as a triage bot, whose labels of their scopes count, below the owner's and collaborators', each as its DID and scopes, tab-separated
triager add <url> <handle> <scope>...	as owner, name an account a triager of those scopes. 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
triager remove <url> <handle>	as owner, stop naming one
triager eval <url> <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

queue

Command
queue list <url> [--json]	the merge queues in order, and what was ejected
queue leave <url> <at-uri>	take a pull out of the merge queue

pull merge --queue puts a pull in the queue.

notification

Command
notification list [--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
notification 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
notification watch <url> [all | releases | ignore | participating]	what you hear of a repository, kept by the appview: all it does (pulls and issues opened, comments, releases; the default), its releases alone, nothing (ignore, but a review asked of you), or, participating, only what you take part in. Your own repositories are watched at all until you choose. Prints the level, a tab and the repository's record
notification subscribe <at-uri>, notification mute <at-uri>, notification unsubscribe <at-uri>	hear of every comment on a pull or issue (subscribed), nothing of it but a review asked of you (muted), or, with unsubscribe, as your part in it says again (participating). Prints the level, a tab and the URI
notification subscriptions	every choice watch, subscribe and mute made, the latest first: level, subject and when, tab-separated

theme

Command
theme list [<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

run

Command
run list <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
run rerun <url> --ref <name> | --pull <at-uri> [--workflow <name>]	as owner, ask the runners to run it again, or only one of its workflows
run rerun <url> --ref <name> --workflow <name> [-e <name>=<value>]...	as owner, ask for one workflow there, with variables its steps see
run cancel <url> --ref <name> | --pull <at-uri> [--workflow <name>]	as owner, ask the runners to cancel its runs going or waiting, or only one workflow's

run list 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 -. The newest run keeps that name; an older run's picture of the same name is <workflow> <alt> <commit>.<ext>, the commit's first 12 characters, and one older still at that commit is not saved, so none is written over. --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 run_list 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.

run 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.

run cancel writes a dev.knotless.cancel record in the owner's account and prints its AT-URI. It takes the ref as run rerun does, and the same refusals: one ref or one pull (name one ref or one pull whose runs to cancel), a workflow's name, and a repository naming no runners. A runner cancels the runs going or waiting when it reads the request, a deploy's too, and files their checks as cancelled, logged cancelled as the repository's owner asked. Runs started after it go as ever. A merge queue's batches are not a ref's runs: queue leave takes a pull out.

workflow

Command
workflow list <url> [<ref>]	the workflows at a branch or tag (the default branch), and what runs each there
workflow pin [-C <dir>] [<uses>...]	pin the shared steps the checkout's workflows use, and those they use, in .knotless/uses.lock (see shared steps): each to the highest release its @ takes; with <uses> named, only those, the rest as the lock had them

workflow list 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 (run rerun --ref --workflow may ask for it: it runs on a push there, its asked trigger names the ref, or it has a schedule and the ref is the default branch), then, for one that does not load, why. At the default branch, each of its schedules follows on a line of its own, indented, as schedule <cron>. A ref it lacks is refused (<url> has no ref <name>).

A shared step is released as the package @step/<step> with release publish, its one file the step file and --commit the commit it is at. workflow pin 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.

runner

Command
runner list <url>	the accounts whose checks of the repository readers show
runner add <url> <handle>	as owner, name an account a runner; for a private repository it is made a member and invited as repo create does (added, then warning: … if it could not be). 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>
runner remove <url> <handle>	as owner, stop naming one, printing removed; a private repository's keeps it a member (repo share --undo takes it back). Deletes the secrets sealed to it
runner 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)

agent

Command
agent list <url>	the accounts, such as a coding agent, whose pulls the runners check as they move, as code no one vouches for (see the runner), each as its DID
agent add <url> <handle> / agent remove <url> <handle>	as owner, name one or stop naming it, printing added or removed

secret

Command
secret set <url> <name> [--ref <pattern>]... [--runner <handle>]...	as owner, or logged in as an admin who joined the organization that owns it, 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
secret list <url>	as owner or such an admin, each secret given, one line per runner, <name>\t<runner>\t<refs, or *>\t<updated>, never a value
secret remove <url> <name>	as owner or such an admin, take a secret back from every runner, printing removed <name>

release

Command
release 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). Prints the record's AT-URI. --notes - reads the notes from stdin
release list <url> [<package>]	the versions published, by package and then highest version first
release yank <url> <package> <version> [--undo]	as owner, withdraw a version: its files can still be read, but it is no longer the latest (yanking). Asking for what is so already changes nothing. Prints the release's AT-URI
release read <url> <package> <version> <file>	one file of a version (latest for the latest), checked against its size and SHA-256, printed as it is
release 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 (.)

release 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): 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.

release list prints a line per version: the package, the version, createdAt, the commit's first 12 characters (or -) and the files' names, comma-separated, then yanked if it is, tab-separated.

release download takes the package's latest, its highest version without a pre-release part that is not yanked, 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>.

mod

Command
mod hide <url> <at-uri> [--undo]	as owner, hide a pull, issue or comment, or with --undo show it again
mod block <handle> [<url>] [--undo]	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
mod 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
mod 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

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.

admin

Command
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

org

Command
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, and change its repositories' settings from their own login (repo edit, repo archive, repo compact, branch protect, label define, label delete, triager add, triager remove, agent add, agent remove, repo share, runner add, runner remove, secret set, secret remove): not logged in as a repository's owner, these ask the appview (KNOTLESS_APPVIEW), which writes them as the organization through its gateway, and refuses anyone not its admin. Renaming, deleting or transferring one takes the organization's own login. 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 account 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

What the pull, issue and queue commands print

Command	Output
pull create, issue create	the new record's at:// URI
comment add	the at:// URI of each comment it wrote, a line each: the review first, then its comments on lines
comment resolve	resolved, or unresolved with --undo
pull list, issue list	a line per item: <kind>, <state>, <uri>, <title>, tab-separated
pull show, issue show	<state> <kind> by <author>: <title>, then draft for a draft pull, review requested: <handles> for one that asks for reviews, its base's required reviewers among them, 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 run list that reads their logs, then for an open pull ever set to merge when its checks pass merge when checks pass: set by <handle>, or cancelled, as <handle> pushed after <handle> set it, or cancelled, as the pull moved off <branch>, 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>
pull 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
pull merge --queue	queued into <base>: <n> of <of>; queued again at the head the queue last ejected, a line saying so and why; then where to follow it, and to read an ejection's logs before queueing again
pull merge --auto	set to merge when its checks pass, at <head> (12 characters), then what happens next; with --undo, cancelled: it merges only when someone merges it
pull 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, a review of its head from @bot; 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 pull merge would refuse with, and that the caller may not merge it when it may not
queue list	a line per pull: <position>, <base>, <state>, <uri>, <title>, tab-separated, where the state is queued, pre-flight <workflows> while the pre-flights it waits for run, comma-separated, failed <workflows> once the newest run of one failed and none runs, as the runner has yet to eject it or run it again, or <checking or landing> at <commit>; an ejected pull has - and ejected, and a line after it with the reason; one waiting for the pull below it has - and stacked; the merge queue is empty if it is
queue list --json	each pull waiting, with its place and batch, or the preflight workflows it waits for
queue leave	left the merge queue
pull edit, comment delete, pull close, pull reopen, pull retarget	edited, deleted, closed, open, retargeted

pull merge --queue refuses --keep-branch, --wait and --force (--queue takes none of --keep-branch, --wait and --force), and pull 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 (pull merge and pull 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 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 pull retarget changes them (those who may close it, and its author), and rerun (the owner, with runners). queue list takes one flag, --json. pull 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.

The merge gate

In a repository naming runners, pull 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). 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), then Wait for them with `--wait <secs>`
• <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, then The owner asks for them with `knotless run rerun <url> --pull <pull>`; wait for them with `--wait <secs>`

Each ends read their logs with `knotless run list <url> --pull <pull> --log`; the owner, its author or not, merges past it with `--force` . --force from anyone else is refused: only the owner of <url> merges a pull past its checks. Over MCP, pull_merge takes wait (at most 300 s) and force, and its refusals name tools rather than commands: the run_list tool, pull and log, the pull_merge tool and force.

A refusal says what to do last, after a full stop, in the words of whoever reads it: here as a command to run, over MCP as a tool to call, and on the pages, or getMergeStatus and any write of theirs refused, as the control there that does it, leaving out what only the command line can (--force, --wait, reading logs, beside the failed checks the pages already link). A runner's reason for ejecting a pull from the merge queue says only what stands in its way, as every client reads it.

The old names

Before commands were grouped, each stood alone. Those names still work, hidden from the usage, for one release. Each became:

Before	Now
delete-data, delegate, profile, email	account delete-data, account delegate, account profile, account email
follow, unfollow, follows, followers, owners	account follow, account follow --undo, account follows, account followers, account search
create, ls, fork, describe, rename, archive, delete	repo create, repo list, repo fork, repo edit, repo rename, repo archive, repo delete
transfer, transfer --cancel, accept	repo transfer, repo transfer --undo, repo accept
share, unshare, members	repo share, repo share --undo, repo members
star, unstar, stars	repo star, repo star --undo, repo stars
compact, storage, mirror, refs, search, blame, commit, site	repo compact, repo storage, repo mirror, repo refs, repo search, repo blame, repo commit, repo site
diff <url> <base> <head>, diff <url> <at-uri>	repo diff, pull diff
branch <url> <name>, --delete, --rename	branch create, branch delete, branch rename
protect, unprotect, rules	branch protect, branch protect --undo, branch rules
tag, tag --delete	tag create, tag delete
pull, issue	pull create, issue create
list --pulls, list --issues	pull list, issue list (list with neither is gone)
show, edit, close, reopen, label, unlabel, assign, unassign, react	pull or issue with the same action, --undo for the un- ones; comment edit and comment react for a comment
template <url> pull, template <url> issue	pull template, issue template
ask-review, unask-review, retarget, revert, update-branch, dismiss	pull ask-review, pull ask-review --undo, pull retarget, pull revert, pull update-branch, pull dismiss-review
merge	pull merge
comment, delete-comment, resolve, unresolve	comment add, comment delete, comment resolve, comment resolve --undo
labels, labels add, labels remove	label list, label define, label delete
triagers	triager list, triager add, triager remove, triager eval
queue, queue --leave	queue list, queue leave
checks, rerun, workflows, uses update	run list, run rerun, workflow list, workflow pin
minutes, runners, agents, secret ls, secret rm	runner minutes, runner list, agent list, secret list, secret remove
publish, releases, download	release publish, release list, release download
hide, unhide, block, unblock, blocks, report	mod hide, mod hide --undo, mod block, mod block --undo, mod blocks, mod report
themes, notifications	theme list, notification list

login, logout, upgrade, status, admin, org and theme (but for themes) are as they were.

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
--directory <https://host>		ask this collection directory (com.atproto.sync.listReposByCollection, as lightrail answers it) which accounts hold knotless records before the relay or PDS a backfill is from; repeatable, asked in turn; empty, none
--mirror <https://host>		read each account's repository from this mirror (com.atproto.sync.getRepo, as hubble answers it, STAR-lite or a CAR) before the account's PDS; empty, none
--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
--ios-minimum-build <build>		the oldest build of the iOS app this appview lets run, as dev.knotless.describeServer answers: older builds show only a way to update. Anything not a number is refused; empty, none
--ios-minimum-reason <text>		why, which those builds show
--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)
--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)
--pages-domain <domain>		answer repositories' sites on this domain, each owner at a label of it, as knotless.page: a request whose host is the domain or a name under it is answered as a site and nothing else; needs --public-url, where an owner's root redirects (Pages)
--apns-key <file>		send the iOS app's notifications through Apple's push service, signing with this .p8 key; takes --apns-key-id and --apns-team, and an index (Push notifications)
--apns-key-id <id>		the id Apple gave that key
--apns-team <id>		the Apple team the key is of
--code-index <dir>		search the code of public repositories, keeping Zoekt's shards in this directory; zoekt-webserver and zoekt-git-index must be on PATH (Code search)

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 and --apns-key take --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, knotless-mcp, knotless-run, knotless-triage, knotless-agent and knotless-claude-review for aarch64 or x86_64, macOS or Linux (musl), with curl or wget. A release from before the last four shipped installs the first three. 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.

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 repo create --private and knotless runner list <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)
--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 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)
--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)
--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
--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)
--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)
--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 where its account may push, or where they name it and no runner that may (Who lands a queue); takes docker
--batch <n>	8	with --queue, the most pulls in a batch, 64 at most (a check record's batch holds no more)
--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
--review-wait <secs>	1800	with --queue, how long a queued pull waits for a review of its head from its branch's gates before it is ejected

<cache dir> is KNOTLESS_CACHE_DIR's. --jobs, --pull-jobs, --owner-jobs, --allowance, --private-allowance, --sweep, --batch, --notice, --review-wait, --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. --batch above 64 is refused with --batch is 64 pulls at most. --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). 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.

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 sets one up, and 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 times it asks for changes on one pull; it stops reviewing the pull after that. Approvals do not count
--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 repository this account holds that the agent reads: the public ones, listed from its PDS at each read, so one it makes later is watched too, and the private ones it shared with the agent's account, from the invites repo share leaves it at the appview (an invite it can no longer read by, as once unshared, is passed by; without a gateway's DID at the appview to ask with, it logs listing the invites left it failed and watches the public ones). 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), as it does of every pull into a branch whose rule names it a gate, once at each head commit, until it has asked for changes --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. A request for changes is not carried so when the pull's title or body changed after it: the new head is read.

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, changes (how many times it has asked for changes on the pull), approved (the head its last review approved, or null), 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 add --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.

knotless-agent keep [flags] [<handle>/<name>...] keeps the pulls the merge queue turned away moving, for the same repositories, with the same --jetstream, --sweep, --settle, --once and --owner flags, and --attempts <n> (3), the most times it brings one pull up to date. It takes no command. Its account must be the owner or a collaborator, as it pushes to the pull's branch and queues it. See keeping turned-away pulls moving.

It reads a pull that is open and not a draft, that the owner or a collaborator opened from a branch of the repository itself, that the queue turned away at the head its branch is at now, and whose body has no line Keeper: off. When it conflicts with its base, the keeper merges the base in as knotless pull update-branch does, comments, beginning Merged and naming the new head, and queues it again; one it finds still turned away at the head it gave it, as when queueing failed, it queues with nothing more said. Where both sides changed the same lines it pushes nothing, and comments once at that head, naming the paths. A pull turned away for another reason, pushed to since, or brought up to date --attempts times, it leaves alone. Each pull it updates, queues or comments on is logged as kept, with updated, queued or conflicted; one it fails on, as keeping failed.

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 or a queue record 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: an OAuth one whose refresh fails other than by its server turning it down (invalid_grant) is kept and tried again, the failure logged as login refresh failed, rather than replaced by the password's, which reads no private repository
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, at most 256 KiB (262144 bytes), the lexicon's limit
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	how the owner's git push compacts: background (a detached knotless repo compact --due), inline (before the push returns) or off
KNOTLESS_COMPACT_THRESHOLD	32	the packs, counting the push's own, at which the compaction the owner's git push starts folds them
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 run list and pull 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