@braid-cloud/cli

Install and manage braid prompt artifacts locally.

The CLI currently covers four jobs:

• Install prompt artifacts into local coding tools
• Manage authenticated braid resources such as projects, rules, profiles, references, and sub-agents
• Install marketplace packs
• Scaffold GitHub-importable pack repos

Prompt artifacts can include skills, workflows, rules, sub-agents, and marketplace hooks.

Requirements

• Node.js >=20.6
• A supported coding tool if you want local installs to auto-detect targets

Install

npm install -g @braid-cloud/cli

Quick Start

# 1. Authenticate
braid auth

# 2. Save default scope to braid.user.json or braid.json
braid scope

# 3. Install from your saved scope
braid install

# 4. Inspect locally installed bundles
braid list

If you do not want to save defaults first, install directly from flags:

braid install --profile coding-standards
braid install --org-projects proj_frontend,proj_shared
braid install --personal-projects proj_experiments

Install Sources

Scoped braid content

Install from a saved profile or explicit project scope:

braid install --profile coding-standards
braid install --org-projects proj_frontend,proj_shared
braid install --personal-projects proj_experiments

Public versioned source

Install from a public source reference:

braid install @handle/slug
braid install @handle/slug@3

For public installs, the CLI can write and reuse braid.lock entries so later installs can use exact versions with --locked.

braid install --locked

Marketplace pack

Install a marketplace pack already available in your library:

braid marketplace library
braid marketplace install team-toolkit

Marketplace installs can contain skills, workflows, rules, sub-agents, and hooks. Hook installs require explicit opt-in:

braid marketplace install team-toolkit --allow-hooks

Core Local Commands

| Command | What it does | | --- | --- | | braid auth | Authenticate with browser/device flow or --token | | braid auth status | Show current auth state and resolved defaults | | braid auth logout | Remove the saved token or session | | braid scope | Write scoped defaults to braid.user.json or braid.json | | braid install / braid add | Install prompt artifacts from scope or public source | | braid list / braid ls | List locally installed skill bundles | | braid update / braid up | Refresh locally installed non-marketplace bundles | | braid remove / braid rm | Remove locally installed skill bundles | | braid manage | Start the local prompt manager UI | | braid scaffold | Scaffold a GitHub-importable pack artifact in the current directory | | braid rollback | Move a public @handle/slug lockfile entry back to a previous version | | braid retract / braid unpin | Remove a pinned public version from braid.lock |

Common Usage

Authentication

braid auth
braid auth login --token br_xxx
braid auth login --server http://localhost:3211
braid auth status
braid auth logout

Notes:

• braid auth is an alias for braid auth login
• Browser login saves a CLI session in ~/.config/braid/config.json
• --no-scope skips launching scope setup after login

Install

braid install --profile coding-standards
braid install --profile coding-standards --agents claude-code,cursor
braid install --profile coding-standards --global
braid install --profile coding-standards --list
braid install --profile coding-standards --yes

braid install @handle/slug
braid install @handle/slug@3
braid install @handle/slug --locked
braid install --locked

Important flags:

| Flag | Meaning | | --- | --- | | --locked | Reuse exact versions from braid.lock | | -p, --profile <name> | Install from a profile | | --org-projects <ids> | Install from organization projects | | --personal-projects <ids> | Install from personal projects | | --no-include-user-globals | Exclude personal global rules/prompts | | --no-include-org-globals | Exclude organization global rules/prompts | | -a, --agents <list> | Target specific coding tools | | -g, --global | Install into global agent directories | | -l, --list | Preview installable skills without writing files | | -y, --yes | Skip interactive confirmation | | -s, --server <url> | Override the braid server URL |

When no --agents flag is given, the CLI auto-detects installed tools and prompts if needed.

Local inventory

braid list
braid list --global

braid update
braid update --yes

braid remove
braid remove --skill requesting-code-review
braid remove --all --yes

Scope configuration

braid scope
braid scope --file user
braid scope --file project

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

braid scope supports both interactive and non-interactive setup. Manual mode can combine globals, project scopes, and rule include/exclude filters.

Local manager

braid manage
braid manage --port 4321
braid manage --no-open

This starts the local manager server and opens a browser unless --no-open is passed.

E2E Testing

The CLI has two Playwright E2E modes.

For the default local packaged-binary smoke suite:

cd apps/cli
bun run test:e2e

That run is local-first on purpose:

• it builds and packs the real published CLI binary
• it covers local user-facing failures and filesystem side effects
• it does not require the web app, WorkOS, or local Convex to be running

For the full browser-backed auth flow and real web handshake:

cd apps/cli
CLI_E2E_AUTH=1 bun run test:e2e

or the equivalent convenience script:

cd apps/cli
bun run test:e2e:auth

Full auth-backed E2E requires:

• local workspace setup to have written apps/web/.env.local and apps/convex/.env.local
• E2E_TEST_USER_PASSWORD
• WORKOS_API_KEY or E2E_WORKOS_API_KEY
• a supported local Node version for Convex (18, 20, 22, or 24)

If Playwright auto-start hits local watch limits, start the web stack manually first and rerun the auth suite. The CLI Playwright config will reuse an existing server on PLAYWRIGHT_PORT.

cd apps/convex && bun run dev:convex
cd apps/web && bun run dev
cd apps/cli && CLI_E2E_AUTH=1 bun run test:e2e

Scaffold a pack repo

braid scaffold

braid scaffold --type skill --name requesting-code-review --description "When the user wants a detailed code review"
braid scaffold --type rule --name no-biome-ignore --title "No biome-ignore"
braid scaffold --type agent --name code-reviewer --description "Reviews pull requests" --linked-skills requesting-code-review
braid scaffold --type hook --name review-trigger
braid scaffold --type workflow --name pr-review --skill-ref requesting-code-review --agent-ref code-reviewer

Current scaffold targets:

• skill -> skills/<name>/SKILL.md
• rule -> rules/<name>.md
• agent -> agents/<name>.md
• hook -> hooks/<name>.json
• workflow -> workflows/<name>.json

braid scaffold also creates or updates braid-pack.json.

Public version management

braid rollback @handle/slug
braid retract @handle/slug@3

Notes:

• rollback updates braid.lock; it does not reinstall content by itself
• after rollback, run braid install @handle/slug --locked
• retract only removes the local pin from braid.lock; it does not retract a published version from the server

Remote API Commands

These commands talk to the authenticated braid API. Most also accept --api-key and --json.

| Group | Commands | | --- | --- | | projects | list, get, create, update, remove | | rules | list, get, create, update, remove, enable, disable, move, duplicate, fork, sync-status, sync-history, sync-enable, sync-disable, sync-check, sync-now | | references | list, get, create, update, remove, reorder | | profiles | list, get, create, update, remove, set-default | | skills | list | | sub-agents | list, get, create, update, remove, install | | marketplace | library, install |

Examples:

braid projects list
braid projects create --name "Shared Standards"

braid rules list --json
braid rules create --title "No force push" --content "Never force push shared branches"
braid rules sync-status

braid references create --rule-id rule_123 --file ./docs/policy.md

braid profiles list
braid profiles create --name default --context-json '{"profile":"default"}'

braid sub-agents create \
  --name reviewer \
  --description "PR reviewer" \
  --prompt "Review this change for correctness and regressions"

braid sub-agents install --id agent_123 --agents claude-code,opencode

Configuration

Files

• braid.user.json: personal machine defaults, usually gitignored
• braid.json: shared project defaults
• ~/.config/braid/config.json: global CLI auth/session storage

Typical setup:

braid.json

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

braid.user.json

{
  "profile": "coding-standards"
}

Supported config fields

braid.user.json and braid.json can contain:

| Field | Type | Description | | --- | --- | --- | | $schema | string | Optional schema URL | | serverUrl | string | Base braid server URL | | skills.serverUrl | string | Skills endpoint override | | org | string | Default organization ID | | profile | string | Default profile | | orgProjects | string[] | Default organization project IDs | | personalProjects | string[] | Default personal project IDs | | ruleIds | string[] | Include only these rule IDs | | excludedRuleIds | string[] | Exclude these rule IDs | | resolveOverlays | boolean | Resolve overlay prompts from the server | | includeUserGlobal | boolean | Include personal globals | | includeOrgGlobal | boolean | Include organization globals | | agents | string[] | Default target agents |

For authentication, prefer braid auth, BRAID_API_KEY, or the global config file. Do not commit tokens to braid.json.

Environment variables

| Variable | Description | | --- | --- | | BRAID_API_KEY | API key override for authenticated commands | | BRAID_SERVER_URL | Global server URL override | | BRAID_SKILLS_SERVER_URL | Skills endpoint override | | BRAID_STORE_ROOT | Override the local bundle store root | | BRAID_DISABLED_ROOT | Override the disabled bundle store root | | BRAID_ALLOW_UNTRUSTED_SERVER_URL | Allow non-default/untrusted server URLs for API calls |

Resolution behavior

• Default server is https://braid.cloud
• Inside a local braid workspace, the CLI can infer a local server URL from workspace env files
• braid.user.json overrides braid.json
• environment variables override file-based settings

Supported Coding Tools

The CLI auto-detects supported tools from local/global config markers and installs into tool-specific paths.

Current skill-install targets include:

• Amp
• Antigravity
• Claude Code
• Cline
• CodeBuddy
• Codex
• Command Code
• Continue
• Crush
• Cursor
• Droid
• Gemini CLI
• GitHub Copilot
• Goose
• Junie
• Kilo Code
• Kimi Code CLI
• Kiro CLI
• Kode
• MCPJam
• Moltbot
• Mux
• Neovate
• OpenCode
• OpenHands
• Pi
• Pochi
• Qoder
• Qwen Code
• Roo Code
• Trae
• Windsurf
• Zencoder

Rule installs are currently supported for:

• Claude Code
• Cursor
• Roo Code
• Zed
• GitHub Copilot
• Cline
• Windsurf

Some marketplace content can also install:

• Claude Code hooks
• Claude Code and OpenCode sub-agents

Installed File Layout

Installed skills are written as directories that contain SKILL.md and any bundled supporting files:

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

Installed bundle metadata is tracked with .braid-metadata.json in each target directory (skills directory for skills/workflows, alongside the tool config for hooks).

License

Proprietary - all rights reserved.