Forge CLI

One source of truth for every AI tool your team uses.

Your team uses Claude Code, Cursor, Windsurf, Copilot, and Cline. Maybe all of them. Maybe different ones per repo.

Someone writes a great deployment skill for Claude Code — it lives in .claude/skills/deploy.md. The Cursor team never sees it. Copilot has its own version, three weeks out of date.

10 repos × 5 AI tools = 50 config files. Copy-paste. Drift. Nobody knows what's current.

Forge fixes that. Write your AI skills, rules, and workflows once. Sync them everywhere — in the right format, in the right place.

Install

Homebrew (macOS / Linux)

brew install crucibledx/tap/forge

Scoop (Windows)

scoop bucket add crucibledx https://github.com/crucibledx/scoop-bucket
scoop install forge

npm / bun (requires Bun runtime)

bun add -g @crucibledx/forge-cli
# or: npm install -g @crucibledx/forge-cli

Shell script (macOS / Linux — downloads standalone binary)

curl -fsSL https://raw.githubusercontent.com/crucibledx/forge-cli/main/scripts/install.sh | sh

Manual download — grab the binary for your platform from Releases, extract, and add to your PATH.

Quick Start

forge init    # wizard detects your AI tools, configures a source
forge sync    # pulls files, transforms & places them for each tool
forge health  # dashboard: sync status, drift, source reachability

That's it. Commit .crucible/forge.config.yaml so the whole team stays in sync.

How It Works

Define shared AI configs in a source repo:

my-source/
  skills/
    deploy.md
    testing.md
  rules/
    code-style.md
  workflows/
    review.md

Forge auto-detects the layout and maps each file to every assistant's native format:

| Assistant | Target paths | Auto-transform | |--------------------|----------------------------------------------------------|------------------------------| | Claude Code | .claude/skills/, .claude/rules/, .claude/commands/ | — | | Cursor | .cursor/rules/ | .md → .mdc + frontmatter | | Windsurf | .windsurf/rules/, .windsurf/workflows/ | frontmatter injection | | GitHub Copilot | .github/skills/, .github/instructions/ | .md → .instructions.md | | Cline | .cline/skills/, .clinerules/ | — |

Only active tools are synced. If your project doesn't use Windsurf, Forge won't touch .windsurf/. Adding a new assistant is one file.

See It in Action

Drift detection & easy updates

Check status, spot drift, add a second source, sync — no YAML editing, no guessing.

Power user: merge strategies & dry-run

Fine-grained source control, include/exclude filters, conflict resolution, dry-run preview, health dashboard.

Commands

| Command | Description | |---------------------------|--------------------------------------------------------| | forge init | Interactive wizard — detect tools, configure sources | | forge sync | Fetch, transform, and place files for each assistant | | forge sync --dry-run | Preview all changes without writing | | forge status | Show drift between last sync and filesystem | | forge health | SLI dashboard — sync frequency, drift, reachability | | forge config | Interactive config editor | | forge source list | List sources with sync counts | | forge source add | Add a source interactively | | forge source remove | Remove a source + optional cleanup | | forge source edit | Edit source with pre-filled values | | forge scheduler install | Register OS-level auto-sync (launchd/crontab/schtasks) | | forge uninstall | Remove config, scheduler, and synced files |

Full reference → crucibledx.dev/forge/commands

Sources

Git (recommended)

sources:
  - name: org-standards
    type: git
    url: [email protected]:acme/ai-configs.git
    branch: main
    subdirectory: skills     # optional: sync only a subfolder
    include: [ "*.md" ]        # optional: glob filters

Local directory

sources:
  - name: team-rules
    type: local
    path: ../shared-ai-configs

Source layouts

Forge auto-detects how your source is organized — no configuration needed:

• Canonical — skills/, rules/, workflows/ folders, distributed and transformed per assistant
• Pre-structured — contains .claude/, .cursor/ dirs, copied as-is
• Hybrid — mix of both, auto-detected by default

Sync Engine

• Multi-source — parallel fetch via Promise.allSettled, failed sources don't block others
• SHA-256 change detection — no unnecessary writes
• Conflict strategies — prefer_source, prefer_local, or error for both source and local conflicts
• Backup — .bak copies before overwrites
• Dry-run — preview everything before writing
• Rollback — on failure, already-written files are reverted. No partial state
• Auto-sync — OS-level scheduling: launchd (macOS), crontab (Linux), Task Scheduler (Windows)

Best With a Skills Platform

Forge pulls from any git repo. But for teams building shared AI resources at scale, pair it with the Forge Skills Starter — a convention-over-configuration platform for designing, developing, testing, and delivering AI skills, rules, and workflows.

Part of Crucible

Forge is the distribution engine of the Crucible platform — an ecosystem of focused tools for AI developer experience.

Development

bun install               # install deps
bun run dev -- <command>  # run locally
bun run test              # unit + e2e tests
bun run typecheck         # tsc --noEmit
bun run build             # compile to dist/

DDD architecture: domain/ (pure logic) → application/ (commands) → infrastructure/ (I/O). Adding a new assistant or source type = one file, zero changes to existing commands.

License

MIT