chadtmiller.com/knotless
git that lives in your Atmosphere account
7
# Getting started
## Install
```sh
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:
```sh
cargo install --path crates/knotless
cargo install --path crates/knotless-mcp
```
## Log in
```sh
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](../design/access.md#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](private.md).
## Push and clone
A repository's URL is `knotless://<handle>/<name>`. The first push creates
the repository:
```sh
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:
```sh
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`:
```sh
knotless create knotless://alice.bsky.social/my-project --description "A small tool"
knotless ls alice.bsky.social
```
`knotless create --private` makes a [private repository](private.md).
## 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`:
```sh
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](agents.md) 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:
```sh
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:
```sh
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:
```sh
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:
```sh
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.