@braid-cloud/cli 0.1.0

package/README.md

@@ -0,0 +1,283 @@
+# @braid-cloud/cli
+
+Install [braid](https://braid.cloud) rules as agent skills to your local development environment.
+
+## Overview
+
+`@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.
+
+## Installation
+
+```bash
+# Run directly with npx
+npx @braid-cloud/cli --help
+
+# Or install globally
+npm install -g @braid-cloud/cli
+```
+
+## Quick Start
+
+```bash
+# 1. Authenticate with your braid API key
+braid auth
+
+# 2. Install skills from a profile
+braid install --profile coding-standards
+
+# 3. View installed skills
+braid list
+```
+
+## Commands
+
+### `braid auth`
+
+Configure your braid API key for authentication.
+
+```bash
+# Interactive login
+braid auth
+
+# Check auth status
+braid auth status
+
+# Logout (remove stored key)
+braid auth logout
+
+# Use a different server (review apps, local dev)
+braid auth --server https://my-branch.braid.cloud
+```
+
+#### Token Configuration
+
+The CLI looks for your API token in the following order:
+
+1. **`BRAID_API_KEY` environment variable** - Best for CI/CD
+2. **`braid.user.json` in your project** - Recommended for teams
+3. **`~/.config/braid/config.json`** - Global fallback
+
+**Recommended: Project-level configuration**
+
+Create two files in your project root:
+
+**`braid.json`** (committed to git, shared with team):
+
+```json
+{
+  "project": "my-project",
+  "org": "my-org"
+}
+```
+
+**`braid.user.json`** (gitignored, personal token):
+
+```json
+{
+  "token": "br_your_personal_access_token"
+}
+```
+
+Add `braid.user.json` to your `.gitignore`:
+
+```bash
+echo "braid.user.json" >> .gitignore
+```
+
+This approach allows:
+
+- Team members share the same project/org configuration
+- Each developer uses their own personal access token
+- No credentials are committed to git
+
+You can override any setting in `braid.user.json`:
+
+```json
+{
+  "token": "br_your_token",
+  "serverUrl": "https://my-branch.braid.cloud",
+  "profile": "my-custom-profile"
+}
+```
+
+### `braid install`
+
+Install skills from a braid profile or project.
+
+```bash
+# Install from a profile
+braid install --profile coding-standards
+braid install -p coding-standards
+
+# Install from a project
+braid install --project frontend --org acme-corp
+
+# Specify agents manually
+braid install -p coding-standards --agents claude-code,opencode
+
+# Install to global directories (not project-local)
+braid install -p coding-standards --global
+
+# Preview skills without installing
+braid install -p coding-standards --list
+
+# Skip confirmation prompts
+braid install -p coding-standards --yes
+
+# Use a different server
+braid install -p coding-standards --server https://localhost:3000
+```
+
+**Options:**
+
+| Flag                   | Description                         |
+| ---------------------- | ----------------------------------- |
+| `-p, --profile <name>` | Profile name to install from        |
+| `--project <name>`     | Project name (requires `--org`)     |
+| `-o, --org <slug>`     | Organization slug                   |
+| `-a, --agents <list>`  | Comma-separated agent list          |
+| `-g, --global`         | Install to global agent directories |
+| `-y, --yes`            | Skip confirmation prompts           |
+| `-l, --list`           | Preview skills without installing   |
+| `-s, --server <url>`   | braid server URL                    |
+
+### `braid list`
+
+List installed skills across all detected agents.
+
+```bash
+# List project-local skills
+braid list
+
+# List global skills only
+braid list --global
+```
+
+### `braid update`
+
+Update installed skills to the latest version from braid.
+
+```bash
+# Update all installed skills
+braid update
+
+# Update global skills only
+braid update --global
+
+# Skip confirmation
+braid update --yes
+```
+
+## Supported Agents
+
+`@braid-cloud/cli` automatically detects and supports these AI coding agents:
+
+| Agent          | Project Path              | Global Path                        |
+| -------------- | ------------------------- | ---------------------------------- |
+| Claude Code    | `.claude/skills/`         | `~/.claude/skills/`                |
+| OpenCode       | `.opencode/skills/`       | `~/.config/opencode/skills/`       |
+| Cursor         | `.cursor/skills/`         | `~/.cursor/skills/`                |
+| Windsurf       | `.windsurf/skills/`       | `~/.windsurf/skills/`              |
+| Cline          | `.cline/skills/`          | `~/.cline/skills/`                 |
+| Roo Code       | `.roo/skills/`            | `~/.roo/skills/`                   |
+| Augment        | `.augment/skills/`        | `~/.augment/skills/`               |
+| Aider          | `.aider/skills/`          | `~/.aider/skills/`                 |
+| GitHub Copilot | `.github/copilot/skills/` | `~/.config/github-copilot/skills/` |
+| Continue       | `.continue/skills/`       | `~/.continue/skills/`              |
+| Void           | `.void/skills/`           | `~/.void/skills/`                  |
+| Codex          | `.codex/skills/`          | `~/.codex/skills/`                 |
+| Amp            | `.amp/skills/`            | `~/.amp/skills/`                   |
+| Trae           | `.trae/skills/`           | `~/.trae/skills/`                  |
+| Kilo Code      | `.kilo/skills/`           | `~/.kilo/skills/`                  |
+| Gemini CLI     | `.gemini/skills/`         | `~/.gemini/skills/`                |
+| Witsy          | `.witsy/skills/`          | `~/.witsy/skills/`                 |
+| Zed            | `.zed/skills/`            | `~/.config/zed/skills/`            |
+
+## Configuration
+
+### Configuration Files
+
+The CLI uses two configuration files in your project:
+
+| File              | Purpose                                    | Git    |
+| ----------------- | ------------------------------------------ | ------ |
+| `braid.json`      | Shared team config (project, org, profile) | Commit |
+| `braid.user.json` | Personal token and overrides               | Ignore |
+
+### `braid.json` Format (shared)
+
+```json
+{
+  "project": "my-project",
+  "org": "my-org",
+  "serverUrl": "https://braid.cloud"
+}
+```
+
+### `braid.user.json` Format (personal)
+
+```json
+{
+  "token": "br_your_personal_access_token"
+}
+```
+
+You can override any `braid.json` setting in `braid.user.json`.
+
+### Resolution Order
+
+Settings are resolved in this order (later sources override earlier):
+
+1. `braid.json` (shared team config)
+2. `braid.user.json` (personal overrides)
+3. Environment variables (`BRAID_API_KEY`, `BRAID_SERVER_URL`)
+4. CLI flags (`--server`, `--profile`, etc.)
+
+### Environment Variables
+
+| Variable           | Description                                 |
+| ------------------ | ------------------------------------------- |
+| `BRAID_API_KEY`    | API key (highest priority)                  |
+| `BRAID_SERVER_URL` | Server URL (default: `https://braid.cloud`) |
+
+## SKILL.md Format
+
+Skills are installed as directories containing a `SKILL.md` file with YAML frontmatter:
+
+```
+my-skill/
+├── SKILL.md
+└── references/
+    ├── style-guide.md
+    └── diagram.png
+```
+
+**SKILL.md example:**
+
+```markdown
+---
+name: code-quality
+description: Modern TypeScript/React development standards
+category: coding-standards
+tags:
+  - typescript
+  - react
+  - code-style
+---
+
+# Code Quality
+
+Instructions for the agent to follow...
+```
+
+## Metadata Tracking
+
+Installed skills are tracked in `.braid-skills-metadata.json` within each agent's skills directory. This enables:
+
+- Knowing which skills came from braid
+- Tracking the source profile/project
+- Detecting when updates are available
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }