@braid-cloud/cli 0.1.9 → 0.1.12

package/README.md

@@ -14,7 +14,7 @@ Also configures braid MCP in supported tools by writing the right config entry f
 # Install
 npm install -g @braid-cloud/cli
 
-# Authenticate
+# Sign in (interactive, beginner-safe)
 braid auth
 
 # Install skills from a profile
@@ -23,8 +23,8 @@ braid install --profile coding-standards
 # View installed skills
 braid list
 
-# Configure MCP for a tool
-braid mcp --tool claude-code --no-auth -y
+# Advanced: configure MCP for a specific tool (skips confirmation prompts)
+braid mcp --tool claude-code --yes
 ```
 
 ## Commands
@@ -35,7 +35,7 @@ Authenticate with your braid account. Runs interactive login by default.
 
 During login, the CLI now walks you through:
 
-1. Signing in with your API key
+1. Signing in with your Personal Access Token (PAT)
 2. Launching an interactive scope wizard
 3. Selecting organization/profile/projects with name + ID context
 
@@ -51,35 +51,37 @@ After a successful login, `braid auth` offers to run `braid scope --file user` s
 
 The `login` subcommand accepts:
 
-| Flag                 | Description                                   |
-| -------------------- | --------------------------------------------- |
-| `-s, --server <url>` | braid server URL (for review apps, local dev) |
+| Flag                 | Description                                        |
+| -------------------- | -------------------------------------------------- |
+| `-s, --server <url>` | braid base server URL (for review apps, local dev) |
+
+Advanced (non-interactive) auth input can be provided with `BRAID_API_KEY` (PAT value).
 
 ### `braid install`
 
 Install skills from profiles or projects. Alias: `braid add`
 
 ```bash
-# From a profile
+# Beginner-safe default
 braid install --profile coding-standards
 
-# From projects
+# Advanced: from explicit projects
 braid install --org-projects proj_frontend,proj_shared
 braid install --personal-projects proj_experiments
 
 # Combine sources
 braid install -p coding-standards --org-projects proj_frontend
 
-# Target specific agents
+# Advanced: target specific agents
 braid install -p coding-standards --agents claude-code,cursor
 
-# Install globally (not project-local)
+# Advanced: install globally (not project-local)
 braid install -p coding-standards --global
 
-# Preview without installing
+# Advanced: preview without installing
 braid install -p coding-standards --list
 
-# Skip confirmation
+# Advanced: skip confirmation
 braid install -p coding-standards --yes
 ```
 
@@ -98,7 +100,7 @@ braid install -p coding-standards --yes
 | `-g, --global`              | Install to global directories               |
 | `-l, --list`                | Preview skills without installing           |
 | `-y, --yes`                 | Skip confirmation prompts                   |
-| `-s, --server <url>`        | Override server URL                         |
+| `-s, --server <url>`        | Override base server URL                    |
 
 At least one source (`--profile`, `--org-projects`, or `--personal-projects`) is required. The CLI auto-detects installed agents unless `--agents` is specified.
 
@@ -171,28 +173,62 @@ Configure braid MCP entries in tool-specific MCP config files.
 - Optional token embedding and custom MCP URL overrides
 
 ```bash
-braid mcp                                 # Interactive MCP setup
+braid mcp                                 # Beginner-safe interactive setup
 braid mcp --tool claude-code              # Configure a specific tool
+
+# Advanced flags
 braid mcp --tool cursor --global          # Write global config
 braid mcp --tool claude-code --token br_xxx
-braid mcp --tool claude-code --server https://custom.braid.cloud
+braid mcp --tool claude-code --server https://custom.braid.cloud/api/mcp
+braid mcp --tool claude-code --no-auth    # Use existing BRAID_TOKEN from tool env
 braid mcp --status                        # Show configured tools
 braid mcp --remove --tool claude-code     # Remove braid MCP entry
 ```
 
 **Options:**
 
-| Flag                 | Description                               |
-| -------------------- | ----------------------------------------- |
-| `-t, --tool <name>`  | Tool to configure                         |
-| `-g, --global`       | Use global config instead of project      |
-| `--token <token>`    | Embed `BRAID_TOKEN` in MCP entry env      |
-| `--no-auth`          | Skip token prompt / embedding             |
-| `--scope`            | Run interactive scope wizard during setup |
-| `--remove`           | Remove braid MCP entry                    |
-| `--status`           | List tools currently configured for MCP   |
-| `-y, --yes`          | Skip confirmation prompts                 |
-| `-s, --server <url>` | Set `BRAID_MCP_URL` in MCP entry env      |
+| Flag                 | Description                                                                            |
+| -------------------- | -------------------------------------------------------------------------------------- |
+| `-t, --tool <name>`  | Tool to configure                                                                      |
+| `-g, --global`       | Use global config instead of project                                                   |
+| `--token <token>`    | Embed `BRAID_TOKEN` in MCP entry env                                                   |
+| `--no-auth`          | Skip token prompt / embedding                                                          |
+| `--scope`            | Run interactive scope wizard during setup                                              |
+| `--remove`           | Remove braid MCP entry                                                                 |
+| `--status`           | List tools currently configured for MCP                                                |
+| `-y, --yes`          | Skip confirmation prompts                                                              |
+| `-s, --server <url>` | Set `BRAID_MCP_URL` (full MCP endpoint URL, e.g. `https://custom.braid.cloud/api/mcp`) |
+
+### `braid workflows`
+
+Manage local workflow execution lifecycle state (CLI-first contract used by MCP passthrough tools).
+
+```bash
+# List control flows available to your token context
+braid workflows list --json
+
+# Start execution tracking for a session
+braid workflows start --session-id cli_sess_123 --flow-id flow_123 --current-step-label input --json
+
+# Update progress
+braid workflows progress --execution-id exec_123 --current-node-id node_2 --current-step-label prompt --json
+
+# Read active run
+braid workflows active --session-id cli_sess_123 --json
+
+# Mark terminal states
+braid workflows complete --execution-id exec_123 --json
+braid workflows fail --execution-id exec_123 --error-message "Node timeout" --json
+braid workflows cancel --execution-id exec_123 --json
+```
+
+Notes:
+
+- These commands track execution state for local/MCP workflows (not cloud execution runtime).
+- `--metadata` accepts JSON for `start` and `progress`.
+- `active` can be used to recover context after long model turns.
+
+Reference: `docs/workflows/local-execution-session-state.md`.
 
 ## Configuration
 
@@ -200,11 +236,13 @@ braid mcp --remove --tool claude-code     # Remove braid MCP entry
 
 The CLI finds your token in this order:
 
-1. `BRAID_API_KEY` environment variable
-2. `braid.user.json` (searches up from current directory)
-3. `braid.json` (searches up from current directory)
+1. `BRAID_API_KEY` environment variable (CLI auth context)
+2. `token` in `braid.user.json` (searches up from current directory)
+3. `token` in `braid.json` (searches up from current directory)
 4. `~/.config/braid/config.json` global config
 
+Note: MCP runtime uses `BRAID_TOKEN` (not `BRAID_API_KEY`).
+
 ### Project Configuration
 
 For teams, use two config files in your project root:
@@ -230,7 +268,7 @@ For teams, use two config files in your project root:
 ```
 
 This lets teams share configuration while each developer uses their own token.
-`braid auth` can create/update this file for you through its onboarding wizard.
+Use `braid scope --file user` to create/update this file. `braid auth` can launch the scope wizard after sign-in.
 
 ### All Config Options
 
@@ -238,7 +276,7 @@ Both `braid.json` and `braid.user.json` support these fields. Values in `braid.u
 
 | Field               | Type     | Description                                           |
 | ------------------- | -------- | ----------------------------------------------------- |
-| `token`             | string   | Personal Access Token                                 |
+| `token`             | string   | Personal Access Token (PAT)                           |
 | `serverUrl`         | string   | Server URL (default: `https://braid.cloud`)           |
 | `skills.serverUrl`  | string   | Skills endpoint override (alternative to `serverUrl`) |
 | `org`               | string   | Default organization ID                               |
@@ -254,12 +292,19 @@ Both `braid.json` and `braid.user.json` support these fields. Values in `braid.u
 
 ### Environment Variables
 
+CLI context:
+
 | Variable                  | Description                                            |
 | ------------------------- | ------------------------------------------------------ |
-| `BRAID_API_KEY`           | API key (highest priority)                             |
+| `BRAID_API_KEY`           | PAT for CLI auth (highest priority)                    |
 | `BRAID_SERVER_URL`        | Server URL override                                    |
 | `BRAID_SKILLS_SERVER_URL` | Skills endpoint URL (falls back to `BRAID_SERVER_URL`) |
 
+MCP runtime context (when configuring tool MCP entries):
+
+- `BRAID_TOKEN` is the PAT consumed by MCP server requests.
+- `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`).
+
 ## Supported Agents
 
 Skills are installed to agent-specific directories. The CLI auto-detects installed agents.
@@ -379,7 +424,7 @@ Installed skills are tracked in `.braidskills-metadata.json` for update detectio
 
 - **[@braid-cloud/mcp](https://www.npmjs.com/package/@braid-cloud/mcp)** - Real-time MCP integration (no local files)
 - **[braid Website](https://braid.cloud)** - Learn more about braid and sign up for an account.
-- 
+
 ## License
 
 Proprietary - all rights reserved.