oeiuwq.com
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### Using with Nix
64
65This repo provides a runnable flake:
66
67```sh
68nix run git+https://tangled.org/vitorpy.com/tangled-cli
69```
70
71#### On Tangled CI Pipelines
72
73Register a [Spindle dependency](https://tangled.org/tangled.org/core/blob/master/docs/spindle/pipeline.md#dependencies) on your workflow:
74
75```yaml
76dependencies:
77 git+https://tangled.org/victorpy.com/tangled-cli:
78 - tangled-cli
79```
80
81### Install from AUR (Arch Linux)
82
83Community-maintained package:
84
85```sh
86yay -S tangled-cli-git
87```
88
89## Quick Start
90
911. **Login to Tangled**:
92 ```sh
93 tangled auth login --handle your.handle.bsky.social
94 ```
95
962. **List your repositories**:
97 ```sh
98 tangled repo list
99 ```
100
1013. **Create a new repository**:
102 ```sh
103 tangled repo create myproject --description "My cool project"
104 ```
105
1064. **Clone a repository**:
107 ```sh
108 tangled repo clone username/reponame
109 ```
110
111## Workspace Structure
112
113- `crates/tangled-cli` - CLI binary with clap-based argument parsing
114- `crates/tangled-config` - Configuration and session management (keyring-backed)
115- `crates/tangled-api` - XRPC client wrapper for AT Protocol and Tangled APIs
116- `crates/tangled-git` - Git operation helpers
117
118## Configuration
119
120The CLI stores session credentials securely in your system keyring and configuration in:
121- Linux: `~/.config/tangled/config.toml`
122- macOS: `~/Library/Application Support/tangled/config.toml`
123- Windows: `%APPDATA%\tangled\config.toml`
124
125### Environment Variables
126
127- `TANGLED_PDS_BASE` - Override the PDS base URL (default: `https://bsky.social`)
128- `TANGLED_API_BASE` - Override the Tangled API base URL (default: `https://tngl.sh`)
129- `TANGLED_SPINDLE_BASE` - Override the Spindle base URL (default: `wss://spindle.tangled.sh`)
130
131## Examples
132
133### Working with Issues
134
135```sh
136# Create an issue
137tangled issue create --repo myrepo --title "Bug: Fix login" --body "Description here"
138
139# List issues
140tangled issue list --repo myrepo
141
142# Comment on an issue
143tangled issue comment <issue-id> --body "I'll fix this"
144```
145
146### Working with Pull Requests
147
148```sh
149# Create a PR from a branch
150tangled pr create --repo myrepo --base main --head feature-branch --title "Add new feature"
151
152# Review a PR
153tangled pr review <pr-id> --approve --comment "LGTM!"
154
155# Merge a PR
156tangled pr merge <pr-id>
157```
158
159### CI/CD with Spindle
160
161```sh
162# Enable spindle for your repo
163tangled spindle config --repo myrepo --enable
164
165# List pipeline runs
166tangled spindle list --repo myrepo
167
168# Stream logs from a workflow
169tangled spindle logs knot:rkey:workflow-name --follow
170
171# Manage secrets
172tangled spindle secret add --repo myrepo --key API_KEY --value "secret-value"
173tangled spindle secret list --repo myrepo
174```
175
176## Development
177
178Run tests:
179```sh
180cargo test
181```
182
183Run with debug output:
184```sh
185cargo run -p tangled-cli -- --verbose <command>
186```
187
188Format code:
189```sh
190cargo fmt
191```
192
193Check for issues:
194```sh
195cargo clippy
196```
197
198## Contributing
199
200Contributions are welcome! Please feel free to submit issues or pull requests.
201
202## License
203
204MIT OR Apache-2.0