README.md

knit #

A command line interface for Tangled, modeled on the GitHub CLI (gh).

Installation #

Using go (1.26 or later):

go install tangled.org/rockorager.dev/knit/cmd/knit@latest

Otherwise,

git clone https://tangled.org/rockorager.dev/knit
cd knit
make install

Logging in #

knit auth login

knit asks for your handle and opens your browser to approve access with atproto OAuth. On a machine without a browser, such as over SSH, open the printed URL on any device and approve. The browser then fails to load a 127.0.0.1 page; paste that page's address into knit to finish.

You can also log in with an app password from your PDS:

knit auth login --app-password --handle alice.tngl.sh

knit auth status shows who you're logged in as, and knit auth logout signs out. Credentials are stored in ~/.config/knit/auth.json (or the platform's equivalent), readable only by you.

Reading public data, such as listing issues, doesn't need a login.

Usage #

Inside a clone of a Tangled repository, commands act on that repository. knit looks at the upstream remote first, then origin, then any other remote. Use -R OWNER/NAME to pick another repository.

knit repo create my-project --description "Something new"
knit repo create --source . --push        # publish an existing local repo
knit repo clone tangled.org/core
knit repo fork tangled.org/core --clone
knit repo view
knit repo list alice.tngl.sh

knit issue list --state all
knit issue create --title "Crash on startup" --label bug
knit issue view 12 --comments
knit issue comment 12 --body "Fixed in main"
knit issue close 12

knit pr create --fill
knit pr list --author @me
knit pr view 34
knit pr checkout 34
knit pr diff 34 | git am
knit pr merge 34 --delete-branch

knit pipeline list
knit pipeline watch --exit-status
knit pipeline logs 3mzjc4h7tzk22
knit pipeline rerun --failed
knit pr checks 34
knit workflow run deploy.yml --ref main -f environment=staging

knit browse
knit ssh-key add ~/.ssh/id_ed25519.pub
knit api org.tangled.repo.listRepos -f subject=did:plc:...

Run knit help <command> for every flag. List and view commands accept --json for scripting and --web to open the page in your browser.

Pull requests #

A Tangled pull request is a series of immutable rounds. knit pr create pushes your branch, opens the pull request, and submits round 0. Pushing more commits to the branch doesn't change what reviewers see; when you're ready for another review, submit a new round:

git push
knit pr resubmit

Merging rebases the latest round onto the target branch.

Pushing over HTTPS #

Knots accept a short-lived token from your PDS as the password for HTTPS pushes. To push without an SSH key, let knit answer git's credential requests:

knit auth setup-git

This configures the default knot; pass --hostname for others.

Configuration #

knit config set git_protocol ssh
knit config list
Setting Default Meaning
git_protocol https Protocol for clone URLs and new remotes
editor $VISUAL, $EDITOR Editor for issue, pull request, comment bodies
browser $BROWSER, OS opener Command that opens web pages
knot knot1.tangled.sh Knot for new repositories and forks
appview https://tangled.org Tangled web interface
api https://api.tangled.org Tangled API

Each setting can also be set with an environment variable such as KNIT_GIT_PROTOCOL. KNIT_REPO works like -R, and KNIT_CONFIG_DIR moves the configuration directory.