- Go 99%
- Makefile <1%
- Shell <1%
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.