Skip to content

Commands

Jump to bottom
github-actions[bot] edited this page May 2, 2026 · 25 revisions

Commands

bluetemberg init [directory]

Interactive wizard that scaffolds AI tooling into a project. When you need reproducible installs (agents, CI, infrastructure scripts), prefer non-interactive mode or --config.

Arguments:

  • directory — target directory (default: current directory)

Options:

Option Notes
--non-interactive Use the same preset logic as the wizard for the chosen --profile (default profile: fullstack), then merge optional overrides. Exclusive with --config.
--config <file> Validate JSON against InitAnswers (teamProfile, projectName, platforms, ruleSource, rules, ruleCollections, boolean includes, arrays, …). Overrides like --profile, --omit-mcp, and CSV lists cannot be mixed with --config.
--profile <id> With --non-interactive only (frontend, backend, fullstack, devops, pure-infra, custom).
--project-name, --project-description With --non-interactive without --config.
--package-manager Values: pnpm, npm, or yarn. --non-interactive only.
--platforms <csv> e.g. cursor,claude (non-empty when set). --non-interactive only.
--rule-source Values: templates or collections. --non-interactive only.
--rules <csv>, --rule-collections <csv> Respect rule-source: template rule ids extend universal rules automatically; registry collection ids apply when --rule-source collections.
--agents <csv>, --skills <csv>, --mcp-servers <csv> Scoped lists when scaffolding is enabled.
--omit-agents, --omit-skills, --omit-mcp Shortcut booleans (--non-interactive only).

Global discovery: combine --help --json (any position with --help/-h) to dump team profiles, package managers, rules, collections, agents, skills, MCP presets, and CLI metadata as JSON (writeSync-safe for piping).

What it does:

  1. Asks you to pick a team profile (sets smart defaults for all subsequent choices)
  2. Asks for project name, description, and package manager
  3. Asks you to pick platforms, rules, agents, skills, and MCP servers
  4. Creates llm/ directory with selected starter content
  5. Generates bluetemberg.config.json
  6. Creates AGENTS.md, CLAUDE.md (if Claude selected), and GEMINI.md (if Gemini selected, via the initial sync)
  7. Writes llm/mcp.json with chosen MCP preset ids (if MCP selected); the initial sync step generates .claude/mcp.json, .github/mcp.json, and/or .cursor/mcp.json from that manifest (per selected platforms)
  8. Adds sync:llm-config scripts to package.json
  9. Patches .prettierignore with llm/ and docs/wiki/ to protect prose from formatters
  10. Runs an initial sync to generate all platform-specific files

Universal guardrail rules are always included and shown as non-deselectable in the rules step. See Profiles for what each team profile pre-checks.

Example:

npx @prototypdigital/bluetemberg init
npx @prototypdigital/bluetemberg init ./my-project

# Headless
npx @prototypdigital/bluetemberg init --non-interactive --profile devops --omit-mcp
npx @prototypdigital/bluetemberg init --config ./bluetemberg.init.json ./my-project

Programmatic callers can keep using init(root, opts)/scaffold(...)/sync(...) exported from the package (InitRunOptions describes the programmatic mirror of the CLI knobs).

bluetemberg sync [directory]

Reads vendor-neutral sources from llm/ and generates platform-specific files.

Arguments:

  • directory — project root directory (default: current directory)

Options:

Option Description
--check Dry-run mode; exits with code 1 if any generated files are out of sync
--dry-run Alias for --check
--silent Suppress all output (useful in scripts and CI)
--prune After a successful write pass, delete stale generated files under managed output dirs (ignored with --check; see Configuration)
--verbose Emit debug output: resolved source directories (including extends entries), per-file origin when multiple sources are active, and any non-fatal warnings

Before first use of --prune, read the short pre-flight list and platform notes under Stale generated files in Configuration.

Example:

npx bluetemberg sync
npx bluetemberg sync --check
npx bluetemberg sync --dry-run --silent
npx bluetemberg sync --prune
npx bluetemberg sync ./my-project

bluetemberg add <package>

Install a rule pack from the npm registry. See Registry for full details.

bluetemberg add @company/rules-frontend
bluetemberg add @company/rules-frontend@^1.2.0

bluetemberg remove <package>

Remove a rule pack from the project.

bluetemberg remove @company/rules-frontend

bluetemberg list

List installed rule packs with their resolved versions.

bluetemberg list

bluetemberg install

Install all packs from the manifest (llm/rule-packages.json). Run after cloning a repo.

bluetemberg install
bluetemberg install --force

bluetemberg update [package]

Re-resolve and upgrade rule packs to the best version satisfying their manifest range. See Registry for full details.

bluetemberg update
bluetemberg update @company/rules-frontend
bluetemberg update --latest
Option Description
--latest Widen ranges to "latest" in manifest, not just re-resolve current range
--silent Suppress all output

bluetemberg search <query>

Search npm for rule packs tagged with bluetemberg-pack.

bluetemberg search typescript
bluetemberg search frontend rules --limit 10

Exit codes

Code When
0 Sync finished with no recorded errors, and (if --check) all generated files match the expected content
1 Any sync error was recorded (invalid optional manifests, unknown MCP preset ids, adapter load failures, per-file rule errors, etc.), or --check found one or more files out of sync

Warnings vs errors: Some issues are non-fatal and appear as warnings — for example, an extends entry that references a path or package that does not exist. Warnings are logged and included in the programmatic SyncResults.warnings array but do not cause exit code 1. Use --verbose to see all warnings even when there are no errors.

Use --silent in CI only together with checking $? (or equivalent): failures are signaled by the exit code, not only by log lines.

When to run:

  • After creating or editing any file in llm/rules/, llm/agents/, llm/skills/, llm/mcp.json, llm/hooks.json, llm/commands/, or llm/prompts/
  • After changing platforms, extends, or adapters in bluetemberg.config.json
  • In CI to verify generated files haven't drifted (use --check)

Package scripts

After running init, these scripts are added to your package.json:

Script Command
sync:llm-config npx bluetemberg sync
sync:llm-config:check npx bluetemberg sync --check

Clone this wiki locally