dunkirk.sh
1# Getting Started with Tangled CLI
2
3This guide will help you get up and running with the Tangled CLI.
4
5## Installation
6
7### Prerequisites
8
9- Rust toolchain 1.70 or later
10- Git
11- A Bluesky/AT Protocol account
12
13### Build from Source
14
151. Clone the repository:
16 ```sh
17 git clone https://tangled.org/tangled/tangled-cli
18 cd tangled-cli
19 ```
20
212. Build the project:
22 ```sh
23 cargo build --release
24 ```
25
263. The binary will be available at `target/release/tangled-cli`. Optionally, add it to your PATH or create an alias:
27 ```sh
28 alias tangled='./target/release/tangled-cli'
29 ```
30
31### Install from AUR (Arch Linux)
32
33If you're on Arch Linux, you can install from the AUR:
34
35```sh
36yay -S tangled-cli-git
37```
38
39## First Steps
40
41### 1. Authenticate
42
43Login with your AT Protocol credentials (your Bluesky account):
44
45```sh
46tangled auth login
47```
48
49You'll be prompted for your handle (e.g., `alice.bsky.social`) and password. If you're using a custom PDS, specify it with the `--pds` flag:
50
51```sh
52tangled auth login --pds https://your-pds.example.com
53```
54
55Your credentials are stored securely in your system keyring.
56
57### 2. Check Your Status
58
59Verify you're logged in:
60
61```sh
62tangled auth status
63```
64
65### 3. List Your Repositories
66
67See all your repositories:
68
69```sh
70tangled repo list
71```
72
73Or view someone else's public repositories:
74
75```sh
76tangled repo list --user alice.bsky.social
77```
78
79### 4. Create a Repository
80
81Create a new repository on Tangled:
82
83```sh
84tangled repo create my-project --description "My awesome project"
85```
86
87By default, repositories are created on the default knot (`tngl.sh`). You can specify a different knot:
88
89```sh
90tangled repo create my-project --knot knot1.tangled.sh
91```
92
93### 5. Clone a Repository
94
95Clone a repository to start working on it:
96
97```sh
98tangled repo clone alice/my-project
99```
100
101This uses SSH by default. For HTTPS:
102
103```sh
104tangled repo clone alice/my-project --https
105```
106
107## Working with Issues
108
109### Create an Issue
110
111```sh
112tangled issue create --repo my-project --title "Add new feature" --body "We should add feature X"
113```
114
115### List Issues
116
117```sh
118tangled issue list --repo my-project
119```
120
121### View Issue Details
122
123```sh
124tangled issue show <issue-id>
125```
126
127### Comment on an Issue
128
129```sh
130tangled issue comment <issue-id> --body "I'm working on this!"
131```
132
133## Working with Pull Requests
134
135### Create a Pull Request
136
137```sh
138tangled pr create --repo my-project --base main --head feature-branch --title "Add feature X"
139```
140
141The CLI will use `git format-patch` to create a patch from your branch.
142
143### List Pull Requests
144
145```sh
146tangled pr list --repo my-project
147```
148
149### Review a Pull Request
150
151```sh
152tangled pr review <pr-id> --approve --comment "Looks good!"
153```
154
155Or request changes:
156
157```sh
158tangled pr review <pr-id> --request-changes --comment "Please fix the tests"
159```
160
161### Merge a Pull Request
162
163```sh
164tangled pr merge <pr-id>
165```
166
167## CI/CD with Spindle
168
169Spindle is Tangled's integrated CI/CD system.
170
171### Enable Spindle for Your Repository
172
173```sh
174tangled spindle config --repo my-project --enable
175```
176
177Or use a custom spindle URL:
178
179```sh
180tangled spindle config --repo my-project --url https://my-spindle.example.com
181```
182
183### View Pipeline Runs
184
185```sh
186tangled spindle list --repo my-project
187```
188
189### Stream Workflow Logs
190
191```sh
192tangled spindle logs knot:rkey:workflow-name
193```
194
195Add `--follow` to tail the logs in real-time.
196
197### Manage Secrets
198
199Add secrets for your CI/CD workflows:
200
201```sh
202tangled spindle secret add --repo my-project --key API_KEY --value "my-secret-value"
203```
204
205List secrets:
206
207```sh
208tangled spindle secret list --repo my-project
209```
210
211Remove a secret:
212
213```sh
214tangled spindle secret remove --repo my-project --key API_KEY
215```
216
217## Advanced Topics
218
219### Repository Migration
220
221Move a repository to a different knot:
222
223```sh
224tangled knot migrate --repo my-project --to knot2.tangled.sh
225```
226
227This command must be run from within the repository's working directory, and your working tree must be clean and pushed.
228
229### Output Formats
230
231Most commands support JSON output:
232
233```sh
234tangled repo list --format json
235```
236
237### Quiet and Verbose Modes
238
239Reduce output:
240
241```sh
242tangled --quiet repo list
243```
244
245Increase verbosity for debugging:
246
247```sh
248tangled --verbose repo list
249```
250
251## Configuration
252
253The CLI stores configuration in:
254- Linux: `~/.config/tangled/config.toml`
255- macOS: `~/Library/Application Support/tangled/config.toml`
256- Windows: `%APPDATA%\tangled\config.toml`
257
258Session credentials are stored securely in your system keyring (GNOME Keyring, KWallet, macOS Keychain, or Windows Credential Manager).
259
260### Environment Variables
261
262- `TANGLED_PDS_BASE` - Override the default PDS (default: `https://bsky.social`)
263- `TANGLED_API_BASE` - Override the Tangled API base (default: `https://tngl.sh`)
264- `TANGLED_SPINDLE_BASE` - Override the Spindle base (default: `wss://spindle.tangled.sh`)
265
266## Troubleshooting
267
268### Keyring Issues on Linux
269
270If you see keyring errors on Linux, ensure you have a secret service running:
271
272```sh
273# For GNOME
274systemctl --user enable --now gnome-keyring-daemon
275
276# For KDE
277# KWallet should start automatically with Plasma
278```
279
280### Authentication Failures
281
282If authentication fails with your custom PDS:
283
284```sh
285tangled auth login --pds https://your-pds.example.com
286```
287
288Make sure the PDS URL is correct and accessible.
289
290### "Repository not found" Errors
291
292Verify the repository exists and you have access:
293
294```sh
295tangled repo info owner/reponame
296```
297
298## Getting Help
299
300For command-specific help, use the `--help` flag:
301
302```sh
303tangled --help
304tangled repo --help
305tangled repo create --help
306```
307
308## Next Steps
309
310- Explore all available commands with `tangled --help`
311- Set up CI/CD workflows with `.tangled.yml` in your repository
312- Check out the main README for more examples and advanced usage
313
314Happy collaborating! 🧶