@braid-cloud/cli 0.1.0 → 0.1.2

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 +178 -176
  3. package/dist/index.js +496 -179
  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) prompts 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 prompts 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,251 +26,260 @@ 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. Runs interactive login by default.
82
30
 
83
31
  ```bash
84
- echo "braid.user.json" >> .gitignore
32
+ braid auth # Interactive login (alias for `braid auth login`)
33
+ braid auth status # Check auth status
34
+ braid auth logout # Remove stored credentials
85
35
  ```
86
36
 
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
37
+ The `login` subcommand accepts:
92
38
 
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
- }
101
- ```
39
+ | Flag | Description |
40
+ | -------------------- | --------------------------------------------- |
41
+ | `-s, --server <url>` | Braid server URL (for review apps, local dev) |
102
42
 
103
43
  ### `braid install`
104
44
 
105
- Install skills from a braid profile or project.
45
+ Install skills from profiles or projects. Alias: `braid add`
106
46
 
107
47
  ```bash
108
- # Install from a profile
48
+ # From a profile
109
49
  braid install --profile coding-standards
110
- braid install -p coding-standards
111
50
 
112
- # Install from a project
113
- braid install --project frontend --org acme-corp
51
+ # From projects
52
+ braid install --org-projects proj_frontend,proj_shared
53
+ braid install --personal-projects proj_experiments
54
+
55
+ # Combine sources
56
+ braid install -p coding-standards --org-projects proj_frontend
114
57
 
115
- # Specify agents manually
116
- braid install -p coding-standards --agents claude-code,opencode
58
+ # Target specific agents
59
+ braid install -p coding-standards --agents claude-code,cursor
117
60
 
118
- # Install to global directories (not project-local)
61
+ # Install globally (not project-local)
119
62
  braid install -p coding-standards --global
120
63
 
121
- # Preview skills without installing
64
+ # Preview without installing
122
65
  braid install -p coding-standards --list
123
66
 
124
- # Skip confirmation prompts
67
+ # Skip confirmation
125
68
  braid install -p coding-standards --yes
126
-
127
- # Use a different server
128
- braid install -p coding-standards --server https://localhost:3000
129
69
  ```
130
70
 
131
71
  **Options:**
132
72
 
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 |
73
+ | Flag | Description |
74
+ | --------------------------- | ------------------------------------------- |
75
+ | `-p, --profile <name>` | Profile to install from |
76
+ | `--org-projects <ids>` | Organization project IDs (comma-sep) |
77
+ | `--personal-projects <ids>` | Personal project IDs (comma-sep) |
78
+ | `--include-user-globals` | Include user's global prompts (default: on) |
79
+ | `--no-include-user-globals` | Exclude user's global prompts |
80
+ | `--include-org-globals` | Include org's global prompts (default: on) |
81
+ | `--no-include-org-globals` | Exclude org's global prompts |
82
+ | `-a, --agents <list>` | Target specific agents (comma-sep) |
83
+ | `-g, --global` | Install to global directories |
84
+ | `-l, --list` | Preview skills without installing |
85
+ | `-y, --yes` | Skip confirmation prompts |
86
+ | `-s, --server <url>` | Override server URL |
87
+
88
+ At least one source (`--profile`, `--org-projects`, or `--personal-projects`) is required. The CLI auto-detects installed agents unless `--agents` is specified.
143
89
 
144
90
  ### `braid list`
145
91
 
146
- List installed skills across all detected agents.
92
+ List installed skills. Alias: `braid ls`
147
93
 
148
94
  ```bash
149
- # List project-local skills
150
- braid list
151
-
152
- # List global skills only
153
- braid list --global
95
+ braid list # Project-local skills
96
+ braid list --global # Global skills only
154
97
  ```
155
98
 
156
99
  ### `braid update`
157
100
 
158
- Update installed skills to the latest version from braid.
101
+ Update installed skills to latest versions. Alias: `braid up`
159
102
 
160
103
  ```bash
161
- # Update all installed skills
162
- braid update
104
+ braid update # Update all
105
+ braid update --global # Global only
106
+ braid update --yes # Skip confirmation
107
+ ```
163
108
 
164
- # Update global skills only
165
- braid update --global
109
+ ### `braid remove`
166
110
 
167
- # Skip confirmation
168
- braid update --yes
111
+ Remove installed skills. Alias: `braid rm`
112
+
113
+ ```bash
114
+ braid remove # Interactive selection
115
+ braid remove --skill my-skill # Remove specific skill
116
+ braid remove --all # Remove all skills
117
+ braid remove --global # Global only
169
118
  ```
170
119
 
171
- ## Supported Agents
120
+ ## Configuration
172
121
 
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/` |
122
+ ### Token Resolution
195
123
 
196
- ## Configuration
124
+ The CLI finds your token in this order:
197
125
 
198
- ### Configuration Files
126
+ 1. `BRAID_API_KEY` environment variable
127
+ 2. `braid.user.json` (searches up from current directory)
128
+ 3. `braid.json` (searches up from current directory)
129
+ 4. `~/.config/braid/config.json` global config
199
130
 
200
- The CLI uses two configuration files in your project:
131
+ ### Project Configuration
201
132
 
202
- | File | Purpose | Git |
203
- | ----------------- | ------------------------------------------ | ------ |
204
- | `braid.json` | Shared team config (project, org, profile) | Commit |
205
- | `braid.user.json` | Personal token and overrides | Ignore |
133
+ For teams, use two config files in your project root:
206
134
 
207
- ### `braid.json` Format (shared)
135
+ **braid.json** (commit to git):
208
136
 
209
137
  ```json
210
138
  {
211
- "project": "my-project",
212
- "org": "my-org",
213
- "serverUrl": "https://braid.cloud"
139
+ "$schema": "https://braid.cloud/schemas/config.json",
140
+ "profile": "coding-standards",
141
+ "orgProjects": ["proj_frontend", "proj_shared"],
142
+ "agents": ["claude-code", "cursor"]
214
143
  }
215
144
  ```
216
145
 
217
- ### `braid.user.json` Format (personal)
146
+ **braid.user.json** (add to .gitignore):
218
147
 
219
148
  ```json
220
149
  {
221
- "token": "br_your_personal_access_token"
150
+ "token": "br_your_personal_token"
222
151
  }
223
152
  ```
224
153
 
225
- You can override any `braid.json` setting in `braid.user.json`.
154
+ This lets teams share configuration while each developer uses their own token.
226
155
 
227
- ### Resolution Order
156
+ ### All Config Options
228
157
 
229
- Settings are resolved in this order (later sources override earlier):
158
+ Both `braid.json` and `braid.user.json` support these fields. Values in `braid.user.json` override `braid.json`.
230
159
 
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.)
160
+ | Field | Type | Description |
161
+ | ------------------- | -------- | --------------------------------------------- |
162
+ | `token` | string | Personal Access Token |
163
+ | `serverUrl` | string | Server URL (default: `https://braid.cloud`) |
164
+ | `profile` | string | Default profile |
165
+ | `orgProjects` | string[] | Organization project IDs |
166
+ | `personalProjects` | string[] | Personal project IDs |
167
+ | `includeUserGlobal` | boolean | Include user's global prompts (default: true) |
168
+ | `includeOrgGlobal` | boolean | Include org's global prompts (default: true) |
169
+ | `agents` | string[] | Target agents |
235
170
 
236
171
  ### Environment Variables
237
172
 
238
- | Variable | Description |
239
- | ------------------ | ------------------------------------------- |
240
- | `BRAID_API_KEY` | API key (highest priority) |
241
- | `BRAID_SERVER_URL` | Server URL (default: `https://braid.cloud`) |
173
+ | Variable | Description |
174
+ | ------------------------- | ------------------------------------------------------ |
175
+ | `BRAID_API_KEY` | API key (highest priority) |
176
+ | `BRAID_SERVER_URL` | Server URL override |
177
+ | `BRAID_SKILLS_SERVER_URL` | Skills endpoint URL (falls back to `BRAID_SERVER_URL`) |
242
178
 
243
- ## SKILL.md Format
179
+ ## Supported Agents
244
180
 
245
- Skills are installed as directories containing a `SKILL.md` file with YAML frontmatter:
181
+ Skills are installed to agent-specific directories. The CLI auto-detects installed agents.
182
+
183
+ | Agent | Project Path | Global Path |
184
+ | -------------- | ------------------- | ----------------------------- |
185
+ | Claude Code | `.claude/skills/` | `~/.claude/skills/` |
186
+ | Cursor | `.cursor/skills/` | `~/.cursor/skills/` |
187
+ | GitHub Copilot | `.github/skills/` | `~/.copilot/skills/` |
188
+ | OpenCode | `.opencode/skills/` | `~/.config/opencode/skills/` |
189
+ | Windsurf | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
190
+ | Cline | `.cline/skills/` | `~/.cline/skills/` |
191
+ | Continue | `.continue/skills/` | `~/.continue/skills/` |
192
+ | Gemini CLI | `.gemini/skills/` | `~/.gemini/skills/` |
193
+ | Goose | `.goose/skills/` | `~/.config/goose/skills/` |
194
+ | Roo Code | `.roo/skills/` | `~/.roo/skills/` |
195
+
196
+ <details>
197
+ <summary>All 30+ supported agents</summary>
198
+
199
+ | Agent | Project Path | Global Path |
200
+ | ------------- | ---------------------- | -------------------------------------- |
201
+ | Amp | `.agents/skills/` | `~/.config/agents/skills/` |
202
+ | Antigravity | `.agent/skills/` | `~/.gemini/antigravity/global_skills/` |
203
+ | CodeBuddy | `.codebuddy/skills/` | `~/.codebuddy/skills/` |
204
+ | Codex | `.codex/skills/` | `~/.codex/skills/` |
205
+ | Command Code | `.commandcode/skills/` | `~/.commandcode/skills/` |
206
+ | Crush | `.crush/skills/` | `~/.config/crush/skills/` |
207
+ | Droid | `.factory/skills/` | `~/.factory/skills/` |
208
+ | Junie | `.junie/skills/` | `~/.junie/skills/` |
209
+ | Kilo Code | `.kilocode/skills/` | `~/.kilocode/skills/` |
210
+ | Kimi Code CLI | `.agents/skills/` | `~/.config/agents/skills/` |
211
+ | Kiro CLI | `.kiro/skills/` | `~/.kiro/skills/` |
212
+ | Kode | `.kode/skills/` | `~/.kode/skills/` |
213
+ | MCPJam | `.mcpjam/skills/` | `~/.mcpjam/skills/` |
214
+ | Moltbot | `skills/` | `~/.moltbot/skills/` |
215
+ | Mux | `.mux/skills/` | `~/.mux/skills/` |
216
+ | Neovate | `.neovate/skills/` | `~/.neovate/skills/` |
217
+ | OpenHands | `.openhands/skills/` | `~/.openhands/skills/` |
218
+ | Pi | `.pi/skills/` | `~/.pi/agent/skills/` |
219
+ | Pochi | `.pochi/skills/` | `~/.pochi/skills/` |
220
+ | Qoder | `.qoder/skills/` | `~/.qoder/skills/` |
221
+ | Qwen Code | `.qwen/skills/` | `~/.qwen/skills/` |
222
+ | Trae | `.trae/skills/` | `~/.trae/skills/` |
223
+ | Zed | -- | -- |
224
+ | Zencoder | `.zencoder/skills/` | `~/.zencoder/skills/` |
225
+
226
+ </details>
227
+
228
+ ### Prompts Support
229
+
230
+ Some agents also receive prompts (always-on standards) in addition to skills. The format depends on the agent:
231
+
232
+ | Agent | Format | Location |
233
+ | -------------- | -------------- | --------------------------------- |
234
+ | Claude Code | Markdown files | `.claude/rules/` |
235
+ | Cursor | MDC files | `.cursor/rules/` |
236
+ | Roo Code | Markdown files | `.roo/rules/` |
237
+ | Zed | Markdown files | `.zed/rules/` |
238
+ | GitHub Copilot | Appended | `.github/copilot-instructions.md` |
239
+ | Cline | Appended | `.clinerules` |
240
+ | Windsurf | Appended | `.windsurfrules` |
241
+
242
+ ## Skill Format
243
+
244
+ Installed skills are directories with a `SKILL.md` file:
246
245
 
247
246
  ```
248
247
  my-skill/
249
248
  ├── SKILL.md
250
- └── references/
251
- ├── style-guide.md
252
- └── diagram.png
249
+ ├── references/
250
+ │ ├── style-guide.md
251
+ │ └── diagram.png
252
+ └── scripts/
253
+ ├── setup.sh
254
+ └── deploy.py
253
255
  ```
254
256
 
257
+ Scripts in `scripts/` with recognized extensions (`.sh`, `.bash`, `.py`, `.js`, `.mjs`, `.rb`) are automatically made executable.
258
+
255
259
  **SKILL.md example:**
256
260
 
257
261
  ```markdown
258
262
  ---
259
263
  name: code-quality
260
- description: Modern TypeScript/React development standards
264
+ description: Modern TypeScript/React standards
261
265
  category: coding-standards
262
- tags:
263
- - typescript
264
- - react
265
- - code-style
266
+ tags: [typescript, react]
266
267
  ---
267
268
 
268
269
  # Code Quality
269
270
 
270
- Instructions for the agent to follow...
271
+ Instructions for the agent...
271
272
  ```
272
273
 
273
- ## Metadata Tracking
274
+ ## Metadata
275
+
276
+ Installed skills are tracked in `.braidskills-metadata.json` for update detection. This file is written to each agent's skills directory.
274
277
 
275
- Installed skills are tracked in `.braid-skills-metadata.json` within each agent's skills directory. This enables:
278
+ ## Related
276
279
 
277
- - Knowing which skills came from braid
278
- - Tracking the source profile/project
279
- - Detecting when updates are available
280
+ - **[@braid-cloud/mcp](https://www.npmjs.com/package/@braid-cloud/mcp)** - Real-time MCP integration (no local files)
281
+ - **[Braid Documentation](https://docs.braid.cloud)** - Full platform docs
280
282
 
281
283
  ## License
282
284
 
283
- MIT
285
+ Proprietary - see [LICENSE](./LICENSE)