Getting started

Install

curl -fsSL https://knotless.dev/install.sh | sh

The script installs three binaries into $HOME/.local/bin: knotless (the CLI), git-remote-knotless (which lets git use knotless:// URLs) and knotless-mcp (for agents). KNOTLESS_INSTALL_DIR picks another directory, and KNOTLESS_VERSION another release.

To build from a clone instead:

cargo install --path crates/knotless
cargo install --path crates/knotless-mcp

Log in

knotless login alice.bsky.social

Your browser opens to approve knotless at your own PDS, over OAuth. knotless asks only for the dev.knotless.* records and blobs it writes, not your whole account (see scopes). The session lasts two weeks at most; after that, run knotless login again.

Without a browser, log in with an app password: pipe it to knotless login alice.bsky.social --password-stdin, or set KNOTLESS_PASSWORD. An app password cannot read other people's private repositories.

Push and clone

A repository's URL is knotless://<handle>/<name>. The first push creates the repository:

git push knotless://alice.bsky.social/my-project main
git clone knotless://alice.bsky.social/my-project

You can also add it as a remote:

git remote add origin knotless://alice.bsky.social/my-project
git push -u origin main

Anyone can clone a public repository straight from your PDS, with no knotless server involved.

To create a repository before the first push, with a description or a default branch, use knotless create. To list an account's repositories, use knotless ls:

knotless create knotless://alice.bsky.social/my-project --description "A small tool"
knotless ls alice.bsky.social

knotless create --private makes a private repository.

Connect an agent

An agent connected over MCP works as your account: it makes repositories, commits, opens issues and pulls, answers comments and queues merges, with no clone. In Claude Code, after knotless login:

claude mcp add knotless -- knotless-mcp

Assistants that connect to a server rather than start one, such as claude.ai, need nothing installed: add https://knotless.dev/mcp as a custom connector, and you sign in with your handle at your own PDS. Agents has both in full, and other clients.

Commit without a checkout

knotless commit changes files on a branch without a clone. --put writes a file at a path, --put-exec writes an executable one, --delete removes one, and - as a file reads standard input:

knotless commit knotless://alice.bsky.social/my-project -b main -m "Fix a typo" \
  --put README.md ./README.md --put-exec run.sh - --delete old.txt --json < run.sh

If the branch moved while you committed, the same changes are replayed onto its new tip and pushed again.

knotless branch makes a branch the same way, from the default branch or from a branch or commit you name. knotless refs lists the refs, in one round trip:

knotless branch knotless://alice.bsky.social/my-project feature main
knotless refs knotless://alice.bsky.social/my-project

Show who you are

The web pages show a commit as its author's account, with their Bluesky picture, once the account claims the address git authored it as. If your account has claimed none yet, your first push from a machine claims the address git uses there, and says so. To add or take back an address:

knotless email add me@work.example
knotless email remove me@old.example

Claims are stored hashed, so they name no address.

Your page on knotless shows your Bluesky profile. To show something else, set a knotless profile. Each field you set replaces Bluesky's, and a field set to '' shows Bluesky's again:

knotless profile --name "Me" --bio "Small tools for text." --pronouns they/them \
  --link https://me.example --link https://me.example/blog --title Blog --avatar me.png
knotless profile --bio '' --link ''

--title names the --link before it. --avatar takes a PNG or JPEG file.