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