@braid-cloud/cli

Install braid prompts as local files for your AI coding agents, and configure braid MCP endpoints in supported tools.

What It Does

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.

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).

Quick Start

# Install
npm install -g @braid-cloud/cli

# Sign in (interactive, beginner-safe)
braid auth

# Install skills from a profile
braid install --profile coding-standards

# View installed skills
braid list

# Advanced: configure MCP for a specific tool (skips confirmation prompts)
braid mcp --tool claude-code --yes

Commands

braid auth

Authenticate with your braid account. Runs interactive login by default.

During login, the CLI now walks you through:

1. Signing in with your Personal Access Token (PAT)
2. Launching an interactive scope wizard
3. Selecting organization/profile/projects with name + ID context

Scope defaults are saved to braid.user.json so braid install can run without repeatedly passing context flags.

braid auth              # Interactive login (alias for `braid auth login`)
braid auth status       # Check auth status
braid auth logout       # Remove stored credentials

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.

The login subcommand accepts:

| 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

# Beginner-safe default
braid install --profile coding-standards

# 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

# Advanced: target specific agents
braid install -p coding-standards --agents claude-code,cursor

# Advanced: install globally (not project-local)
braid install -p coding-standards --global

# Advanced: preview without installing
braid install -p coding-standards --list

# Advanced: skip confirmation
braid install -p coding-standards --yes

Options:

| Flag | Description | | --------------------------- | ------------------------------------------- | | -p, --profile <name> | Profile to install from | | --org-projects <ids> | Organization project IDs (comma-sep) | | --personal-projects <ids> | Personal project IDs (comma-sep) | | --include-user-globals | Include user's global prompts (default: on) | | --no-include-user-globals | Exclude user's global prompts | | --include-org-globals | Include org's global prompts (default: on) | | --no-include-org-globals | Exclude org's global prompts | | -a, --agents <list> | Target specific agents (comma-sep) | | -g, --global | Install to global directories | | -l, --list | Preview skills without installing | | -y, --yes | Skip confirmation prompts | | -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.

braid list

List installed skills. Alias: braid ls

braid list              # Project-local skills
braid list --global     # Global skills only

braid scope

Interactively choose scope and write either braid.user.json or braid.json.

braid scope                         # Prompt for target file + scope choices
braid scope --file user             # Force write to braid.user.json
braid scope --file project          # Force write to braid.json
braid scope --server http://localhost:3211

# Non-interactive (script-friendly)
braid scope --file user --organization personal --source profile --profile default
braid scope --file project --organization organization --source manual --projects proj_a,proj_b --include-org-global
braid scope --file user --organization personal --source manual --projects proj_a --rule-ids rule_1,rule_2

Wizard flow:

1. Choose config target (braid.user.json or braid.json)
2. Choose organization context (personal or organization)
3. Choose source (profile or manual)
4. In manual mode: choose global toggles, optional project scopes, optional rule include/exclude filters
5. Select profile/projects/rules by name (with ID hints)

Manual mode supports combining global + project scopes together (not either/or). When you belong to multiple orgs, the wizard lets you pick which org's projects to browse.

braid update

Update installed skills to latest versions. Alias: braid up

braid update            # Update all
braid update --global   # Global only
braid update --yes      # Skip confirmation

braid remove

Remove installed skills. Alias: braid rm

braid remove                    # Interactive selection
braid remove --skill my-skill   # Remove specific skill
braid remove --all              # Remove all skills
braid remove --global           # Global only

braid mcp

Configure braid MCP entries in tool-specific MCP config files.

braid mcp supports:

• Adding/updating a braid MCP entry for a tool
• Removing only the braid MCP entry while preserving other MCP servers
• Status scanning across project/global MCP config locations
• Optional token embedding and custom MCP URL overrides

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/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 (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).

# 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

Token Resolution

The CLI finds your token in this order:

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:

braid.json (commit to git):

{
  "$schema": "https://braid.cloud/schemas/config.json",
  "profile": "coding-standards",
  "orgProjects": ["proj_frontend", "proj_shared"],
  "agents": ["claude-code", "cursor"]
}

braid.user.json (add to .gitignore):

{
  "token": "br_your_personal_token",
  "profile": "coding-standards"
}

This lets teams share configuration while each developer uses their own token. Use braid scope --file user to create/update this file. braid auth can launch the scope wizard after sign-in.

All Config Options

Both braid.json and braid.user.json support these fields. Values in braid.user.json override braid.json.

| Field | Type | Description | | ------------------- | -------- | ----------------------------------------------------- | | 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 | | profile | string | Default profile | | orgProjects | string[] | Organization project IDs | | personalProjects | string[] | Personal project IDs | | ruleIds | string[] | Include only specific rule IDs | | excludedRuleIds | string[] | Exclude specific rule IDs | | resolveOverlays | boolean | Resolve overlay prompts from server | | includeUserGlobal | boolean | Include user's global prompts (default: true) | | includeOrgGlobal | boolean | Include org's global prompts (default: true) | | agents | string[] | Target agents |

Environment Variables

CLI context:

| Variable | Description | | ------------------------- | ------------------------------------------------------ | | 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.

| Agent | Project Path | Global Path | | -------------- | ------------------- | ----------------------------- | | Claude Code | .claude/skills/ | ~/.claude/skills/ | | Cursor | .cursor/skills/ | ~/.cursor/skills/ | | GitHub Copilot | .github/skills/ | ~/.copilot/skills/ | | OpenCode | .opencode/skills/ | ~/.config/opencode/skills/ | | Windsurf | .windsurf/skills/ | ~/.codeium/windsurf/skills/ | | Cline | .cline/skills/ | ~/.cline/skills/ | | Continue | .continue/skills/ | ~/.continue/skills/ | | Gemini CLI | .gemini/skills/ | ~/.gemini/skills/ | | Goose | .goose/skills/ | ~/.config/goose/skills/ | | Roo Code | .roo/skills/ | ~/.roo/skills/ |

| Agent | Project Path | Global Path | | ------------- | ---------------------- | -------------------------------------- | | Amp | .agents/skills/ | ~/.config/agents/skills/ | | Antigravity | .agent/skills/ | ~/.gemini/antigravity/global_skills/ | | CodeBuddy | .codebuddy/skills/ | ~/.codebuddy/skills/ | | Codex | .codex/skills/ | ~/.codex/skills/ | | Command Code | .commandcode/skills/ | ~/.commandcode/skills/ | | Crush | .crush/skills/ | ~/.config/crush/skills/ | | Droid | .factory/skills/ | ~/.factory/skills/ | | Junie | .junie/skills/ | ~/.junie/skills/ | | Kilo Code | .kilocode/skills/ | ~/.kilocode/skills/ | | Kimi Code CLI | .agents/skills/ | ~/.config/agents/skills/ | | Kiro CLI | .kiro/skills/ | ~/.kiro/skills/ | | Kode | .kode/skills/ | ~/.kode/skills/ | | MCPJam | .mcpjam/skills/ | ~/.mcpjam/skills/ | | Moltbot | skills/ | ~/.moltbot/skills/ | | Mux | .mux/skills/ | ~/.mux/skills/ | | Neovate | .neovate/skills/ | ~/.neovate/skills/ | | OpenHands | .openhands/skills/ | ~/.openhands/skills/ | | Pi | .pi/skills/ | ~/.pi/agent/skills/ | | Pochi | .pochi/skills/ | ~/.pochi/skills/ | | Qoder | .qoder/skills/ | ~/.qoder/skills/ | | Qwen Code | .qwen/skills/ | ~/.qwen/skills/ | | Trae | .trae/skills/ | ~/.trae/skills/ | | Zed | -- | -- | | Zencoder | .zencoder/skills/ | ~/.zencoder/skills/ |

Rules Support

Some agents also receive rules (always-on standards) in addition to skills. The format depends on the agent:

| Agent | Format | Location | | -------------- | -------------- | --------------------------------- | | Claude Code | Markdown files | .claude/rules/ | | Cursor | MDC files | .cursor/rules/ | | Roo Code | Markdown files | .roo/rules/ | | Zed | Markdown files | .zed/rules/ | | GitHub Copilot | Appended | .github/copilot-instructions.md | | Cline | Appended | .clinerules | | Windsurf | Appended | .windsurfrules |

MCP Support

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.

Common examples:

| Tool | Project Config | Global Config | | -------------- | -------------------- | ------------------------------------------------------ | | Claude Code | .mcp.json | — | | Cursor | .cursor/mcp.json | ~/.cursor/mcp.json | | GitHub Copilot | .vscode/mcp.json | — | | OpenCode | .opencode/mcp.json | ~/.config/opencode/mcp.json | | Cline | — | VS Code extension settings (cline_mcp_settings.json) | | Roo Code | — | VS Code extension settings (mcp_settings.json) | | Zed | — | ~/.config/zed/settings.json |

Skill Format

Installed skills are directories with a SKILL.md file:

my-skill/
├── SKILL.md
├── references/
│   ├── style-guide.md
│   └── diagram.png
└── scripts/
    ├── setup.sh
    └── deploy.py

Scripts in scripts/ with recognized extensions (.sh, .bash, .py, .js, .mjs, .rb) are automatically made executable.

SKILL.md example:

---
name: code-quality
description: Modern TypeScript/React standards
category: coding-standards
tags: [typescript, react]
---

# Code Quality

Instructions for the agent...

Metadata

Installed skills are tracked in .braidskills-metadata.json for update detection. This file is written to each agent's skills directory.

Related

• @braid-cloud/mcp - Real-time MCP integration (no local files)
• braid Website - Learn more about braid and sign up for an account.

License

Proprietary - all rights reserved.