- Go 100%
- Makefile <1%
tng #
A command-line interface for Tangled, the decentralized Git collaboration platform built on the AT Protocol.
tng brings the full Tangled workflow to your terminal: authenticate with your AT Protocol identity, manage repositories, create and review pull requests, file and track issues -- all without leaving the command line.
Known Issues #
- OAuth session expiry: The public client OAuth flow produces tokens that cannot always be refreshed silently. If you encounter
invalid_granterrors, runtng auth loginto re-authenticate. - Repo view on empty repos:
tng repo viewreturns a 404 for repos with no commits, since the knot has no ref to resolve. Push at least one commit first.
tng targets Tangled core 1.20.0. Repositories, issues, pull requests and
comments use the org.tangled.* records hosted by Rust knots.
Installation #
From source #
go install tangled.org/eric.wien/tng-cli.git/v2/cmd/tng@latest
The .git module path uses Git discovery directly. The binary is named tng.
Build from source #
git clone git@tangled.sh:eric.wien/tng-cli
cd tng-cli
make build
# Binary is at ./bin/tng
Updating #
tng upgrade # Check the Go module proxy and install the latest release via go install
tng upgrade --check # Only check whether a newer release exists
tng upgrade is equivalent to go install tangled.org/eric.wien/tng-cli.git/v2/cmd/tng@latest
and requires a Go toolchain. For source builds, use git pull && make install instead.
Makefile targets #
make build # Build the binary
make test # Run tests
make lint # Run golangci-lint
make install # Install to /usr/local/bin
make clean # Remove build artifacts
Quick Start #
# 1. Authenticate with your AT Protocol handle
tng auth login --handle example.bsky.social
# 2. Create a repository on a knot
tng repo create my-project --knot knot.example.com
# 3. Clone it
tng repo clone example.bsky.social/my-project
# 4. Work on code, then create a pull request
cd my-project
git checkout -b feature-branch
# ... make changes, commit ...
git push -u origin feature-branch
tng pr create --title "Add new feature" -b main
# 5. List and view your pull requests
tng pr list
tng pr view <rkey>
# 6. Open in browser
tng browse
Authentication #
tng uses AT Protocol OAuth 2.0 with PKCE and DPoP. Your handle can be from any AT Protocol provider -- Bluesky (example.bsky.social), Tangled (example.tngl.sh), or any self-hosted PDS.
# Interactive login (opens browser)
tng auth login
# Login with a specific handle
tng auth login --handle example.bsky.social
# Login from an SSH or other headless session
tng auth login --manual --handle example.bsky.social
# Check who you're logged in as
tng auth status
# Log out
tng auth logout
Login requests permission to manage repository declarations and obtain method-bound
service-auth tokens for knot writes. Run tng auth login if your session lacks
these permissions.
Sessions are stored in ~/.config/tng/. Tokens are persisted locally and refreshed automatically. The public client flow is used, so tokens expire after approximately two weeks.
When run over SSH, tng auth login automatically uses manual browser
authentication. Open the displayed authorization URL on your local machine,
authorize the CLI, then copy the full localhost callback URL from the browser's
address bar back into the terminal. Use --manual to select the same flow in
other headless environments.
Environment variables #
| Variable | Description |
|---|---|
TNG_HOST |
Override the trusted appview API and merge mirror (default: https://api.tangled.org) |
TNG_CONFIG_DIR |
Override config directory |
TNG_REPO |
Override repository context (owner/name or repository DID) |
TNG_FORCE_TTY |
Force TTY output in non-TTY contexts |
NO_COLOR |
Disable color output |
Commands #
tng auth -- Authentication #
tng auth login [--handle <handle>] [--manual] # Log in via browser OAuth
tng auth logout [--did <did>] # Log out and revoke tokens
tng auth status # Show authenticated accounts
tng repo -- Repositories #
tng repo create <name> [flags] # Create a new repository
tng repo clone <owner/repo> [dir] # Clone via SSH
tng repo delete <owner/repo> # Delete a repository
tng repo view [owner/repo] # View repository details
tng repo list [owner] # List repositories
Flags for repo create:
-d, --description-- Repository description--default-branch-- Default branch name (default:main)-k, --knot-- Knot URL to create the repo on (required unlessdefault_knotis set in config)-c, --clone-- Clone after creation
Flags for repo clone:
-k, --knot-- Knot hostname to clone from (skips AT Protocol record lookup)
Flags for repo delete:
-y, --yes-- Skip confirmation prompt
Deletion removes the owner's org.tangled.repo.declaration and any legacy
sh.tangled.repo record before deleting the knot repository. Each record must
identify the target repository DID; deletion uses its current CID to avoid
removing a record that changed after it was read. Removing legacy records requires
the repo:sh.tangled.repo?action=delete login permission. If the PDS reports
ScopeMissingError, run tng auth login to grant it before retrying.
If the knot response is uncertain, the error includes the repository DID for
inspection and retry. The CLI does not restore a declaration that might point
to an already-deleted repository.
Flags for repo view:
-w, --web-- Print the repository URL instead
Flags for repo list:
-L, --limit-- Maximum number of results (default: 30)
tng pr -- Pull Requests #
Pull requests are org.tangled.track.ticket records with a target branch, stored
under the repository DID on its knot. Use the record key shown by tng pr list.
Patch records refer to base and head commits, not uploaded patch files.
Push the source branch before running pr create. For a fork, pass
--head-repo owner/name. The local checkout must contain the target branch tip
so Git can find the common ancestor; fetch the target repository first.
pr merge rebases the latest patch through the configured appview mirror, then
marks the ticket completed. The mirror receives a short-lived token restricted
to git push on the target knot. Only configure a mirror you trust. If a merge
returns an uncertain result, do not repeat the merge until you inspect the target
branch. If its history and contents confirm that the PR's changes are merged,
run tng pr merge <rkey> -R owner/name --complete-only to finish the ticket.
This flag only marks an open PR completed; it neither checks nor changes git.
It also handles a successful merge whose ticket update failed. Concurrent ticket
edits still require a fresh read; completion never overwrites them blindly.
tng pr create [flags] # Create a pull request
tng pr list [flags] # List repository pull requests from all authors
tng pr view <rkey> [flags] # View PR details
tng pr diff <rkey> # View PR patch
tng pr merge <rkey> # Merge a pull request
tng pr close <rkey> # Close a pull request
tng pr comment <rkey> --body "..." # Comment on a PR
Flags for pr create:
-t, --title-- PR title (required)-B, --body-- PR description-b, --base-- Target branch (default: the repo's default branch)-H, --head-- Source branch (default: current branch)--head-repo-- Source repository for a fork (default: target repository)
Flags for pr merge:
--complete-only-- Mark the ticket completed without merging; first verify its changes are in the target branch
Flags for pr list:
-R, --repo-- Filter by repository (owner/name)-w, --web-- Print the pull requests URL on tangled.org
All PR commands use the selected repository. Pass -R owner/name or a repository
DID when outside its checkout. pr view --web prints the repository pull-request URL.
tng issue -- Issues #
Issues are repository-owned org.tangled.track.ticket records without a target
branch. issue list includes all authors and states in the selected repository.
Closing a ticket edits its state with a CID check to protect concurrent edits.
Comments reference the ticket URI and CID.
tng issue create [flags] # Create an issue
tng issue list [flags] # List repository issues from all authors
tng issue view <rkey> [flags] # View issue details
tng issue close <rkey> # Close an issue
tng issue comment <rkey> --body "..." # Comment on an issue
Flags for issue create:
-t, --title-- Issue title (required)-b, --body-- Issue body-R, --repo-- Repository override (owner/name)
Flags for issue list:
-R, --repo-- Filter by repository (owner/name)-w, --web-- Print the issues URL on tangled.org
All issue commands accept the global -R/--repo flag. issue view --web prints
the repository issue URL.
tng browse -- Open in Browser #
tng browse # Open current repo
tng browse src/main.go # Open specific file
tng browse -n # Print URL without opening
tng browse -R owner/repo # Open specific repo
Utilities #
tng upgrade [--check] # Upgrade to the latest release (alias: update)
tng version # Print version
tng completion <bash|zsh|fish> # Generate shell completions
Repository Context #
Inside a checkout, tng detects repositories from owner/name remotes on
tangled.org, tangled.sh, the public knots, and knot.* hosts. It also accepts
repository-DID paths over HTTPS and SSH. For other hostnames, set the repository
explicitly. Remote priority:
upstreamremotetangledremoteoriginremote
You can override this with:
- The
-R/--repoflag on any command - The
TNG_REPOenvironment variable (owner/nameor a repository DID) git config tng.default-repo owner/name
Shell Completions #
# Bash
tng completion bash > /etc/bash_completion.d/tng
# Zsh
tng completion zsh > "${fpath[1]}/_tng"
# Fish
tng completion fish > ~/.config/fish/completions/tng.fish
Configuration #
Config file is at ~/.config/tng/config.yml:
default_knot: "" # Default knot for repo creation
api_host: "" # Override API host
Architecture #
tng follows the same architectural patterns as the GitHub CLI:
- Written in Go with cobra for command parsing
- Factory pattern for dependency injection with lazy initialization
- AT Protocol OAuth via indigo (PKCE + DPoP)
- XRPC API client for Tangled's AT Protocol-based endpoints
- Automatic git remote detection for Tangled repositories
Key differences from gh #
- Authentication: AT Protocol OAuth 2.0 (not GitHub's device flow). Requires identity resolution through the AT Protocol stack (handle -> DID -> PDS -> auth server).
- Data model: The owner stores an
org.tangled.repo.declarationon their PDS. Its repository DID points to the knot, which hosts the manifest, tickets, comments and patches. - Writes: Knot record writes use service-auth tokens addressed to the repository DID. Edits and deletes include the current record CID. Repository creation and deletion use the knot service DID.
- Pull requests: Patches reference pushed commits. The appview mirror performs merges using a forwarded
org.tangled.git.receivePacktoken. - Discovery: Repository declarations and DID documents resolve owner/name to a knot without an appview lookup.
Project Structure #
cmd/tng/ Entry point
internal/
tngcmd/ Root command assembly, exit codes
authflow/ AT Protocol OAuth (PKCE, DPoP, callback server)
config/ Config files, session storage
build/ Version info (ldflags, Go build metadata fallback)
pkg/
cmd/ Command implementations
auth/ login, logout, status
repo/ create, clone, delete, view, list
pr/ create, list, view, diff, merge, close, comment
issue/ create, list, view, close, comment
browse/ Open in browser
upgrade/ Upgrade via the Go module proxy + go install
cmdutil/ Factory, errors, arg validators
iostreams/ TTY detection, color, terminal width
api/ XRPC API client and domain methods
context/ Git remote -> Tangled repo resolution
git/ Git CLI wrapper, remote URL parsing
License #
MIT