A command-line interface for tangled, the decentralized Git collaboration platform built on the AT Protocol. eric-wien.tngl.io/tng-cli
README.md

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_grant errors, run tng auth login to re-authenticate.
  • Repo view on empty repos: tng repo view returns 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 unless default_knot is 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:

  1. upstream remote
  2. tangled remote
  3. origin remote

You can override this with:

  • The -R / --repo flag on any command
  • The TNG_REPO environment variable (owner/name or 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.declaration on 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.receivePack token.
  • 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