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 docs with ATProto details
+83
-15
+71
-5
API_ANALYSIS.md
+71
-5
API_ANALYSIS.md
···
16
16
17
17
### Git SSH Key Management
18
18
19
+
#### Lexicon Details
20
+
21
+
**`sh.tangled.publicKey` Record Schema** (from `core/lexicons/publicKey.json`):
22
+
```json
23
+
{
24
+
"lexicon": 1,
25
+
"id": "sh.tangled.publicKey",
26
+
"key": "tid",
27
+
"record": {
28
+
"required": ["key", "name", "createdAt"],
29
+
"properties": {
30
+
"key": {
31
+
"type": "string",
32
+
"maxLength": 4096,
33
+
"description": "public key contents"
34
+
},
35
+
"name": {
36
+
"type": "string",
37
+
"description": "human-readable name for this key"
38
+
},
39
+
"createdAt": {
40
+
"type": "string",
41
+
"format": "datetime",
42
+
"description": "key upload timestamp"
43
+
}
44
+
}
45
+
}
46
+
}
47
+
```
48
+
49
+
**`sh.tangled.knot.listKeys` Query** (from `core/lexicons/knot/listKeys.json`):
50
+
- Query endpoint for listing public keys stored on the knot server
51
+
- Returns: Array of `{ did, key, createdAt }`
52
+
- Supports pagination with `limit` and `cursor` parameters
53
+
54
+
#### Implementation Approach
55
+
19
56
* **`tangled ssh-key add <public-key-path>`**:
20
-
* **Feasible (using generic ATProto record creation).** The `core/lexicons/publicKey.json` defines the `sh.tangled.publicKey` record type. To add a user's global SSH public key, the CLI would use the generic ATProto `com.atproto.repo.createRecord` procedure. The `collection` parameter would be set to `sh.tangled.publicKey`, and the public key content (`key`) and a human-readable name (`name`) would be provided as the record data.
57
+
* **Feasible (using generic ATProto record creation).**
58
+
* Uses `AtpAgent.com.atproto.repo.createRecord()` with:
59
+
- `collection: "sh.tangled.publicKey"`
60
+
- `record: { key, name, createdAt }`
61
+
* The record will be stored on the user's PDS (Personal Data Server)
62
+
* The CLI reads the public key file, validates the format, and creates the record
63
+
21
64
* **`tangled ssh-key verify`**:
22
65
* **Feasible.** This command can be implemented by:
23
-
1. Executing `ssh -T git@tangled.org` to capture the authenticated user's DID from the server response.
24
-
2. Using the `sh.tangled.knot.listKeys` query (defined in `core/lexicons/knot/listKeys.json`) to fetch a list of public keys known to the knot server. This query returns objects that include the `did` associated with each key.
25
-
3. Comparing the DID obtained from the SSH output with the DIDs returned by `listKeys` to confirm the key's association.
26
-
4. Resolving the DID to a human-readable Bluesky handle using the standard AT Protocol `com.atproto.identity.resolveHandle` procedure (part of `@atproto/api`).
66
+
1. Executing `ssh -T git@tangled.org` to capture the authenticated user's DID from the server response
67
+
2. Parsing the DID from the SSH output
68
+
3. Resolving the DID to a human-readable Bluesky handle using `com.atproto.identity.resolveHandle`
69
+
* Note: The `sh.tangled.knot.listKeys` query is available but may require knot server access
70
+
71
+
#### TypeScript/JavaScript Tools
72
+
73
+
- **`@atproto/api`**: Main SDK for AT Protocol operations
74
+
- `AtpAgent` class handles authentication and API calls
75
+
- Built-in methods for `com.atproto.repo.createRecord`, `getRecord`, `listRecords`
76
+
77
+
- **`@atproto/lexicon`**: Schema validation library
78
+
- `Lexicons` class for loading and validating custom schemas
79
+
- Provides `assertValidRecord()` for validating record data against lexicons
80
+
81
+
- **Direct Record Creation**: No code generation needed
82
+
```typescript
83
+
await agent.com.atproto.repo.createRecord({
84
+
repo: agent.session.did,
85
+
collection: 'sh.tangled.publicKey',
86
+
record: {
87
+
key: publicKeyContent,
88
+
name: keyName,
89
+
createdAt: new Date().toISOString()
90
+
}
91
+
})
92
+
```
27
93
28
94
### Repository Management
29
95
+12
-10
README.md
+12
-10
README.md
···
35
35
36
36
## Tech Stack (TypeScript)
37
37
38
-
| Component | Library | Purpose |
39
-
| :---------------- | :-------------------- | :------------------------------------------------------------ |
40
-
| **Framework** | **commander** | Routing (tangled repo create). |
41
-
| **API Client** | **@atproto/api** | Official XRPC client & session management. |
42
-
| **Git Context** | **git-url-parse** | **New:** Parses remote URLs to extract the Tangled DID/NSID. |
43
-
| **Git Ops** | **simple-git** | Wraps local git operations safely. |
44
-
| **Validation** | **zod** | Validates inputs & generates schemas for LLMs. |
45
-
| **Interactivity** | **@inquirer/prompts** | Modern prompts for humans. |
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. |
38
+
| Component | Library | Purpose |
39
+
| :---------------- | :---------------------- | :--------------------------------------------------------------------------------------------- |
40
+
| **Framework** | **commander** | CLI routing and command parsing (e.g., `tangled repo create`). |
41
+
| **API Client** | **@atproto/api** | Official AT Protocol XRPC client, session management, and record operations. |
42
+
| **Lexicon Tools** | **@atproto/lexicon** | Schema validation for custom Tangled.org lexicons (e.g., `sh.tangled.publicKey`). |
43
+
| **Git Context** | **git-url-parse** | Parses remote URLs to extract the Tangled DID/NSID from `.git/config`. |
44
+
| **Git Ops** | **simple-git** | Wraps local git operations safely. |
45
+
| **Validation** | **zod** | Input validation and schema generation for LLMs. |
46
+
| **Interactivity** | **@inquirer/prompts** | Modern, user-friendly prompts for interactive flows. |
47
+
| **Formatting** | **cli-table3** | Pretty tables for "Human Mode" output (following gh CLI patterns). |
48
+
| **OS Keychain** | **@napi-rs/keyring** | Cross-platform secure storage for AT Protocol session tokens (macOS, Windows, Linux). |
49
+
| **TypeScript** | **tsx** | Fast TypeScript execution for development and testing. |
48
50
49
51
## Agent Integration (The "LLM Friendly" Layer)
50
52