tgl reference #

Español · Back to the README

Commands #

• The Tangled repo is taken from the git remote (git@tangled.org:did:plc:...), or given with -R owner/name or -R did:plc:....

• <pr> and <issue> are the number the website shows (12 or #12) or the id shown by list; a PR can also be named by its branch. [<pr>] can be left out: then it is the open PR of the current branch.

• Every command has --help. pr create, pr update, pr merge and release upload have --dry-run, which checks everything without writing anything.

• Lists show the 30 newest by default; --limit 0 shows all.

• --json prints the data for other programs to read.

• pr checkout creates a local branch with a PR's changes so you can try them. Your working copy must have no uncommitted changes. If the changes don't apply, nothing is left behind.

• There are two ways to finish a PR. pr merge has Tangled's server apply it, like the website's merge button: each commit is kept, with new hashes, so afterwards pull the target branch (and push it to any mirror, e.g. GitHub). Or merge locally, push, and run pr close --merged, which doesn't merge anything; it only changes the PR's state. Both close the issues named as Fixes #12 (or Closes, Resolves, or with a link to the issue) in the PR's title or description, or in a comment on it by its author or the repo's owner or collaborators, with a comment linking to the PR; --keep-issues leaves them open. Only issues of the same repo, and only if you may close them. pr create and pr edit turn that #12 into a link to the issue (Tangled shows a plain #12 as text), and the closing comment links back to the PR.

• pr create and pr update stop if the branch has commits that aren't pushed to Tangled (--allow-unpushed goes ahead anyway). A Tangled PR keeps the changes it was sent with: after new commits, push them and run pr update.

• pr edit, pr update and issue edit only work on your own PRs and issues.

• Labels: --add good-first-issue, or --add assignee=alice.bsky.social for labels that take a value. --add and --remove can be repeated. Only the repo's owner and collaborators can change labels; label with no options shows the repo's labels.

• label create makes your own labels: --kind simple (no value, the default), text, person, number or yes-no; --values high,medium,low for fixed choices; --multiple for several values at once; --for issues|prs|both; --color "#E11D48". Only the repo's owner can create or delete labels. label delete also deletes a label you created; Tangled's own labels are only removed from the repo.

• issue stale puts a label (default stale, create it first with tgl label create stale --for issues) on open issues with no comments or state changes in --days days (default 60), and takes it off when they get activity again. It only labels; --comment "…" also posts a comment. To run it every day, use a scheduled pipeline (below).

• In a CI pipeline, log in with environment variables instead of tgl auth login: TGL_ACCOUNT (your handle or DID) and TGL_APP_PASSWORD (a separate app password, stored as a pipeline secret; Tangled never gives secrets to pipelines of PRs from forks). For example, .tangled/workflows/stale.yml:

  when:
    - event: schedule
      schedule:
        - cron: "H 6 * * *"
  engine: microvm
  image: nixos
  dependencies:
    - nodejs_22
  environment:
    TGL_ACCOUNT: "alice.bsky.social"   # TGL_APP_PASSWORD goes in Settings → Secrets
  steps:
    - name: "Mark stale issues"
      command: npx --yes tangled-cli issue stale --days 60 -R "$TANGLED_REPO_DID/$TANGLED_REPO_NAME"
  

• repo create makes an empty repo (default branch main, host knot1.tangled.sh); --remote tangled also adds it as a git remote. For pipelines, pick a CI server with --spindle spindle.tangled.sh or later in the repo's settings on the website.

• --web opens the page in your browser. PR and issue pages go by number, so with an id or a branch the list opens instead.

• -b can be replaced by -F file.md to read the text from a file.

• release upload: the tag must be annotated (git tag -a), already pushed to Tangled, and the same tag as in your copy. Tangled accepts up to 50 MB per file. A tag can't get two files with the same name.

• Ids are the last part of each record's address, as shown by list. Numbers are assigned by Tangled's website and are in no record: tgl reads them from the item's web page, and list shows ids, not numbers.

• Messages are in English, or in Spanish on Spanish systems. Force one with TGL_LANG=en or TGL_LANG=es.

• On Linux systems without a secret service, the app password falls back to a file only your user can read, and tgl tells you so.

How it works #

On Tangled, as everywhere on the AT Protocol, each person's data lives in their own account. A PR or an issue is a record in its author's account that points at the repo.

• Writing (create, comment, close…) saves records to your account with your app password. Repo settings, merges and new repos (repo set-default-branch, pr merge, repo create) go to the repo's git server (its "knot") with a one-use token your account issues for that single action.
• Reading other people's PRs, issues and comments needs an index of "which records point at this repo". tgl uses two public, read-only community services from microcosm: Constellation (that index) and Slingshot (a fast cache of records, updated live). Neither ever sees your credentials. If Slingshot fails, records are read from their author's server. If Constellation is down, tgl warns you and still shows the records in your own account. Your own records are always read straight from your account.
• A state change (close, reopen, merge) only counts if Tangled would accept it: from the author, the repo owner, a collaborator or Tangled itself.

Records used: sh.tangled.repo.pull (with the changes as a gzipped git format-patch), .pull.status, sh.tangled.repo.issue, .issue.state, sh.tangled.feed.comment (comments on both; the older .pull.comment and .issue.comment are still read) and sh.tangled.repo.artifact (a release file, linked to its tag by the tag's hash).

These formats have no official documentation and may change. They follow Tangled's lexicons, including older formats still found in long-lived repos.

Known limitation: on large, old repos a few old PRs (mostly stacked PRs) may show a different state from the website, which can't be rebuilt from public records alone. Issues and PRs in the current format match the website.