@braid-cloud/cli 0.1.13 → 0.1.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +293 -313
  2. package/dist/index.js +5190 -1550
  3. package/dist/index.js.map +1 -1
  4. package/dist/manage-ui/assets/index-BX8fP_pz.css +2 -0
  5. package/dist/manage-ui/assets/index-BrO1UpTp.js +53 -0
  6. package/dist/manage-ui/index.html +37 -0
  7. package/package.json +20 -8
package/README.md CHANGED
@@ -1,253 +1,282 @@
1
1
  # @braid-cloud/cli
2
2
 
3
- Install [braid](https://braid.cloud) prompts as local files for your AI coding agents, and configure braid MCP endpoints in supported tools.
3
+ Install and manage braid prompt artifacts locally.
4
4
 
5
- ## What It Does
5
+ The CLI currently covers four jobs:
6
6
 
7
- Syncs your braid prompts to local files that AI coding agents automatically pick up. Works with 35+ agents including Claude Code, Cursor, GitHub Copilot, and more. Once installed, skills work offline.
7
+ - Install prompt artifacts into local coding tools
8
+ - Manage authenticated braid resources such as projects, rules, profiles, references, and sub-agents
9
+ - Install marketplace packs
10
+ - Scaffold GitHub-importable pack repos
8
11
 
9
- Also configures braid MCP in supported tools by writing the right config entry format for each interface (for example standard JSON, typed stdio entries, Zed nested command blocks, and VS Code extension-specific MCP files).
12
+ Prompt artifacts can include skills, workflows, rules, sub-agents, and marketplace hooks.
10
13
 
11
- ## Quick Start
14
+ ## Requirements
15
+
16
+ - Node.js `>=20.6`
17
+ - A supported coding tool if you want local installs to auto-detect targets
18
+
19
+ ## Install
12
20
 
13
21
  ```bash
14
- # Install
15
22
  npm install -g @braid-cloud/cli
23
+ ```
16
24
 
17
- # Sign in (interactive, beginner-safe)
25
+ ## Quick Start
26
+
27
+ ```bash
28
+ # 1. Authenticate
18
29
  braid auth
19
30
 
20
- # Install skills from a profile
21
- braid install --profile coding-standards
31
+ # 2. Save default scope to braid.user.json or braid.json
32
+ braid scope
33
+
34
+ # 3. Install from your saved scope
35
+ braid install
22
36
 
23
- # View installed skills
37
+ # 4. Inspect locally installed bundles
24
38
  braid list
39
+ ```
40
+
41
+ If you do not want to save defaults first, install directly from flags:
25
42
 
26
- # Advanced: configure MCP for a specific tool (skips confirmation prompts)
27
- braid mcp --tool claude-code --yes
43
+ ```bash
44
+ braid install --profile coding-standards
45
+ braid install --org-projects proj_frontend,proj_shared
46
+ braid install --personal-projects proj_experiments
28
47
  ```
29
48
 
30
- ## Commands
49
+ ## Install Sources
31
50
 
32
- ### `braid auth`
51
+ ### Scoped braid content
33
52
 
34
- Authenticate with your braid account. Runs interactive login by default.
53
+ Install from a saved profile or explicit project scope:
35
54
 
36
- During login, the CLI now walks you through:
55
+ ```bash
56
+ braid install --profile coding-standards
57
+ braid install --org-projects proj_frontend,proj_shared
58
+ braid install --personal-projects proj_experiments
59
+ ```
37
60
 
38
- 1. Signing in with your Personal Access Token (PAT)
39
- 2. Launching an interactive scope wizard
40
- 3. Selecting organization/profile/projects with name + ID context
61
+ ### Public versioned source
41
62
 
42
- Scope defaults are saved to `braid.user.json` so `braid install` can run without repeatedly passing context flags.
63
+ Install from a public source reference:
43
64
 
44
65
  ```bash
45
- braid auth # Interactive login (alias for `braid auth login`)
46
- braid auth status # Check auth status
47
- braid auth logout # Remove stored credentials
66
+ braid install @handle/slug
67
+ braid install @handle/slug@3
48
68
  ```
49
69
 
50
- After a successful login, `braid auth` offers to run `braid scope --file user` so you can pick your defaults from live org/project/profile data.
70
+ For public installs, the CLI can write and reuse `braid.lock` entries so later installs can use exact versions with `--locked`.
51
71
 
52
- The `login` subcommand accepts:
72
+ ```bash
73
+ braid install --locked
74
+ ```
53
75
 
54
- | Flag | Description |
55
- | -------------------- | -------------------------------------------------- |
56
- | `-s, --server <url>` | braid base server URL (for review apps, local dev) |
76
+ ### Marketplace pack
57
77
 
58
- Advanced (non-interactive) auth input can be provided with `BRAID_API_KEY` (PAT value).
78
+ Install a marketplace pack already available in your library:
59
79
 
60
- ### `braid install`
80
+ ```bash
81
+ braid marketplace library
82
+ braid marketplace install team-toolkit
83
+ ```
61
84
 
62
- Install skills from profiles or projects. Alias: `braid add`
85
+ Marketplace installs can contain skills, workflows, rules, sub-agents, and hooks. Hook installs require explicit opt-in:
63
86
 
64
87
  ```bash
65
- # Beginner-safe default
66
- braid install --profile coding-standards
67
-
68
- # Advanced: from explicit projects
69
- braid install --org-projects proj_frontend,proj_shared
70
- braid install --personal-projects proj_experiments
88
+ braid marketplace install team-toolkit --allow-hooks
89
+ ```
71
90
 
72
- # Combine sources
73
- braid install -p coding-standards --org-projects proj_frontend
91
+ ## Core Local Commands
74
92
 
75
- # Advanced: target specific agents
76
- braid install -p coding-standards --agents claude-code,cursor
93
+ | Command | What it does |
94
+ | --- | --- |
95
+ | `braid auth` | Authenticate with browser/device flow or `--token` |
96
+ | `braid auth status` | Show current auth state and resolved defaults |
97
+ | `braid auth logout` | Remove the saved token or session |
98
+ | `braid scope` | Write scoped defaults to `braid.user.json` or `braid.json` |
99
+ | `braid install` / `braid add` | Install prompt artifacts from scope or public source |
100
+ | `braid list` / `braid ls` | List locally installed skill bundles |
101
+ | `braid update` / `braid up` | Refresh locally installed non-marketplace bundles |
102
+ | `braid remove` / `braid rm` | Remove locally installed skill bundles |
103
+ | `braid manage` | Start the local prompt manager UI |
104
+ | `braid scaffold` | Scaffold a GitHub-importable pack artifact in the current directory |
105
+ | `braid rollback` | Move a public `@handle/slug` lockfile entry back to a previous version |
106
+ | `braid retract` / `braid unpin` | Remove a pinned public version from `braid.lock` |
77
107
 
78
- # Advanced: install globally (not project-local)
79
- braid install -p coding-standards --global
108
+ ## Common Usage
80
109
 
81
- # Advanced: preview without installing
82
- braid install -p coding-standards --list
110
+ ### Authentication
83
111
 
84
- # Advanced: skip confirmation
85
- braid install -p coding-standards --yes
112
+ ```bash
113
+ braid auth
114
+ braid auth login --token br_xxx
115
+ braid auth login --server http://localhost:3211
116
+ braid auth status
117
+ braid auth logout
86
118
  ```
87
119
 
88
- **Options:**
120
+ Notes:
121
+
122
+ - `braid auth` is an alias for `braid auth login`
123
+ - Browser login saves a CLI session in `~/.config/braid/config.json`
124
+ - `--no-scope` skips launching scope setup after login
89
125
 
90
- | Flag | Description |
91
- | --------------------------- | ------------------------------------------- |
92
- | `-p, --profile <name>` | Profile to install from |
93
- | `--org-projects <ids>` | Organization project IDs (comma-sep) |
94
- | `--personal-projects <ids>` | Personal project IDs (comma-sep) |
95
- | `--include-user-globals` | Include user's global prompts (default: on) |
96
- | `--no-include-user-globals` | Exclude user's global prompts |
97
- | `--include-org-globals` | Include org's global prompts (default: on) |
98
- | `--no-include-org-globals` | Exclude org's global prompts |
99
- | `-a, --agents <list>` | Target specific agents (comma-sep) |
100
- | `-g, --global` | Install to global directories |
101
- | `-l, --list` | Preview skills without installing |
102
- | `-y, --yes` | Skip confirmation prompts |
103
- | `-s, --server <url>` | Override base server URL |
126
+ ### Install
104
127
 
105
- At least one source (`--profile`, `--org-projects`, or `--personal-projects`) is required. The CLI auto-detects installed agents unless `--agents` is specified.
128
+ ```bash
129
+ braid install --profile coding-standards
130
+ braid install --profile coding-standards --agents claude-code,cursor
131
+ braid install --profile coding-standards --global
132
+ braid install --profile coding-standards --list
133
+ braid install --profile coding-standards --yes
134
+
135
+ braid install @handle/slug
136
+ braid install @handle/slug@3
137
+ braid install @handle/slug --locked
138
+ braid install --locked
139
+ ```
140
+
141
+ Important flags:
142
+
143
+ | Flag | Meaning |
144
+ | --- | --- |
145
+ | `--locked` | Reuse exact versions from `braid.lock` |
146
+ | `-p, --profile <name>` | Install from a profile |
147
+ | `--org-projects <ids>` | Install from organization projects |
148
+ | `--personal-projects <ids>` | Install from personal projects |
149
+ | `--no-include-user-globals` | Exclude personal global rules/prompts |
150
+ | `--no-include-org-globals` | Exclude organization global rules/prompts |
151
+ | `-a, --agents <list>` | Target specific coding tools |
152
+ | `-g, --global` | Install into global agent directories |
153
+ | `-l, --list` | Preview installable skills without writing files |
154
+ | `-y, --yes` | Skip interactive confirmation |
155
+ | `-s, --server <url>` | Override the braid server URL |
106
156
 
107
- ### `braid list`
157
+ When no `--agents` flag is given, the CLI auto-detects installed tools and prompts if needed.
108
158
 
109
- List installed skills. Alias: `braid ls`
159
+ ### Local inventory
110
160
 
111
161
  ```bash
112
- braid list # Project-local skills
113
- braid list --global # Global skills only
114
- ```
162
+ braid list
163
+ braid list --global
115
164
 
116
- ### `braid scope`
165
+ braid update
166
+ braid update --yes
167
+
168
+ braid remove
169
+ braid remove --skill requesting-code-review
170
+ braid remove --all --yes
171
+ ```
117
172
 
118
- Interactively choose scope and write either `braid.user.json` or `braid.json`.
173
+ ### Scope configuration
119
174
 
120
175
  ```bash
121
- braid scope # Prompt for target file + scope choices
122
- braid scope --file user # Force write to braid.user.json
123
- braid scope --file project # Force write to braid.json
124
- braid scope --server http://localhost:3211
176
+ braid scope
177
+ braid scope --file user
178
+ braid scope --file project
125
179
 
126
- # Non-interactive (script-friendly)
127
180
  braid scope --file user --organization personal --source profile --profile default
128
181
  braid scope --file project --organization organization --source manual --projects proj_a,proj_b --include-org-global
129
182
  braid scope --file user --organization personal --source manual --projects proj_a --rule-ids rule_1,rule_2
130
183
  ```
131
184
 
132
- Wizard flow:
185
+ `braid scope` supports both interactive and non-interactive setup. Manual mode can combine globals, project scopes, and rule include/exclude filters.
133
186
 
134
- 1. Choose config target (`braid.user.json` or `braid.json`)
135
- 2. Choose organization context (personal or organization)
136
- 3. Choose source (`profile` or `manual`)
137
- 4. In manual mode: choose global toggles, optional project scopes, optional rule include/exclude filters
138
- 5. Select profile/projects/rules by name (with ID hints)
139
-
140
- Manual mode supports combining global + project scopes together (not either/or).
141
- When you belong to multiple orgs, the wizard lets you pick which org's projects to browse.
142
-
143
- ### `braid update`
144
-
145
- Update installed skills to latest versions. Alias: `braid up`
187
+ ### Local manager
146
188
 
147
189
  ```bash
148
- braid update # Update all
149
- braid update --global # Global only
150
- braid update --yes # Skip confirmation
190
+ braid manage
191
+ braid manage --port 4321
192
+ braid manage --no-open
151
193
  ```
152
194
 
153
- ### `braid remove`
195
+ This starts the local manager server and opens a browser unless `--no-open` is passed.
154
196
 
155
- Remove installed skills. Alias: `braid rm`
197
+ ### Scaffold a pack repo
156
198
 
157
199
  ```bash
158
- braid remove # Interactive selection
159
- braid remove --skill my-skill # Remove specific skill
160
- braid remove --all # Remove all skills
161
- braid remove --global # Global only
200
+ braid scaffold
201
+
202
+ braid scaffold --type skill --name requesting-code-review --description "When the user wants a detailed code review"
203
+ braid scaffold --type rule --name no-biome-ignore --title "No biome-ignore"
204
+ braid scaffold --type agent --name code-reviewer --description "Reviews pull requests" --linked-skills requesting-code-review
205
+ braid scaffold --type hook --name review-trigger
206
+ braid scaffold --type workflow --name pr-review --skill-ref requesting-code-review --agent-ref code-reviewer
162
207
  ```
163
208
 
164
- ### `braid mcp`
209
+ Current scaffold targets:
165
210
 
166
- Configure braid MCP entries in tool-specific MCP config files.
211
+ - `skill` -> `skills/<name>/SKILL.md`
212
+ - `rule` -> `rules/<name>.md`
213
+ - `agent` -> `agents/<name>.md`
214
+ - `hook` -> `hooks/<name>.json`
215
+ - `workflow` -> `workflows/<name>.json`
167
216
 
168
- `braid mcp` supports:
217
+ `braid scaffold` also creates or updates `braid-pack.json`.
169
218
 
170
- - Adding/updating a braid MCP entry for a tool
171
- - Removing only the braid MCP entry while preserving other MCP servers
172
- - Status scanning across project/global MCP config locations
173
- - Optional token embedding and custom MCP URL overrides
219
+ ### Public version management
174
220
 
175
221
  ```bash
176
- braid mcp # Beginner-safe interactive setup
177
- braid mcp --tool claude-code # Configure a specific tool
178
-
179
- # Advanced flags
180
- braid mcp --tool cursor --global # Write global config
181
- braid mcp --tool claude-code --token br_xxx
182
- braid mcp --tool claude-code --server https://custom.braid.cloud/api/mcp
183
- braid mcp --tool claude-code --no-auth # Use existing BRAID_TOKEN from tool env
184
- braid mcp --status # Show configured tools
185
- braid mcp --remove --tool claude-code # Remove braid MCP entry
222
+ braid rollback @handle/slug
223
+ braid retract @handle/slug@3
186
224
  ```
187
225
 
188
- **Options:**
226
+ Notes:
189
227
 
190
- | Flag | Description |
191
- | -------------------- | -------------------------------------------------------------------------------------- |
192
- | `-t, --tool <name>` | Tool to configure |
193
- | `-g, --global` | Use global config instead of project |
194
- | `--token <token>` | Embed `BRAID_TOKEN` in MCP entry env |
195
- | `--no-auth` | Skip token prompt / embedding |
196
- | `--scope` | Run interactive scope wizard during setup |
197
- | `--remove` | Remove braid MCP entry |
198
- | `--status` | List tools currently configured for MCP |
199
- | `-y, --yes` | Skip confirmation prompts |
200
- | `-s, --server <url>` | Set `BRAID_MCP_URL` (full MCP endpoint URL, e.g. `https://custom.braid.cloud/api/mcp`) |
228
+ - `rollback` updates `braid.lock`; it does not reinstall content by itself
229
+ - after rollback, run `braid install @handle/slug --locked`
230
+ - `retract` only removes the local pin from `braid.lock`; it does not retract a published version from the server
201
231
 
202
- ### `braid workflows`
232
+ ## Remote API Commands
203
233
 
204
- Manage local workflow execution lifecycle state (CLI-first contract used by MCP passthrough tools).
234
+ These commands talk to the authenticated braid API. Most also accept `--api-key` and `--json`.
205
235
 
206
- ```bash
207
- # List control flows available to your token context
208
- braid workflows list --json
236
+ | Group | Commands |
237
+ | --- | --- |
238
+ | `projects` | `list`, `get`, `create`, `update`, `remove` |
239
+ | `rules` | `list`, `get`, `create`, `update`, `remove`, `enable`, `disable`, `move`, `duplicate`, `fork`, `sync-status`, `sync-history`, `sync-enable`, `sync-disable`, `sync-check`, `sync-now` |
240
+ | `references` | `list`, `get`, `create`, `update`, `remove`, `reorder` |
241
+ | `profiles` | `list`, `get`, `create`, `update`, `remove`, `set-default` |
242
+ | `skills` | `list` |
243
+ | `sub-agents` | `list`, `get`, `create`, `update`, `remove`, `install` |
244
+ | `marketplace` | `library`, `install` |
209
245
 
210
- # Start execution tracking for a session
211
- braid workflows start --session-id cli_sess_123 --flow-id flow_123 --current-step-label input --json
246
+ Examples:
212
247
 
213
- # Update progress
214
- braid workflows progress --execution-id exec_123 --current-node-id node_2 --current-step-label prompt --json
248
+ ```bash
249
+ braid projects list
250
+ braid projects create --name "Shared Standards"
215
251
 
216
- # Read active run
217
- braid workflows active --session-id cli_sess_123 --json
252
+ braid rules list --json
253
+ braid rules create --title "No force push" --content "Never force push shared branches"
254
+ braid rules sync-status
218
255
 
219
- # Mark terminal states
220
- braid workflows complete --execution-id exec_123 --json
221
- braid workflows fail --execution-id exec_123 --error-message "Node timeout" --json
222
- braid workflows cancel --execution-id exec_123 --json
223
- ```
256
+ braid references create --rule-id rule_123 --file ./docs/policy.md
224
257
 
225
- Notes:
258
+ braid profiles list
259
+ braid profiles create --name default --context-json '{"profile":"default"}'
226
260
 
227
- - These commands track execution state for local/MCP workflows (not cloud execution runtime).
228
- - `--metadata` accepts JSON for `start` and `progress`.
229
- - `active` can be used to recover context after long model turns.
261
+ braid sub-agents create \
262
+ --name reviewer \
263
+ --description "PR reviewer" \
264
+ --prompt "Review this change for correctness and regressions"
230
265
 
231
- Reference: `docs/workflows/local-execution-session-state.md`.
266
+ braid sub-agents install --id agent_123 --agents claude-code,opencode
267
+ ```
232
268
 
233
269
  ## Configuration
234
270
 
235
- ### Token Resolution
236
-
237
- The CLI finds your token in this order:
238
-
239
- 1. `BRAID_API_KEY` environment variable (CLI auth context)
240
- 2. `token` in `braid.user.json` (searches up from current directory)
241
- 3. `token` in `braid.json` (searches up from current directory)
242
- 4. `~/.config/braid/config.json` global config
271
+ ### Files
243
272
 
244
- Note: MCP runtime uses `BRAID_TOKEN` (not `BRAID_API_KEY`).
273
+ - `braid.user.json`: personal machine defaults, usually gitignored
274
+ - `braid.json`: shared project defaults
275
+ - `~/.config/braid/config.json`: global CLI auth/session storage
245
276
 
246
- ### Project Configuration
277
+ Typical setup:
247
278
 
248
- For teams, use two config files in your project root:
249
-
250
- **braid.json** (commit to git):
279
+ `braid.json`
251
280
 
252
281
  ```json
253
282
  {
@@ -258,172 +287,123 @@ For teams, use two config files in your project root:
258
287
  }
259
288
  ```
260
289
 
261
- **braid.user.json** (add to .gitignore):
290
+ `braid.user.json`
262
291
 
263
292
  ```json
264
293
  {
265
- "token": "br_your_personal_token",
266
294
  "profile": "coding-standards"
267
295
  }
268
296
  ```
269
297
 
270
- This lets teams share configuration while each developer uses their own token.
271
- Use `braid scope --file user` to create/update this file. `braid auth` can launch the scope wizard after sign-in.
272
-
273
- ### All Config Options
274
-
275
- Both `braid.json` and `braid.user.json` support these fields. Values in `braid.user.json` override `braid.json`.
276
-
277
- | Field | Type | Description |
278
- | ------------------- | -------- | ----------------------------------------------------- |
279
- | `token` | string | Personal Access Token (PAT) |
280
- | `serverUrl` | string | Server URL (default: `https://braid.cloud`) |
281
- | `skills.serverUrl` | string | Skills endpoint override (alternative to `serverUrl`) |
282
- | `org` | string | Default organization ID |
283
- | `profile` | string | Default profile |
284
- | `orgProjects` | string[] | Organization project IDs |
285
- | `personalProjects` | string[] | Personal project IDs |
286
- | `ruleIds` | string[] | Include only specific rule IDs |
287
- | `excludedRuleIds` | string[] | Exclude specific rule IDs |
288
- | `resolveOverlays` | boolean | Resolve overlay prompts from server |
289
- | `includeUserGlobal` | boolean | Include user's global prompts (default: true) |
290
- | `includeOrgGlobal` | boolean | Include org's global prompts (default: true) |
291
- | `agents` | string[] | Target agents |
292
-
293
- ### Environment Variables
294
-
295
- CLI context:
296
-
297
- | Variable | Description |
298
- | ------------------------- | ------------------------------------------------------ |
299
- | `BRAID_API_KEY` | PAT for CLI auth (highest priority) |
300
- | `BRAID_SERVER_URL` | Server URL override |
301
- | `BRAID_SKILLS_SERVER_URL` | Skills endpoint URL (falls back to `BRAID_SERVER_URL`) |
302
-
303
- MCP runtime context (when configuring tool MCP entries):
304
-
305
- - `BRAID_TOKEN` is the PAT consumed by MCP server requests.
306
- - `BRAID_MCP_URL` is used when no MCP server URL is set in config (use full endpoint, for example `https://app.braid.cloud/api/mcp`).
307
-
308
- ## Supported Agents
309
-
310
- Skills are installed to agent-specific directories. The CLI auto-detects installed agents.
311
-
312
- | Agent | Project Path | Global Path |
313
- | -------------- | ------------------- | ----------------------------- |
314
- | Claude Code | `.claude/skills/` | `~/.claude/skills/` |
315
- | Cursor | `.cursor/skills/` | `~/.cursor/skills/` |
316
- | GitHub Copilot | `.github/skills/` | `~/.copilot/skills/` |
317
- | OpenCode | `.opencode/skills/` | `~/.config/opencode/skills/` |
318
- | Windsurf | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
319
- | Cline | `.cline/skills/` | `~/.cline/skills/` |
320
- | Continue | `.continue/skills/` | `~/.continue/skills/` |
321
- | Gemini CLI | `.gemini/skills/` | `~/.gemini/skills/` |
322
- | Goose | `.goose/skills/` | `~/.config/goose/skills/` |
323
- | Roo Code | `.roo/skills/` | `~/.roo/skills/` |
324
-
325
- <details>
326
- <summary>All supported agents</summary>
327
-
328
- | Agent | Project Path | Global Path |
329
- | ------------- | ---------------------- | -------------------------------------- |
330
- | Amp | `.agents/skills/` | `~/.config/agents/skills/` |
331
- | Antigravity | `.agent/skills/` | `~/.gemini/antigravity/global_skills/` |
332
- | CodeBuddy | `.codebuddy/skills/` | `~/.codebuddy/skills/` |
333
- | Codex | `.codex/skills/` | `~/.codex/skills/` |
334
- | Command Code | `.commandcode/skills/` | `~/.commandcode/skills/` |
335
- | Crush | `.crush/skills/` | `~/.config/crush/skills/` |
336
- | Droid | `.factory/skills/` | `~/.factory/skills/` |
337
- | Junie | `.junie/skills/` | `~/.junie/skills/` |
338
- | Kilo Code | `.kilocode/skills/` | `~/.kilocode/skills/` |
339
- | Kimi Code CLI | `.agents/skills/` | `~/.config/agents/skills/` |
340
- | Kiro CLI | `.kiro/skills/` | `~/.kiro/skills/` |
341
- | Kode | `.kode/skills/` | `~/.kode/skills/` |
342
- | MCPJam | `.mcpjam/skills/` | `~/.mcpjam/skills/` |
343
- | Moltbot | `skills/` | `~/.moltbot/skills/` |
344
- | Mux | `.mux/skills/` | `~/.mux/skills/` |
345
- | Neovate | `.neovate/skills/` | `~/.neovate/skills/` |
346
- | OpenHands | `.openhands/skills/` | `~/.openhands/skills/` |
347
- | Pi | `.pi/skills/` | `~/.pi/agent/skills/` |
348
- | Pochi | `.pochi/skills/` | `~/.pochi/skills/` |
349
- | Qoder | `.qoder/skills/` | `~/.qoder/skills/` |
350
- | Qwen Code | `.qwen/skills/` | `~/.qwen/skills/` |
351
- | Trae | `.trae/skills/` | `~/.trae/skills/` |
352
- | Zed | -- | -- |
353
- | Zencoder | `.zencoder/skills/` | `~/.zencoder/skills/` |
354
-
355
- </details>
356
-
357
- ### Rules Support
358
-
359
- Some agents also receive rules (always-on standards) in addition to skills. The format depends on the agent:
360
-
361
- | Agent | Format | Location |
362
- | -------------- | -------------- | --------------------------------- |
363
- | Claude Code | Markdown files | `.claude/rules/` |
364
- | Cursor | MDC files | `.cursor/rules/` |
365
- | Roo Code | Markdown files | `.roo/rules/` |
366
- | Zed | Markdown files | `.zed/rules/` |
367
- | GitHub Copilot | Appended | `.github/copilot-instructions.md` |
368
- | Cline | Appended | `.clinerules` |
369
- | Windsurf | Appended | `.windsurfrules` |
370
-
371
- ### MCP Support
372
-
373
- Most supported tools now expose MCP config targets. `braid mcp` writes the braid entry to the correct root key and entry shape for each tool.
374
-
375
- Common examples:
376
-
377
- | Tool | Project Config | Global Config |
378
- | -------------- | -------------------- | ------------------------------------------------------ |
379
- | Claude Code | `.mcp.json` | — |
380
- | Cursor | `.cursor/mcp.json` | `~/.cursor/mcp.json` |
381
- | GitHub Copilot | `.vscode/mcp.json` | — |
382
- | OpenCode | `.opencode/mcp.json` | `~/.config/opencode/mcp.json` |
383
- | Cline | — | VS Code extension settings (`cline_mcp_settings.json`) |
384
- | Roo Code | — | VS Code extension settings (`mcp_settings.json`) |
385
- | Zed | — | `~/.config/zed/settings.json` |
386
-
387
- ## Skill Format
388
-
389
- Installed skills are directories with a `SKILL.md` file:
390
-
391
- ```
298
+ ### Supported config fields
299
+
300
+ `braid.user.json` and `braid.json` can contain:
301
+
302
+ | Field | Type | Description |
303
+ | --- | --- | --- |
304
+ | `$schema` | `string` | Optional schema URL |
305
+ | `serverUrl` | `string` | Base braid server URL |
306
+ | `skills.serverUrl` | `string` | Skills endpoint override |
307
+ | `org` | `string` | Default organization ID |
308
+ | `profile` | `string` | Default profile |
309
+ | `orgProjects` | `string[]` | Default organization project IDs |
310
+ | `personalProjects` | `string[]` | Default personal project IDs |
311
+ | `ruleIds` | `string[]` | Include only these rule IDs |
312
+ | `excludedRuleIds` | `string[]` | Exclude these rule IDs |
313
+ | `resolveOverlays` | `boolean` | Resolve overlay prompts from the server |
314
+ | `includeUserGlobal` | `boolean` | Include personal globals |
315
+ | `includeOrgGlobal` | `boolean` | Include organization globals |
316
+ | `agents` | `string[]` | Default target agents |
317
+
318
+ For authentication, prefer `braid auth`, `BRAID_API_KEY`, or the global config file. Do not commit tokens to `braid.json`.
319
+
320
+ ### Environment variables
321
+
322
+ | Variable | Description |
323
+ | --- | --- |
324
+ | `BRAID_API_KEY` | API key override for authenticated commands |
325
+ | `BRAID_SERVER_URL` | Global server URL override |
326
+ | `BRAID_SKILLS_SERVER_URL` | Skills endpoint override |
327
+ | `BRAID_STORE_ROOT` | Override the local bundle store root |
328
+ | `BRAID_DISABLED_ROOT` | Override the disabled bundle store root |
329
+ | `BRAID_ALLOW_UNTRUSTED_SERVER_URL` | Allow non-default/untrusted server URLs for API calls |
330
+
331
+ ### Resolution behavior
332
+
333
+ - Default server is `https://braid.cloud`
334
+ - Inside a local braid workspace, the CLI can infer a local server URL from workspace env files
335
+ - `braid.user.json` overrides `braid.json`
336
+ - environment variables override file-based settings
337
+
338
+ ## Supported Coding Tools
339
+
340
+ The CLI auto-detects supported tools from local/global config markers and installs into tool-specific paths.
341
+
342
+ Current skill-install targets include:
343
+
344
+ - Amp
345
+ - Antigravity
346
+ - Claude Code
347
+ - Cline
348
+ - CodeBuddy
349
+ - Codex
350
+ - Command Code
351
+ - Continue
352
+ - Crush
353
+ - Cursor
354
+ - Droid
355
+ - Gemini CLI
356
+ - GitHub Copilot
357
+ - Goose
358
+ - Junie
359
+ - Kilo Code
360
+ - Kimi Code CLI
361
+ - Kiro CLI
362
+ - Kode
363
+ - MCPJam
364
+ - Moltbot
365
+ - Mux
366
+ - Neovate
367
+ - OpenCode
368
+ - OpenHands
369
+ - Pi
370
+ - Pochi
371
+ - Qoder
372
+ - Qwen Code
373
+ - Roo Code
374
+ - Trae
375
+ - Windsurf
376
+ - Zencoder
377
+
378
+ Rule installs are currently supported for:
379
+
380
+ - Claude Code
381
+ - Cursor
382
+ - Roo Code
383
+ - Zed
384
+ - GitHub Copilot
385
+ - Cline
386
+ - Windsurf
387
+
388
+ Some marketplace content can also install:
389
+
390
+ - Claude Code hooks
391
+ - Claude Code and OpenCode sub-agents
392
+
393
+ ## Installed File Layout
394
+
395
+ Installed skills are written as directories that contain `SKILL.md` and any bundled supporting files:
396
+
397
+ ```text
392
398
  my-skill/
393
399
  ├── SKILL.md
394
400
  ├── references/
395
- │ ├── style-guide.md
396
- │ └── diagram.png
401
+ │ └── style-guide.md
397
402
  └── scripts/
398
- ├── setup.sh
399
- └── deploy.py
400
- ```
401
-
402
- Scripts in `scripts/` with recognized extensions (`.sh`, `.bash`, `.py`, `.js`, `.mjs`, `.rb`) are automatically made executable.
403
-
404
- **SKILL.md example:**
405
-
406
- ```markdown
407
- ---
408
- name: code-quality
409
- description: Modern TypeScript/React standards
410
- category: coding-standards
411
- tags: [typescript, react]
412
- ---
413
-
414
- # Code Quality
415
-
416
- Instructions for the agent...
403
+ └── setup.sh
417
404
  ```
418
405
 
419
- ## Metadata
420
-
421
- Installed skills are tracked in `.braidskills-metadata.json` for update detection. This file is written to each agent's skills directory.
422
-
423
- ## Related
424
-
425
- - **[@braid-cloud/mcp](https://www.npmjs.com/package/@braid-cloud/mcp)** - Real-time MCP integration (no local files)
426
- - **[braid Website](https://braid.cloud)** - Learn more about braid and sign up for an account.
406
+ Installed bundle metadata is tracked with `.braidskills-metadata.json` in each target skills directory. Marketplace hook installs also maintain `.braid-hooks-metadata.json` alongside the tool config they update.
427
407
 
428
408
  ## License
429
409