Skip to main content

BoilerSync CLI

boilersync scaffolds projects from templates and keeps templates alive as projects evolve.

BoilerSync Ensemble

BoilerSync works as a small ensemble of tools:

  • boilersync-cli for scaffold, pull, and push workflows.
  • boilersync-desktop for repository diff review, staging, commit, and push workflows.
  • Editor integration (Cursor/VS Code extension workflows) for fast editing and context switching.

For the full workflow guide, read docs/ensemble.md. For template metadata reference, read docs/template-metadata.md.

Quick Start

# 1) Clone a template source into your local BoilerSync cache
boilersync templates init https://github.com/your-org/your-templates.git

# 2) Initialize a project from a source-qualified template ref
boilersync init your-org/your-templates#python/service-template

# Well-defaulted templates can be initialized without prompts
mkdir my-app-workspace
cd my-app-workspace
boilersync init your-org/your-templates#python/service-template --non-interactive

# 3) Pull template updates into the current project when needed
boilersync pull

# 4) Check project divergence from the current template
boilersync diff

# 5) Create a reviewable pull proposal without mutating the project
boilersync pull-proposal create

# 6) Push committed project changes back into the template source
boilersync push

Command Overview

  • boilersync init TEMPLATE_REF: create a project from a template (empty target directory).
  • boilersync init TEMPLATE_REF --non-interactive: create a project without prompts when defaults and automatic values cover all inputs.
  • boilersync check-pull: compare the project's recorded template repo commit against the current cached template repo HEAD.
  • boilersync diff: render the upstream template with the project's saved variables and show how the current project has diverged.
  • boilersync pull [TEMPLATE_REF]: apply template updates to an existing project.
  • boilersync pull-proposal create: create a temp git repo containing proposed pull changes for review.
  • boilersync pull-proposal apply-file PROPOSAL_DIR PATH: copy one proposed file into the current project.
  • boilersync pull-proposal apply-patch PATCH: apply selected hunks from a saved patch.
  • boilersync push: review and copy committed project changes back to the template.
  • boilersync templates init: clone a template source repository into the local cache.
  • boilersync skills install: install the BoilerSync agent skills for Codex and Claude Code with npx skills add.
  • boilersync skills install --dev: symlink a local boilersync-skills checkout into ~/.agents/skills and ~/.claude/skills by running its scripts/install-dev.sh, so skill edits are live.

Use command help for full flags:

boilersync --help
boilersync init --help
boilersync check-pull --help
boilersync diff --help
boilersync pull --help
boilersync pull-proposal --help
boilersync push --help
boilersync templates --help
boilersync skills install --help

Template References

Template commands accept:

  • org/repo#path/to/template
  • https://github.com/org/repo#path/to/template
  • https://github.com/org/repo.git#path/to/template

GitHub is the only supported host for source-qualified template refs.

Source-qualified refs clone (if missing) into:

${BOILERSYNC_TEMPLATE_DIR:-~/.boilersync/templates}/<org>/<repo>

Project Tracking

After scaffold or pull, BoilerSync writes .boilersync metadata in the project root so future pull/push operations can resolve the original template source. That metadata now includes the last pulled template repo commit so boilersync check-pull can tell whether the project is behind template HEAD. For the field-by-field schema and validation rules, see docs/project-metadata.md.

Template Conventions

  • Files ending in .boilersync are rendered and emitted without that extension.
  • Files with .starter as the first extension are starter-only files.
  • Every template root must include template.json, which supports inheritance (extends/parent), defaults, child templates, hooks, and optional GitHub repo creation.
  • Project naming is provided through standard template variables such as name_snake and name_pretty.
  • template.json defaults can derive variables from naming values, such as "api_package_name": "$${name_snake}_api" or "web_package_name": "$${name_kebab}-web".
  • Default project-name inference strips a trailing -workspace / _workspace suffix from the target directory name.
  • If a template references github_user, BoilerSync tries to populate it with gh api user --jq .login before prompting or failing in non-interactive mode.

Documentation Policy

This repository intentionally avoids hand-written API reference docs. If API docs are ever included, they should be generated and linked from this README.

Metadata

Release files for boilersync 1.2.22

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for boilersync 1.2.22
File Size Uploaded Provenance Actions
boilersync-1.2.22.tar.gz 63.3 kB Without provenance Details for boilersync-1.2.22.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for boilersync 1.2.22
File Interpreter ABI Platform Actions
boilersync-1.2.22-py3-none-any.whl Python 3 none any Details for boilersync-1.2.22-py3-none-any.whl

Total release size: 114.5 kB

Release files / boilersync-1.2.22.tar.gz

Download URL boilersync-1.2.22.tar.gz
Size 63.3 kB
Tags Source
SHA-256 checksum
How to use checksums
d15e151621a7f37f68ba6b4b07398563db3ce633ed9a1c3af0e44cea436f1cb4
BLAKE2b-256 checksum
How to use checksums
f7bfd6c40670ce4b957e3f43a3e01b6be3eea05b3f2b7c0f4019e0eee63d2aea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

Release files / boilersync-1.2.22-py3-none-any.whl

Download URL boilersync-1.2.22-py3-none-any.whl
Size 51.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0d82b7ca93e60a77a624ab1dfc362f60fb74bd061d41960e3d6402157f7ea70c
BLAKE2b-256 checksum
How to use checksums
e7036646544e469582c1b2d56107cac1e68d03c02347444f6a3bd2c5c7ab3370
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

Security for boilersync 1.2.22

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page