@braid-cloud/cli 0.1.0 → 0.1.1

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 (5) hide show
  1. package/LICENSE +18 -0
  2. package/README.md +174 -177
  3. package/dist/index.js +493 -176
  4. package/dist/index.js.map +1 -1
  5. package/package.json +64 -57
package/LICENSE ADDED
@@ -0,0 +1,18 @@
1
+ Braid Proprietary License
2
+ Copyright (c) 2026 braid ai labs, LLC All rights reserved.
3
+
4
+ Permission is hereby granted to use this software for its intended purpose
5
+ (installing and managing Braid rules in your development environment).
6
+
7
+ You MAY NOT:
8
+ - Copy, reproduce, or redistribute the software or its source code
9
+ - Modify, adapt, or create derivative works
10
+ - Reverse engineer, decompile, or disassemble the software
11
+ - Use the source code to build competing products or services
12
+ - Sublicense, sell, resell, or transfer the software
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. IN NO EVENT
15
+ SHALL BRAID AI LABS, LLC BE LIABLE FOR ANY DAMAGES ARISING FROM USE OF THIS
16
+ SOFTWARE.
17
+
18
+ For licensing inquiries: legal@braid.cloud
package/README.md CHANGED
@@ -1,31 +1,24 @@
1
1
  # @braid-cloud/cli
2
2
 
3
- Install [braid](https://braid.cloud) rules as agent skills to your local development environment.
3
+ Install [Braid](https://braid.cloud) rules and skills as local files for your AI coding agents.
4
4
 
5
- ## Overview
5
+ ## What It Does
6
6
 
7
- `@braid-cloud/cli` is a CLI that syncs your braid rules to local AI coding agents like Claude Code, OpenCode, Cursor, and 15+ others. Once installed, skills work offline and are automatically picked up by your agents.
7
+ Syncs your Braid rules and skills to local files that AI coding agents automatically pick up. Works with 30+ agents including Claude Code, Cursor, GitHub Copilot, and more. Once installed, skills work offline.
8
8
 
9
- ## Installation
9
+ ## Quick Start
10
10
 
11
11
  ```bash
12
- # Run directly with npx
13
- npx @braid-cloud/cli --help
14
-
15
- # Or install globally
12
+ # Install
16
13
  npm install -g @braid-cloud/cli
17
- ```
18
14
 
19
- ## Quick Start
20
-
21
- ```bash
22
- # 1. Authenticate with your braid API key
15
+ # Authenticate
23
16
  braid auth
24
17
 
25
- # 2. Install skills from a profile
18
+ # Install skills from a profile
26
19
  braid install --profile coding-standards
27
20
 
28
- # 3. View installed skills
21
+ # View installed skills
29
22
  braid list
30
23
  ```
31
24
 
@@ -33,250 +26,254 @@ braid list
33
26
 
34
27
  ### `braid auth`
35
28
 
36
- Configure your braid API key for authentication.
37
-
38
- ```bash
39
- # Interactive login
40
- braid auth
41
-
42
- # Check auth status
43
- braid auth status
44
-
45
- # Logout (remove stored key)
46
- braid auth logout
47
-
48
- # Use a different server (review apps, local dev)
49
- braid auth --server https://my-branch.braid.cloud
50
- ```
51
-
52
- #### Token Configuration
53
-
54
- The CLI looks for your API token in the following order:
55
-
56
- 1. **`BRAID_API_KEY` environment variable** - Best for CI/CD
57
- 2. **`braid.user.json` in your project** - Recommended for teams
58
- 3. **`~/.config/braid/config.json`** - Global fallback
59
-
60
- **Recommended: Project-level configuration**
61
-
62
- Create two files in your project root:
63
-
64
- **`braid.json`** (committed to git, shared with team):
65
-
66
- ```json
67
- {
68
- "project": "my-project",
69
- "org": "my-org"
70
- }
71
- ```
72
-
73
- **`braid.user.json`** (gitignored, personal token):
74
-
75
- ```json
76
- {
77
- "token": "br_your_personal_access_token"
78
- }
79
- ```
80
-
81
- Add `braid.user.json` to your `.gitignore`:
29
+ Authenticate with your Braid account.
82
30
 
83
31
  ```bash
84
- echo "braid.user.json" >> .gitignore
85
- ```
86
-
87
- This approach allows:
88
-
89
- - Team members share the same project/org configuration
90
- - Each developer uses their own personal access token
91
- - No credentials are committed to git
92
-
93
- You can override any setting in `braid.user.json`:
94
-
95
- ```json
96
- {
97
- "token": "br_your_token",
98
- "serverUrl": "https://my-branch.braid.cloud",
99
- "profile": "my-custom-profile"
100
- }
32
+ braid auth # Interactive login
33
+ braid auth status # Check auth status
34
+ braid auth logout # Remove stored credentials
35
+ braid auth --server https://custom.braid.cloud # Use custom server
101
36
  ```
102
37
 
103
38
  ### `braid install`
104
39
 
105
- Install skills from a braid profile or project.
40
+ Install skills from profiles or projects. Alias: `braid add`
106
41
 
107
42
  ```bash
108
- # Install from a profile
43
+ # From a profile
109
44
  braid install --profile coding-standards
110
- braid install -p coding-standards
111
45
 
112
- # Install from a project
113
- braid install --project frontend --org acme-corp
46
+ # From projects
47
+ braid install --org-projects proj_frontend,proj_shared
48
+ braid install --personal-projects proj_experiments
49
+
50
+ # Combine sources
51
+ braid install -p coding-standards --org-projects proj_frontend
114
52
 
115
- # Specify agents manually
116
- braid install -p coding-standards --agents claude-code,opencode
53
+ # Target specific agents
54
+ braid install -p coding-standards --agents claude-code,cursor
117
55
 
118
- # Install to global directories (not project-local)
56
+ # Install globally (not project-local)
119
57
  braid install -p coding-standards --global
120
58
 
121
- # Preview skills without installing
59
+ # Preview without installing
122
60
  braid install -p coding-standards --list
123
61
 
124
- # Skip confirmation prompts
62
+ # Skip confirmation
125
63
  braid install -p coding-standards --yes
126
-
127
- # Use a different server
128
- braid install -p coding-standards --server https://localhost:3000
129
64
  ```
130
65
 
131
66
  **Options:**
132
67
 
133
- | Flag | Description |
134
- | ---------------------- | ----------------------------------- |
135
- | `-p, --profile <name>` | Profile name to install from |
136
- | `--project <name>` | Project name (requires `--org`) |
137
- | `-o, --org <slug>` | Organization slug |
138
- | `-a, --agents <list>` | Comma-separated agent list |
139
- | `-g, --global` | Install to global agent directories |
140
- | `-y, --yes` | Skip confirmation prompts |
141
- | `-l, --list` | Preview skills without installing |
142
- | `-s, --server <url>` | braid server URL |
68
+ | Flag | Description |
69
+ | ------------------------------ | ------------------------------------------ |
70
+ | `-p, --profile <name>` | Profile to install from |
71
+ | `--org-projects <ids>` | Organization project IDs (comma-sep) |
72
+ | `--personal-projects <ids>` | Personal project IDs (comma-sep) |
73
+ | `--include-user-globals` | Include user's global rules (default: on) |
74
+ | `--no-include-user-globals` | Exclude user's global rules |
75
+ | `--include-org-globals` | Include org's global rules (default: on) |
76
+ | `--no-include-org-globals` | Exclude org's global rules |
77
+ | `-a, --agents <list>` | Target specific agents (comma-sep) |
78
+ | `-g, --global` | Install to global directories |
79
+ | `-l, --list` | Preview skills without installing |
80
+ | `-y, --yes` | Skip confirmation prompts |
81
+ | `-s, --server <url>` | Override server URL |
82
+
83
+ At least one source (`--profile`, `--org-projects`, or `--personal-projects`) is required. The CLI auto-detects installed agents unless `--agents` is specified.
143
84
 
144
85
  ### `braid list`
145
86
 
146
- List installed skills across all detected agents.
87
+ List installed skills. Alias: `braid ls`
147
88
 
148
89
  ```bash
149
- # List project-local skills
150
- braid list
151
-
152
- # List global skills only
153
- braid list --global
90
+ braid list # Project-local skills
91
+ braid list --global # Global skills only
154
92
  ```
155
93
 
156
94
  ### `braid update`
157
95
 
158
- Update installed skills to the latest version from braid.
96
+ Update installed skills to latest versions. Alias: `braid up`
159
97
 
160
98
  ```bash
161
- # Update all installed skills
162
- braid update
99
+ braid update # Update all
100
+ braid update --global # Global only
101
+ braid update --yes # Skip confirmation
102
+ ```
163
103
 
164
- # Update global skills only
165
- braid update --global
104
+ ### `braid remove`
166
105
 
167
- # Skip confirmation
168
- braid update --yes
106
+ Remove installed skills. Alias: `braid rm`
107
+
108
+ ```bash
109
+ braid remove # Interactive selection
110
+ braid remove --skill my-skill # Remove specific skill
111
+ braid remove --all # Remove all skills
112
+ braid remove --global # Global only
169
113
  ```
170
114
 
171
- ## Supported Agents
115
+ ## Configuration
172
116
 
173
- `@braid-cloud/cli` automatically detects and supports these AI coding agents:
174
-
175
- | Agent | Project Path | Global Path |
176
- | -------------- | ------------------------- | ---------------------------------- |
177
- | Claude Code | `.claude/skills/` | `~/.claude/skills/` |
178
- | OpenCode | `.opencode/skills/` | `~/.config/opencode/skills/` |
179
- | Cursor | `.cursor/skills/` | `~/.cursor/skills/` |
180
- | Windsurf | `.windsurf/skills/` | `~/.windsurf/skills/` |
181
- | Cline | `.cline/skills/` | `~/.cline/skills/` |
182
- | Roo Code | `.roo/skills/` | `~/.roo/skills/` |
183
- | Augment | `.augment/skills/` | `~/.augment/skills/` |
184
- | Aider | `.aider/skills/` | `~/.aider/skills/` |
185
- | GitHub Copilot | `.github/copilot/skills/` | `~/.config/github-copilot/skills/` |
186
- | Continue | `.continue/skills/` | `~/.continue/skills/` |
187
- | Void | `.void/skills/` | `~/.void/skills/` |
188
- | Codex | `.codex/skills/` | `~/.codex/skills/` |
189
- | Amp | `.amp/skills/` | `~/.amp/skills/` |
190
- | Trae | `.trae/skills/` | `~/.trae/skills/` |
191
- | Kilo Code | `.kilo/skills/` | `~/.kilo/skills/` |
192
- | Gemini CLI | `.gemini/skills/` | `~/.gemini/skills/` |
193
- | Witsy | `.witsy/skills/` | `~/.witsy/skills/` |
194
- | Zed | `.zed/skills/` | `~/.config/zed/skills/` |
117
+ ### Token Resolution
195
118
 
196
- ## Configuration
119
+ The CLI finds your token in this order:
197
120
 
198
- ### Configuration Files
121
+ 1. `BRAID_API_KEY` environment variable
122
+ 2. `braid.user.json` (searches up from current directory)
123
+ 3. `braid.json` (searches up from current directory)
124
+ 4. `~/.config/braid/config.json` global config
199
125
 
200
- The CLI uses two configuration files in your project:
126
+ ### Project Configuration
201
127
 
202
- | File | Purpose | Git |
203
- | ----------------- | ------------------------------------------ | ------ |
204
- | `braid.json` | Shared team config (project, org, profile) | Commit |
205
- | `braid.user.json` | Personal token and overrides | Ignore |
128
+ For teams, use two config files in your project root:
206
129
 
207
- ### `braid.json` Format (shared)
130
+ **braid.json** (commit to git):
208
131
 
209
132
  ```json
210
133
  {
211
- "project": "my-project",
212
- "org": "my-org",
213
- "serverUrl": "https://braid.cloud"
134
+ "$schema": "https://braid.cloud/schemas/config.json",
135
+ "profile": "coding-standards",
136
+ "orgProjects": ["proj_frontend", "proj_shared"],
137
+ "agents": ["claude-code", "cursor"]
214
138
  }
215
139
  ```
216
140
 
217
- ### `braid.user.json` Format (personal)
141
+ **braid.user.json** (add to .gitignore):
218
142
 
219
143
  ```json
220
144
  {
221
- "token": "br_your_personal_access_token"
145
+ "token": "br_your_personal_token"
222
146
  }
223
147
  ```
224
148
 
225
- You can override any `braid.json` setting in `braid.user.json`.
149
+ This lets teams share configuration while each developer uses their own token.
226
150
 
227
- ### Resolution Order
151
+ ### All Config Options
228
152
 
229
- Settings are resolved in this order (later sources override earlier):
153
+ Both `braid.json` and `braid.user.json` support these fields. Values in `braid.user.json` override `braid.json`.
230
154
 
231
- 1. `braid.json` (shared team config)
232
- 2. `braid.user.json` (personal overrides)
233
- 3. Environment variables (`BRAID_API_KEY`, `BRAID_SERVER_URL`)
234
- 4. CLI flags (`--server`, `--profile`, etc.)
155
+ | Field | Type | Description |
156
+ | ------------------- | -------- | ---------------------------------------- |
157
+ | `token` | string | Personal Access Token |
158
+ | `serverUrl` | string | Server URL (default: `https://braid.cloud`) |
159
+ | `profile` | string | Default profile |
160
+ | `orgProjects` | string[] | Organization project IDs |
161
+ | `personalProjects` | string[] | Personal project IDs |
162
+ | `includeUserGlobal` | boolean | Include user's global rules (default: true) |
163
+ | `includeOrgGlobal` | boolean | Include org's global rules (default: true) |
164
+ | `agents` | string[] | Target agents |
235
165
 
236
166
  ### Environment Variables
237
167
 
238
- | Variable | Description |
239
- | ------------------ | ------------------------------------------- |
240
- | `BRAID_API_KEY` | API key (highest priority) |
241
- | `BRAID_SERVER_URL` | Server URL (default: `https://braid.cloud`) |
168
+ | Variable | Description |
169
+ | ------------------------- | ----------------------------------------------- |
170
+ | `BRAID_API_KEY` | API key (highest priority) |
171
+ | `BRAID_SERVER_URL` | Server URL override |
172
+ | `BRAID_SKILLS_SERVER_URL` | Override for skills endpoint (falls back to `BRAID_SERVER_URL`) |
242
173
 
243
- ## SKILL.md Format
174
+ ## Supported Agents
244
175
 
245
- Skills are installed as directories containing a `SKILL.md` file with YAML frontmatter:
176
+ Skills are installed to agent-specific directories. The CLI auto-detects installed agents.
177
+
178
+ | Agent | Project Path | Global Path |
179
+ | --------------- | ---------------------- | -------------------------------------- |
180
+ | Claude Code | `.claude/skills/` | `~/.claude/skills/` |
181
+ | Cursor | `.cursor/skills/` | `~/.cursor/skills/` |
182
+ | GitHub Copilot | `.github/skills/` | `~/.copilot/skills/` |
183
+ | OpenCode | `.opencode/skills/` | `~/.config/opencode/skills/` |
184
+ | Windsurf | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
185
+ | Cline | `.cline/skills/` | `~/.cline/skills/` |
186
+ | Continue | `.continue/skills/` | `~/.continue/skills/` |
187
+ | Gemini CLI | `.gemini/skills/` | `~/.gemini/skills/` |
188
+ | Goose | `.goose/skills/` | `~/.config/goose/skills/` |
189
+ | Roo Code | `.roo/skills/` | `~/.roo/skills/` |
190
+
191
+ <details>
192
+ <summary>All 30+ supported agents</summary>
193
+
194
+ | Agent | Project Path | Global Path |
195
+ | --------------- | ---------------------- | -------------------------------------- |
196
+ | Amp | `.agents/skills/` | `~/.config/agents/skills/` |
197
+ | Antigravity | `.agent/skills/` | `~/.gemini/antigravity/global_skills/` |
198
+ | CodeBuddy | `.codebuddy/skills/` | `~/.codebuddy/skills/` |
199
+ | Codex | `.codex/skills/` | `~/.codex/skills/` |
200
+ | Command Code | `.commandcode/skills/` | `~/.commandcode/skills/` |
201
+ | Crush | `.crush/skills/` | `~/.config/crush/skills/` |
202
+ | Droid | `.factory/skills/` | `~/.factory/skills/` |
203
+ | Junie | `.junie/skills/` | `~/.junie/skills/` |
204
+ | Kilo Code | `.kilocode/skills/` | `~/.kilocode/skills/` |
205
+ | Kimi Code CLI | `.agents/skills/` | `~/.config/agents/skills/` |
206
+ | Kiro CLI | `.kiro/skills/` | `~/.kiro/skills/` |
207
+ | Kode | `.kode/skills/` | `~/.kode/skills/` |
208
+ | MCPJam | `.mcpjam/skills/` | `~/.mcpjam/skills/` |
209
+ | Moltbot | `skills/` | `~/.moltbot/skills/` |
210
+ | Mux | `.mux/skills/` | `~/.mux/skills/` |
211
+ | Neovate | `.neovate/skills/` | `~/.neovate/skills/` |
212
+ | OpenHands | `.openhands/skills/` | `~/.openhands/skills/` |
213
+ | Pi | `.pi/skills/` | `~/.pi/agent/skills/` |
214
+ | Pochi | `.pochi/skills/` | `~/.pochi/skills/` |
215
+ | Qoder | `.qoder/skills/` | `~/.qoder/skills/` |
216
+ | Qwen Code | `.qwen/skills/` | `~/.qwen/skills/` |
217
+ | Trae | `.trae/skills/` | `~/.trae/skills/` |
218
+ | Zed | — | — |
219
+ | Zencoder | `.zencoder/skills/` | `~/.zencoder/skills/` |
220
+
221
+ </details>
222
+
223
+ ### Rules Support
224
+
225
+ Some agents also receive rules (always-on standards) in addition to skills. The format depends on the agent:
226
+
227
+ | Agent | Format | Location |
228
+ | -------------- | -------------- | --------------------------------- |
229
+ | Claude Code | Markdown files | `.claude/rules/` |
230
+ | Cursor | MDC files | `.cursor/rules/` |
231
+ | Roo Code | Markdown files | `.roo/rules/` |
232
+ | Zed | Markdown files | `.zed/rules/` |
233
+ | GitHub Copilot | Appended | `.github/copilot-instructions.md` |
234
+ | Cline | Appended | `.clinerules` |
235
+ | Windsurf | Appended | `.windsurfrules` |
236
+
237
+ ## Skill Format
238
+
239
+ Installed skills are directories with a `SKILL.md` file:
246
240
 
247
241
  ```
248
242
  my-skill/
249
243
  ├── SKILL.md
250
- └── references/
251
- ├── style-guide.md
252
- └── diagram.png
244
+ ├── references/
245
+ │ ├── style-guide.md
246
+ │ └── diagram.png
247
+ └── scripts/
248
+ ├── setup.sh
249
+ └── deploy.py
253
250
  ```
254
251
 
252
+ Scripts in `scripts/` with recognized extensions (`.sh`, `.bash`, `.py`, `.js`, `.mjs`, `.rb`) are automatically made executable.
253
+
255
254
  **SKILL.md example:**
256
255
 
257
256
  ```markdown
258
257
  ---
259
258
  name: code-quality
260
- description: Modern TypeScript/React development standards
259
+ description: Modern TypeScript/React standards
261
260
  category: coding-standards
262
- tags:
263
- - typescript
264
- - react
265
- - code-style
261
+ tags: [typescript, react]
266
262
  ---
267
263
 
268
264
  # Code Quality
269
265
 
270
- Instructions for the agent to follow...
266
+ Instructions for the agent...
271
267
  ```
272
268
 
273
- ## Metadata Tracking
269
+ ## Metadata
270
+
271
+ Installed skills are tracked in `.braidskills-metadata.json` for update detection. This file is written to each agent's skills directory.
274
272
 
275
- Installed skills are tracked in `.braid-skills-metadata.json` within each agent's skills directory. This enables:
273
+ ## Related
276
274
 
277
- - Knowing which skills came from braid
278
- - Tracking the source profile/project
279
- - Detecting when updates are available
275
+ - **[@braid-cloud/mcp](https://www.npmjs.com/package/@braid-cloud/mcp)** - Real-time MCP integration (no local files)
276
+ - **[Braid Documentation](https://docs.braid.cloud)** - Full platform docs
280
277
 
281
278
  ## License
282
279