WIP: A simple cli for daily tangled use cases and AI integration. This is for my personal use right now, but happy if others get mileage from it! :)
Update README.md with outstanding issue findings.
+47
-8
+46
-7
README.md
+46
-7
README.md
···
44
44
| **Validation** | **zod** | Validates inputs & generates schemas for LLMs. |
45
45
| **Interactivity** | **@inquirer/prompts** | Modern prompts for humans. |
46
46
| **Formatting** | **cli-table3** | **New:** For gh-style pretty tables in Human Mode. |
47
+
| **OS Keychain** | **keytar** | **New:** To securely store session tokens in the OS keychain. |
47
48
48
49
## 5. Agent Integration (The "LLM Friendly" Layer)
49
50
···
112
113
`tangled issue create "<title>" [--body "<body>" | --body-file <file> | -F -]`
113
114
- Creates a new issue in the current repository with the given title and optional body, which can be provided via flag, file, or stdin.
114
115
115
-
## 7. Task Management
116
+
## 8. Design Decisions & Outstanding Issues
116
117
117
-
We're bootstrapping task tracking with TODO.md, but will migrate all tasks into Tangled issues and dog food the product as soon as we have basic issue creation and listing working.
118
+
This section documents key design decisions and tracks outstanding architectural questions.
118
119
119
-
## 8. Outstanding Issues
120
+
### 1. (Resolved) SSH Key Management (`gh` Compatibility)
120
121
121
-
1. Can we allow auth through the web browser, rather than just CLI username/password? This would be more secure and user-friendly.
122
-
2. The GitHub CLI manages the private keys allowing you to authenticate git operations. Can we do something similar, or will users have to manage SSH keys separately? Currently, I store my SSH keys in 1Password which signs requests for me. It would be great if tangled CLI could detect this and use it seamlessly, itentifying the user by the signed ssh key.
123
-
3. How should we handle storing the AT Proto session securely? The GitHub CLI uses the OS keychain. We could do something similar. How does this work across different platforms (Windows, macOS, Linux)? We want to avoid storing sensitive tokens in plaintext files.
124
-
4. How are settings resolved (e.g. local config file, home folder, command-line flags)? We should define a clear precedence order.
122
+
* **Original Question:** How does `gh` manage SSH keys, and can we follow that pattern?
123
+
* **Resolution:** Analysis shows that `gh` does *not* manage private keys. It facilitates uploading the user's *public* key to their GitHub account. The local SSH agent handles the private key.
124
+
* **Our Approach:** The `tangled ssh-key add` command follows this exact pattern. It provides a user-friendly way to upload a public key to `tangled.org`. This resolves the core of this issue, as it is compatible with external key managers like 1Password's SSH agent.
125
+
126
+
### 2. (Decided) Secure Session Storage
127
+
128
+
* **Original Question:** How should we securely store the AT Proto session token?
129
+
* **Resolution:** Storing sensitive tokens in plaintext files is not secure.
130
+
* **Our Approach:** The CLI will use the operating system's native keychain for secure storage (e.g., macOS Keychain, Windows Credential Manager, or Secret Service on Linux). A library like `keytar` will be used to abstract the platform differences.
131
+
132
+
### 3. (Decided) Configuration Resolution Order
133
+
134
+
* **Original Question:** How should settings be resolved from different sources?
135
+
* **Resolution:** A clear precedence order is necessary.
136
+
* **Our Approach:** The CLI will resolve settings in the following order of precedence (highest first):
137
+
1. Command-line flags (e.g., `--repo-did ...`)
138
+
2. Environment variables (e.g., `TANGLED_REPO_DID=...`)
139
+
3. Project-specific config file (e.g., `.tangled/config.yml` in the current directory)
140
+
4. Global user config file (e.g., `~/.config/tangled/config.yml`)
141
+
142
+
### 4. (Outstanding) Web-based Authentication Flow
143
+
144
+
* **Original Question:** Can we allow auth through a web browser?
145
+
* **Status:** This remains an outstanding issue. The standard AT Protocol authentication flow is based on user handles and app passwords, not a third-party OAuth2 flow like GitHub CLI uses.
146
+
* **Path Forward:** Implementing a web-based auth flow would require custom development on the `tangled.org` service itself to securely generate and transmit a session token back to the CLI. This is out of scope for the initial version of the CLI.
147
+
148
+
## 9. Future Expansion Opportunities
149
+
150
+
The analysis of the `tangled.org` API revealed a rich set of features that are not yet part of the initial CLI plan but represent significant opportunities for future expansion. These include:
151
+
152
+
* **Pull Requests:** A full suite of commands for creating, viewing, listing, merging, and commenting on pull requests.
153
+
* **CI/CD Pipelines:** Commands to view pipeline status and manage CI/CD jobs.
154
+
* **Repository Secrets:** A dedicated command set for managing CI/CD secrets within a repository (`tangled repo secret ...`).
155
+
* **Advanced Git Operations:** Commands to interact with the commit log, diffs, branches, and tags directly via the API, augmenting local `git` commands.
156
+
* **Social & Feed Interactions:** Commands for starring repositories, reacting to feed items, and managing the user's social graph (following/unfollowing).
157
+
* **Label Management:** Commands to create, apply, and remove labels from issues and pull requests.
158
+
* **Collaboration:** Commands to manage repository collaborators.
159
+
* **Fork Management:** Commands for forking repositories and managing the sync status of forks.
160
+
161
+
## 10. Task Management
162
+
163
+
We're bootstrapping task tracking with TODO.md, but will migrate all tasks into Tangled issues and dog food the product as soon as we have basic issue creation and listing working.
+1
-1
TODO.md
+1
-1
TODO.md
···
11
11
12
12
## 2. Authentication (Auth)
13
13
- [ ] Implement `tangled auth login` command.
14
-
- [ ] Explore methods for secure AT Proto session storage (OS keychain consideration across platforms: Windows, macOS, Linux).
14
+
- [ ] Implement session storage using an OS keychain library (e.g., `keytar`) for secure, cross-platform token management.
15
15
- [ ] Integrate `@atproto/api` for XRPC client and session management.
16
16
- [ ] Investigate web browser authentication flow.
17
17
- [ ] Implement `tangled auth logout` command.