@braid-cloud/cli 0.1.8 → 0.1.10

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 (4) hide show
  1. package/README.md +48 -34
  2. package/dist/index.js +1093 -104
  3. package/dist/index.js.map +1 -1
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -14,7 +14,7 @@ Also configures braid MCP in supported tools by writing the right config entry f
14
14
  # Install
15
15
  npm install -g @braid-cloud/cli
16
16
 
17
- # Authenticate
17
+ # Sign in (interactive, beginner-safe)
18
18
  braid auth
19
19
 
20
20
  # Install skills from a profile
@@ -23,8 +23,8 @@ braid install --profile coding-standards
23
23
  # View installed skills
24
24
  braid list
25
25
 
26
- # Configure MCP for a tool
27
- braid mcp --tool claude-code --no-auth -y
26
+ # Advanced: configure MCP for a specific tool (skips confirmation prompts)
27
+ braid mcp --tool claude-code --yes
28
28
  ```
29
29
 
30
30
  ## Commands
@@ -35,7 +35,7 @@ Authenticate with your braid account. Runs interactive login by default.
35
35
 
36
36
  During login, the CLI now walks you through:
37
37
 
38
- 1. Signing in with your API key
38
+ 1. Signing in with your Personal Access Token (PAT)
39
39
  2. Launching an interactive scope wizard
40
40
  3. Selecting organization/profile/projects with name + ID context
41
41
 
@@ -51,35 +51,37 @@ After a successful login, `braid auth` offers to run `braid scope --file user` s
51
51
 
52
52
  The `login` subcommand accepts:
53
53
 
54
- | Flag | Description |
55
- | -------------------- | --------------------------------------------- |
56
- | `-s, --server <url>` | braid server URL (for review apps, local dev) |
54
+ | Flag | Description |
55
+ | -------------------- | -------------------------------------------------- |
56
+ | `-s, --server <url>` | braid base server URL (for review apps, local dev) |
57
+
58
+ Advanced (non-interactive) auth input can be provided with `BRAID_API_KEY` (PAT value).
57
59
 
58
60
  ### `braid install`
59
61
 
60
62
  Install skills from profiles or projects. Alias: `braid add`
61
63
 
62
64
  ```bash
63
- # From a profile
65
+ # Beginner-safe default
64
66
  braid install --profile coding-standards
65
67
 
66
- # From projects
68
+ # Advanced: from explicit projects
67
69
  braid install --org-projects proj_frontend,proj_shared
68
70
  braid install --personal-projects proj_experiments
69
71
 
70
72
  # Combine sources
71
73
  braid install -p coding-standards --org-projects proj_frontend
72
74
 
73
- # Target specific agents
75
+ # Advanced: target specific agents
74
76
  braid install -p coding-standards --agents claude-code,cursor
75
77
 
76
- # Install globally (not project-local)
78
+ # Advanced: install globally (not project-local)
77
79
  braid install -p coding-standards --global
78
80
 
79
- # Preview without installing
81
+ # Advanced: preview without installing
80
82
  braid install -p coding-standards --list
81
83
 
82
- # Skip confirmation
84
+ # Advanced: skip confirmation
83
85
  braid install -p coding-standards --yes
84
86
  ```
85
87
 
@@ -98,7 +100,7 @@ braid install -p coding-standards --yes
98
100
  | `-g, --global` | Install to global directories |
99
101
  | `-l, --list` | Preview skills without installing |
100
102
  | `-y, --yes` | Skip confirmation prompts |
101
- | `-s, --server <url>` | Override server URL |
103
+ | `-s, --server <url>` | Override base server URL |
102
104
 
103
105
  At least one source (`--profile`, `--org-projects`, or `--personal-projects`) is required. The CLI auto-detects installed agents unless `--agents` is specified.
104
106
 
@@ -171,28 +173,31 @@ Configure braid MCP entries in tool-specific MCP config files.
171
173
  - Optional token embedding and custom MCP URL overrides
172
174
 
173
175
  ```bash
174
- braid mcp # Interactive MCP setup
176
+ braid mcp # Beginner-safe interactive setup
175
177
  braid mcp --tool claude-code # Configure a specific tool
178
+
179
+ # Advanced flags
176
180
  braid mcp --tool cursor --global # Write global config
177
181
  braid mcp --tool claude-code --token br_xxx
178
- braid mcp --tool claude-code --server https://custom.braid.cloud
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
179
184
  braid mcp --status # Show configured tools
180
185
  braid mcp --remove --tool claude-code # Remove braid MCP entry
181
186
  ```
182
187
 
183
188
  **Options:**
184
189
 
185
- | Flag | Description |
186
- | -------------------- | ----------------------------------------- |
187
- | `-t, --tool <name>` | Tool to configure |
188
- | `-g, --global` | Use global config instead of project |
189
- | `--token <token>` | Embed `BRAID_TOKEN` in MCP entry env |
190
- | `--no-auth` | Skip token prompt / embedding |
191
- | `--scope` | Run interactive scope wizard during setup |
192
- | `--remove` | Remove braid MCP entry |
193
- | `--status` | List tools currently configured for MCP |
194
- | `-y, --yes` | Skip confirmation prompts |
195
- | `-s, --server <url>` | Set `BRAID_MCP_URL` in MCP entry env |
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`) |
196
201
 
197
202
  ## Configuration
198
203
 
@@ -200,11 +205,13 @@ braid mcp --remove --tool claude-code # Remove braid MCP entry
200
205
 
201
206
  The CLI finds your token in this order:
202
207
 
203
- 1. `BRAID_API_KEY` environment variable
204
- 2. `braid.user.json` (searches up from current directory)
205
- 3. `braid.json` (searches up from current directory)
208
+ 1. `BRAID_API_KEY` environment variable (CLI auth context)
209
+ 2. `token` in `braid.user.json` (searches up from current directory)
210
+ 3. `token` in `braid.json` (searches up from current directory)
206
211
  4. `~/.config/braid/config.json` global config
207
212
 
213
+ Note: MCP runtime uses `BRAID_TOKEN` (not `BRAID_API_KEY`).
214
+
208
215
  ### Project Configuration
209
216
 
210
217
  For teams, use two config files in your project root:
@@ -230,7 +237,7 @@ For teams, use two config files in your project root:
230
237
  ```
231
238
 
232
239
  This lets teams share configuration while each developer uses their own token.
233
- `braid auth` can create/update this file for you through its onboarding wizard.
240
+ Use `braid scope --file user` to create/update this file. `braid auth` can launch the scope wizard after sign-in.
234
241
 
235
242
  ### All Config Options
236
243
 
@@ -238,7 +245,7 @@ Both `braid.json` and `braid.user.json` support these fields. Values in `braid.u
238
245
 
239
246
  | Field | Type | Description |
240
247
  | ------------------- | -------- | ----------------------------------------------------- |
241
- | `token` | string | Personal Access Token |
248
+ | `token` | string | Personal Access Token (PAT) |
242
249
  | `serverUrl` | string | Server URL (default: `https://braid.cloud`) |
243
250
  | `skills.serverUrl` | string | Skills endpoint override (alternative to `serverUrl`) |
244
251
  | `org` | string | Default organization ID |
@@ -254,12 +261,19 @@ Both `braid.json` and `braid.user.json` support these fields. Values in `braid.u
254
261
 
255
262
  ### Environment Variables
256
263
 
264
+ CLI context:
265
+
257
266
  | Variable | Description |
258
267
  | ------------------------- | ------------------------------------------------------ |
259
- | `BRAID_API_KEY` | API key (highest priority) |
268
+ | `BRAID_API_KEY` | PAT for CLI auth (highest priority) |
260
269
  | `BRAID_SERVER_URL` | Server URL override |
261
270
  | `BRAID_SKILLS_SERVER_URL` | Skills endpoint URL (falls back to `BRAID_SERVER_URL`) |
262
271
 
272
+ MCP runtime context (when configuring tool MCP entries):
273
+
274
+ - `BRAID_TOKEN` is the PAT consumed by MCP server requests.
275
+ - `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`).
276
+
263
277
  ## Supported Agents
264
278
 
265
279
  Skills are installed to agent-specific directories. The CLI auto-detects installed agents.
@@ -379,7 +393,7 @@ Installed skills are tracked in `.braidskills-metadata.json` for update detectio
379
393
 
380
394
  - **[@braid-cloud/mcp](https://www.npmjs.com/package/@braid-cloud/mcp)** - Real-time MCP integration (no local files)
381
395
  - **[braid Website](https://braid.cloud)** - Learn more about braid and sign up for an account.
382
- -
396
+
383
397
  ## License
384
398
 
385
399
  Proprietary - all rights reserved.