A terminal client for Tangled.
tui
go
tangled
cli
docs: document write commands and platform limits
Aly Raffauf
(Jul 15, 2026, 12:14 PM EDT)
9fb639f4
4a6a4b6a
+89
-3
+60
PLAN.md
+60
PLAN.md
···
1
+
# tg → gh feature-parity — progress
2
+
3
+
Goal: close the gap to *rough* parity with GitHub's `gh`, implementing every capability the
4
+
Tangled platform supports and documenting the hard limits. Full plan/rationale:
5
+
`~/.claude/plans/identify-the-missing-features-foamy-spring.md`.
6
+
7
+
Decisions: phased (core-writes-first) · strictly mirror `gh` (no native-only
8
+
star/follow/vouch/profile) · state mutations gated behind a verification spike.
9
+
10
+
## Legend
11
+
- [ ] not started · [~] in progress · [x] done
12
+
13
+
## Shared plumbing
14
+
- [x] `DeleteRecord` helper in `atproto/records.go` (`com.atproto.repo.deleteRecord`)
15
+
- [x] `UploadBlob` helper in `atproto/records.go` (`com.atproto.repo.uploadBlob`)
16
+
17
+
## Phase 0 — verification spike (gates Phase 3)
18
+
- [x] Confirm write path: issue close/reopen
19
+
- [x] Confirm write path: pr close/reopen/merge
20
+
- [x] Confirm mechanism: repo delete + repo fork
21
+
- [x] Confirm `sh.tangled.repo.issue.comment` / `.pull.comment` record shapes
22
+
- [x] Add required scopes in `atproto/auth.go` `DefaultScopes` (re-login required)
23
+
24
+
## Phase 1 — core writes
25
+
- [x] `issue create` (`internal/cli/issue_create.go`)
26
+
- [x] `issue comment` (`internal/cli/issue_comment.go`)
27
+
- [x] `pr comment` (`internal/cli/pr_comment.go`)
28
+
- [x] `pr diff` (`internal/cli/pr_diff.go`)
29
+
- [x] `repo edit` (`internal/cli/repo_edit.go`)
30
+
- [x] `repo set-default-branch` (`internal/cli/repo_set_default_branch.go`)
31
+
- [x] `ssh-key delete` (`internal/cli/ssh_key_delete.go`)
32
+
- [x] `repo delete` (`internal/cli/repo_delete.go`)
33
+
34
+
## Phase 2 — pr create (complex)
35
+
- [x] Patch-generation helper in `internal/gitutil/`
36
+
- [x] `pr create` (uploadBlob + putRecord `sh.tangled.repo.pull`)
37
+
38
+
## Phase 3 — state mutations (only if Phase 0 is go)
39
+
- [x] `issue close` / `issue reopen` / `issue edit`
40
+
- [x] `pr close` / `pr reopen` / `pr edit`
41
+
- [x] `pr merge` (knot RPC + status record)
42
+
- [x] Add required rpc scopes to `DefaultScopes` (note: forces re-login)
43
+
44
+
## Deferred
45
+
- [ ] `pr checkout`: needs an immutable base commit/ref before it can safely materialize a PR in an isolated worktree
46
+
47
+
## Phase 4 — parity & convenience
48
+
- [x] `browse`
49
+
- [x] `completion` (Cobra built-in)
50
+
- [x] `auth token`
51
+
- [x] `api` raw XRPC passthrough
52
+
- [x] `repo fork`
53
+
- [ ] `search` (scoped to Bobbin's supported filters)
54
+
- [ ] `auth switch` (deferred — needs multi-account state refactor)
55
+
- [ ] README: document new commands + hard-limit list
56
+
57
+
## Hard limits (excluded)
58
+
`release`, `gist`, `workflow`/`run` (CI/spindle — no query API/scope),
59
+
`repo archive`/`sync`/`rename`, `pr checks`, projects/codespaces, `gh status` dashboard,
60
+
native-only star/follow/vouch/profile.
+29
-3
README.md
+29
-3
README.md
···
1
1
# tg
2
2
3
-
`tg` is a command-line client for [Tangled](https://tangled.org), the git forge built on atproto. It is an analogue to the GitHub CLI (`gh`), (for now) built against the read-only [Bobbin](https://docs.tangled.org/bobbin) XRPC API.
3
+
`tg` is a command-line client for [Tangled](https://tangled.org), the git forge built on atproto. It is an analogue to the GitHub CLI (`gh`), using Bobbin for reads and authenticated PDS/knot writes.
4
4
5
5
## Installation
6
6
···
50
50
51
51
# List issues for an explicit repository
52
52
tg issue list microcosm.blue/microcosm-rs
53
+
54
+
# Create, comment on, and update an issue
55
+
tg issue create --repo microcosm.blue/microcosm-rs --body "Details" "Bug report"
56
+
tg issue comment <rkey> --body "I can reproduce this"
57
+
tg issue close <rkey>
58
+
tg issue reopen <rkey>
59
+
tg issue edit <rkey> --title "Updated title"
53
60
```
54
61
55
62
### Pull Requests
···
58
65
# List pull requests
59
66
tg pr list
60
67
61
-
# Check out a pull request as detached HEAD
62
-
tg pr checkout 3mporttfqez22
68
+
# Create, comment on, inspect, and update pull requests
69
+
tg pr create --title "Add feature" --base main
70
+
tg pr diff <rkey>
71
+
tg pr comment <rkey> --body "Looks good"
72
+
tg pr close <rkey>
73
+
tg pr merge <rkey>
63
74
```
75
+
76
+
### Other commands
77
+
78
+
`tg repo edit`, `tg repo set-default-branch`, `tg repo delete --yes`, `tg repo fork`,
79
+
`tg ssh-key delete`, `tg browse`, `tg completion`, `tg auth token`, and `tg api` are available.
80
+
81
+
Changing scopes requires existing users to run `tg auth login` again.
82
+
83
+
## Platform limits
84
+
85
+
Tangled currently has no API for releases, gists, workflows/runs, repository archive/sync/rename,
86
+
PR checks, projects, codespaces, a status dashboard, or global text search. `tg pr checkout` is
87
+
deferred until PRs expose an immutable base commit/ref, allowing a safe isolated-worktree
88
+
implementation. `auth switch` is deferred because the local auth store currently supports one
89
+
account.
64
90
65
91
## Architecture
66
92