johnandersen777.bsky.social/knotless

Switch repository

Loading…

# Actions

Everything someone can do with knotless, and where: the `knotless`
[command](cli.md), the [MCP tool](mcp.md), the XRPC method
[knotless-serve](api.md) answers for it, and the web page. The three
surfaces call the same code in the `knotless` crate, so an action does the
same wherever it is done. A command `knotless <group> <action>` and its
tool `<group>_<action>` are twins, so the tool column repeats the command
in snake case and shows only where the two differ in what they take. "–"
marks where one is missing.

The XRPC column names the method the pages ask. The command line and the
tools write most things straight into your own account on your PDS, as
records, and need no method of knotless-serve's for it: a write has one
only once a page makes it. `<repo>` is a repository's page,
`/<owner>/<name>`.

## Reading

| Action | CLI | MCP | XRPC | Web |
| --- | --- | --- | --- | --- |
| an account's repositories | `repo list` | `repo_list` | `getActorRepos`, `listRepos` | profile, Repositories tab; `<repo>` repository switcher |
| an account's profile and activity | – | – | `getProfile`, `getActorActivity`, `getFeed` | profile, Overview and Activity tabs |
| what the network did | – | – | `getFeed` | home |
| find accounts by handle | `account search` | `account_search` | `searchOwners` | `/search` |
| a repository's summary, branches and tags | `repo refs` | `repo_refs` | `getRepo`, `listBranches` | `<repo>`, its branch menu |
| a directory | `repo tree` | `repo_tree` | `getTree`, `getLastCommits` | `<repo>/tree/…` |
| a file | `repo read` | `repo_read` | `getFile` | `<repo>/blob/…`, `/raw/…` |
| search a repository's files | `repo search` | `repo_search` | – | – |
| history | `repo log` | `repo_log` | `listCommits` | `<repo>/commits/…` |
| a commit | `repo log`, `repo diff` | `repo_log`, `repo_diff` | `getCommit` | `<repo>/commit/<rev>` |
| who last changed each line | `repo blame` | `repo_blame` | – | – |
| what one revision changed since another | `repo diff <base> <head>` | `repo_diff` | – | – |
| pulls | `pull list` | `pull_list` | `listItems` | `<repo>/pulls` |
| issues | `issue list` | `issue_list` | `listItems` | `<repo>/issues` |
| a pull and its comments | `pull show` | `pull_show` | `getThread` | `<repo>/pull/…` |
| an issue and its comments | `issue show` | `issue_show` | `getThread` | `<repo>/issue/…` |
| the diff a pull would apply | `pull diff` | `pull_diff` | `getThread` | the pull's page |
| the template a pull or issue follows | `pull template`, `issue template` | `pull_template`, `issue_template` | `getTemplate` | the new pull and new issue pages |
| checks, their logs and pictures | `run list` | `run_list` | `listRuns`, `getCheck`, `getCheckImage`, `listChecks` | `<repo>/checks`, `<repo>/check/…` |
| the workflows at a ref | `workflow list` | `workflow_list` | – | – |
| the merge queue | `queue list` | `queue_list` | `getQueue` | `<repo>/queue` |
| runner minutes | `runner minutes` | `runner_minutes` | `listRunners` | `<repo>/settings/actions` |
| what a repository takes up on its PDS | `repo storage` | `repo_storage` | – | – |
| members | `repo members` | `repo_members` | – | – |
| protected branches | `branch rules` | `branch_rules` | – | – |
| labels | `label list` | `label_list` | – | – |
| triagers | `triager list` | `triager_list` | – | – |
| runners and agents | `runner list`, `agent list` | `runner_list`, `agent_list` | – | – |
| secrets, by name | `secret list` | `secret_list` | – | – |
| releases | `release list` | `release_list` | – | – |
| a file of a release | `release read` | `release_read` | – | – |
| an account's stars | `repo stars` | `repo_stars` | `getActorStars` | profile, Stars tab |
| follows and followers | `account follows`, `account followers` | `account_follows`, `account_followers` | `getFollows`, `getFollowers` | profile, Following and Followers tabs |
| notifications | `notification list` | `notification_list` | `listNotifications`, `getUnreadCount`, `updateSeen` | `/notifications` |

## Pulls and issues

"Its page" is the pull's or issue's, `<repo>/pull/…` or `<repo>/issue/…`.
Each action on an item exists under `pull` and `issue` as the item is,
and a comment's under `comment`.

| Action | CLI | MCP | XRPC | Web |
| --- | --- | --- | --- | --- |
| open an issue | `issue create` | `issue_create` | `createIssue` | `<repo>/issues/new` |
| open a pull | `pull create` | `pull_create` | `createPull`, `getCompare` | `<repo>/pulls/new` |
| comment | `comment add` | `comment_add` | `createComment` | its page |
| review: approve or ask for changes | `comment add --approve`, `--changes` | `comment_add` with `verdict` | `createComment` with `verdict` | the pull's page |
| edit a title, body or comment | `pull edit`, `issue edit`, `comment edit` | `pull_edit`, `issue_edit`, `comment_edit` | `editItem` | its page |
| take back a comment or review | `comment delete` | `comment_delete` | `deleteComment` | its page |
| close or reopen | `pull close`, `pull reopen`, `issue close`, `issue reopen` | `pull_close`, `pull_reopen`, `issue_close`, `issue_reopen` | `setItemState` | its page |
| resolve a thread, or open it again | `comment resolve [--undo]` | `comment_resolve` | – | the pull's page |
| put labels on or off | `pull label [--undo]`, `issue label [--undo]` | `pull_label`, `issue_label` | `labelItem` | its page |
| assign | `pull assign [--undo]`, `issue assign [--undo]` | `pull_assign`, `issue_assign` | `assignItem` | its page |
| ask for a review, or stop | `pull ask-review [--undo]` | `pull_ask_review` | `assignItem` | its page |
| dismiss a review | `pull dismiss-review` | `pull_dismiss_review` | `dismissReview` | the pull's merge box |
| react | `pull react`, `issue react`, `comment react` | `pull_react`, `issue_react`, `comment_react` | `addReaction`, `removeReaction` | its page |
| hide or show, as owner | `mod hide [--undo]` | `mod_hide` | `hideItem` | its page |
| report | `mod report` | `mod_report` | `createReport` (the pages'), `com.atproto.moderation.createReport` | its page, Report dialog |

## Landing and CI

| Action | CLI | MCP | XRPC | Web |
| --- | --- | --- | --- | --- |
| merge a pull now | `pull merge` | `pull_merge` | – | – |
| queue a pull, or take it out | `pull merge --queue`, `queue leave` | `pull_merge` with `queue`, `queue_leave` | – | – |
| undo a merged pull | `pull revert` | `pull_revert` | `revertPull` | the pull's page |
| bring a pull's branch up to date | `pull update-branch` | `pull_update_branch` | – | – |
| point a pull at other branches | `pull retarget` | `pull_retarget` | – | – |
| run a pull's or a ref's checks again, or one workflow | `run rerun` | `run_rerun` | – | – |
| run a workflow at a ref, with variables | `run rerun --ref --workflow -e` | `run_rerun` with `env` | – | – |
| cancel a pull's or a ref's runs, or one workflow's | `run cancel` | `run_cancel` | – | – |
| name or drop a runner | `runner add`, `runner remove` | `runner_add`, `runner_remove` | `inviteRunner`, `listRunnerInvites` | – |
| name or drop an agent | `agent add`, `agent remove` | `agent_add`, `agent_remove` | – | – |
| give runners a secret, or take it back | `secret set`, `secret remove` | `secret_set`, `secret_remove` | – | – |
| publish a release | `release publish` | `release_publish` | – | – |
| yank a release, or take that back | `release yank` | `release_yank` | – | – |

## Repositories

| Action | CLI | MCP | XRPC | Web |
| --- | --- | --- | --- | --- |
| create | `repo create` | `repo_create` | `createRepo` | `/new` |
| fork | `repo fork` | `repo_fork` | `forkRepo` | `<repo>` Fork button |
| change its description, links, topics, default branch | `repo edit` | `repo_edit` | – | – |
| rename | `repo rename` | `repo_rename` | – | – |
| archive, or stop | `repo archive [--undo]` | `repo_archive` | – | – |
| delete | `repo delete --yes` | `repo_delete` | – | – |
| offer, withdraw, accept a transfer | `repo transfer`, `repo transfer --undo`, `repo accept` | `repo_transfer`, `repo_accept` | – | – |
| share, unshare | `repo share [--undo]` | `repo_share` | – | – |
| protect a branch, or stop | `branch protect [--undo]` | `branch_protect` | – | – |
| create, delete, rename a branch | `branch create`, `branch delete`, `branch rename` | `branch_create`, `branch_delete`, `branch_rename` | – | – |
| create, delete a tag | `tag create`, `tag delete` | `tag_create`, `tag_delete` | – | – |
| define or remove a label | `label define`, `label delete` | `label_define`, `label_delete` | – | – |
| name or drop a triager | `triager add`, `triager remove` | `triager_add`, `triager_remove` | – | – |
| score a triager | `triager eval` | `triager_eval` | – | – |
| commit without a checkout | `repo commit` | `repo_commit` | `createCommit` (through a gateway) | – |
| push | git | – | `pushRefs` (through a gateway) | – |
| compact | `repo compact` | `repo_compact` | – | – |
| star, unstar | `repo star [--undo]` | `repo_star` | `starRepo`, `unstarRepo` | `<repo>` Star button |

## Account

| Action | CLI | MCP | XRPC | Web |
| --- | --- | --- | --- | --- |
| log in, log out | `login`, `logout` | – | `/oauth/login`, `/oauth/logout` | the header |
| switch accounts | – | – | `/oauth/switch` | the header |
| set a profile | `account profile` | `account_profile` | – | – |
| claim an email address, or stop | `account email add`, `account email remove` | `account_email_add`, `account_email_remove` | – | – |
| follow, unfollow | `account follow [--undo]` | `account_follow` | `followActor`, `unfollowActor` | profile, Follow button |
| block, unblock | `mod block [--undo]` | `mod_block` | – | – |
| delegate writes to a gateway | `account delegate` | `account_delegate` | `putDelegation`, `getDelegation` | – |
| delete your knotless data | `account delete-data` | `account_delete_data` | `deleteAccountData` | settings |
| choose which notifications you hear of | `notification settings`, `notification watch`, `notification subscribe`, `notification mute` | `notification_settings`, `notification_watch`, `notification_subscribe`, `notification_mute` | `putSubscription` | `/notifications`, settings |
| choose, check and publish themes | `theme use`, `theme check`, `theme publish`, `theme delete`, `theme list` | `theme_use`, `theme_check`, `theme_publish`, `theme_delete`, `theme_list` | – | – |

## Appview admin

For an account the appview's `KNOTLESS_ADMIN_DIDS` names. The methods
take its service token, or, from the site's own pages, its session there;
`getViewer` says `admin` for it.

| Action | CLI | MCP | XRPC | Web |
| --- | --- | --- | --- | --- |
| take down, or put back | `admin takedown [--undo]` | `admin_takedown` | `com.atproto.admin.updateSubjectStatus` | `/admin` |
| whether something is taken down | `admin status` | `admin_status` | `com.atproto.admin.getSubjectStatus` | `/admin` |
| the reports sent | `admin reports` | `admin_reports` | `listReports` | `/admin` |
| how the appview is used | `admin stats` | `admin_stats` | `getUsage` | `/admin` |
| what the appview logged | `admin logs` | `admin_logs` | `getLogs` | – |

## On one surface only

These belong where they are, as they act on the machine they run on:

- `login` and `logout` keep a session on the machine; the MCP tools run
  as that session, and the pages keep their own. `upgrade` replaces the
  `knotless` binary.
- `repo mirror` prints a local cache's path, `workflow pin` writes
  `.knotless/uses.lock` in a checkout, and `release download` writes a
  release's files to a directory.
- git itself clones, fetches and pushes, through `git-remote-knotless`;
  `repo tree`, `repo read` and `repo log` are how a command or tool, with
  no checkout, reads what git reads locally.
- `help` prints the commands.
- `registerPush` and `unregisterPush` are the iOS app's alone: a device's
  token means nothing to a command or a tool.

Nothing is on the MCP alone: every tool is a command's twin.