dunkirk.sh
1# Tangled CLI
2
3A Rust CLI for Tangled, a decentralized git collaboration platform built on the AT Protocol.
4
5## Features
6
7Tangled CLI is a fully functional tool for managing repositories, issues, pull requests, and CI/CD workflows on the Tangled platform.
8
9### Implemented Commands
10
11- **Authentication** (`auth`)
12 - `login` - Authenticate with AT Protocol credentials
13 - `status` - Show current authentication status
14 - `logout` - Clear stored session
15
16- **Repositories** (`repo`)
17 - `list` - List your repositories or another user's repos
18 - `create` - Create a new repository on a knot
19 - `clone` - Clone a repository to your local machine
20 - `info` - Show detailed repository information
21 - `delete` - Delete a repository
22 - `star` / `unstar` - Star or unstar repositories
23
24- **Issues** (`issue`)
25 - `list` - List issues for a repository
26 - `create` - Create a new issue
27 - `show` - Show issue details and comments
28 - `edit` - Edit issue title, body, or state
29 - `comment` - Add a comment to an issue
30
31- **Pull Requests** (`pr`)
32 - `list` - List pull requests for a repository
33 - `create` - Create a pull request from a branch
34 - `show` - Show pull request details and diff
35 - `review` - Review a pull request (approve/request changes)
36 - `merge` - Merge a pull request
37
38- **Knot Management** (`knot`)
39 - `migrate` - Migrate a repository to another knot
40
41- **CI/CD with Spindle** (`spindle`)
42 - `config` - Enable/disable or configure spindle for a repository
43 - `list` - List pipeline runs for a repository
44 - `logs` - Stream logs from a workflow execution
45 - `secret` - Manage secrets for CI/CD workflows
46 - `list` - List secrets for a repository
47 - `add` - Add or update a secret
48 - `remove` - Remove a secret
49 - `run` - Manually trigger a workflow (not yet implemented)
50
51## Installation
52
53### Build from Source
54
55Requires Rust toolchain (1.70+) and network access to fetch dependencies.
56
57```sh
58cargo build --release
59```
60
61The binary will be available at `target/release/tangled-cli`.
62
63### Install from AUR (Arch Linux)
64
65Community-maintained package:
66
67```sh
68yay -S tangled-cli-git
69```
70
71## Quick Start
72
731. **Login to Tangled**:
74 ```sh
75 tangled auth login --handle your.handle.bsky.social
76 ```
77
782. **List your repositories**:
79 ```sh
80 tangled repo list
81 ```
82
833. **Create a new repository**:
84 ```sh
85 tangled repo create myproject --description "My cool project"
86 ```
87
884. **Clone a repository**:
89 ```sh
90 tangled repo clone username/reponame
91 ```
92
93## Workspace Structure
94
95- `crates/tangled-cli` - CLI binary with clap-based argument parsing
96- `crates/tangled-config` - Configuration and session management (keyring-backed)
97- `crates/tangled-api` - XRPC client wrapper for AT Protocol and Tangled APIs
98- `crates/tangled-git` - Git operation helpers
99
100## Configuration
101
102The CLI stores session credentials securely in your system keyring and configuration in:
103- Linux: `~/.config/tangled/config.toml`
104- macOS: `~/Library/Application Support/tangled/config.toml`
105- Windows: `%APPDATA%\tangled\config.toml`
106
107### Environment Variables
108
109- `TANGLED_PDS_BASE` - Override the PDS base URL (default: `https://bsky.social`)
110- `TANGLED_API_BASE` - Override the Tangled API base URL (default: `https://tngl.sh`)
111- `TANGLED_SPINDLE_BASE` - Override the Spindle base URL (default: `wss://spindle.tangled.sh`)
112
113## Examples
114
115### Working with Issues
116
117```sh
118# Create an issue
119tangled issue create --repo myrepo --title "Bug: Fix login" --body "Description here"
120
121# List issues
122tangled issue list --repo myrepo
123
124# Comment on an issue
125tangled issue comment <issue-id> --body "I'll fix this"
126```
127
128### Working with Pull Requests
129
130```sh
131# Create a PR from a branch
132tangled pr create --repo myrepo --base main --head feature-branch --title "Add new feature"
133
134# Review a PR
135tangled pr review <pr-id> --approve --comment "LGTM!"
136
137# Merge a PR
138tangled pr merge <pr-id>
139```
140
141### CI/CD with Spindle
142
143```sh
144# Enable spindle for your repo
145tangled spindle config --repo myrepo --enable
146
147# List pipeline runs
148tangled spindle list --repo myrepo
149
150# Stream logs from a workflow
151tangled spindle logs knot:rkey:workflow-name --follow
152
153# Manage secrets
154tangled spindle secret add --repo myrepo --key API_KEY --value "secret-value"
155tangled spindle secret list --repo myrepo
156```
157
158## Development
159
160Run tests:
161```sh
162cargo test
163```
164
165Run with debug output:
166```sh
167cargo run -p tangled-cli -- --verbose <command>
168```
169
170Format code:
171```sh
172cargo fmt
173```
174
175Check for issues:
176```sh
177cargo clippy
178```
179
180## Contributing
181
182Contributions are welcome! Please feel free to submit issues or pull requests.
183
184## License
185
186MIT OR Apache-2.0