nandi.uk
Gleam CLI client for Tangled (clone of aly.codes/tg)
3.1 kB
108 lines
1# gtg
2
3A [Gleam](https://gleam.run) CLI client for [Tangled](https://tangled.org), the git forge built on AT Protocol.
4
5`gtg` is a Gleam reimplementation of [`aly.codes/tg`](https://tangled.org/aly.codes/tg) (the Go `tg` tool — an analogue of GitHub’s `gh`).
6
7## Features
8
9- **Auth** — OAuth (browser + localhost callback + DPoP) or app-password login; multi-account store
10- **Repos** — list, view, clone, create, delete, edit, set-default-branch
11- **Issues** — list, view, create, comment, close, reopen
12- **Pull requests** — list, view, create (patch upload), comment, diff, checkout, close, reopen, merge
13- **Strings** — list, view, create, delete
14- **SSH keys** — list, add, delete
15- **API** — call authenticated XRPC endpoints
16- **Browse** — open a repo on tangled.org
17
18Reads go through the Bobbin appview (default `https://bobbin.klbr.net`). Writes use your PDS session and knot service-auth JWTs.
19
20## Build / develop
21
22### With Nix (recommended)
23
24```bash
25nix develop # or: direnv allow (uses .envrc → use flake)
26gleam run -- --help
27gleam test
28```
29
30One-shot without entering the shell:
31
32```bash
33nix run . -- --help
34nix run . -- repo list aly.codes
35```
36
37### Without Nix
38
39Requires Erlang/OTP and Gleam on `PATH`:
40
41```bash
42gleam build
43gleam run -- --help
44gleam run -- auth status
45```
46
47## Quick start
48
49```bash
50# Log in with OAuth (opens browser; callback on 127.0.0.1:8095)
51gtg auth login alice.example.com
52
53# Or headless with an atproto app password
54gtg auth login alice.example.com xxxx-xxxx-xxxx-xxxx
55
56# Clone a repository (SSH)
57gtg repo clone aly.codes/tg
58
59# List issues / PRs (detects origin remote in a Tangled clone)
60gtg issue list
61gtg pr list
62
63# Create an issue
64gtg issue create --body "Details" "Bug report" -R handle/repo
65```
66
67## Configuration
68
69Precedence (highest first): flags → `TG_*` env → config file → defaults.
70
71| Source | Keys |
72|--------|------|
73| Flags | `--appview`, `--account`, `--config`, `--json` |
74| Env | `TG_APPVIEW`, `TG_ACCOUNT` |
75| File | `$XDG_CONFIG_HOME/gtg/config.toml` (also reads `tg/config.toml`) |
76
77```toml
78# ~/.config/gtg/config.toml
79appview = "https://bobbin.klbr.net"
80```
81
82Sessions are stored under `$XDG_DATA_HOME/gtg/` (not the OS keyring — unlike Go `tg`).
83
84## Architecture
85
86```
87src/gtg.gleam entrypoint
88src/gtg/cli.gleam command tree
89src/gtg/config.gleam flags / env / toml
90src/gtg/app/ domain service (repos, issues, PRs, …)
91src/gtg/atproto/ resolve, XRPC, OAuth+DPoP, password auth, PDS, sessions
92src/gtg/tangled/ Bobbin appview client
93src/gtg/knot/ knot RPCs
94src/gtg/gitutil.gleam git clone / remotes / patches
95```
96
97## Differences from Go `tg`
98
99| | `tg` (Go) | `gtg` (Gleam) |
100|--|-----------|---------------|
101| Auth | OAuth + app password, OS keyring | OAuth (DPoP) + app password, file store |
102| Binary name | `tg` | `gtg` |
103| Config dir | `~/.config/tg` | `~/.config/gtg` (falls back to reading `tg`) |
104| Completions / man | generated | not yet |
105
106## License
107
108MIT (this port). Upstream `tg` has its own license — see [aly.codes/tg](https://tangled.org/aly.codes/tg).