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-clifor scaffold, pull, and push workflows.boilersync-desktopfor 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 withnpx skills add.boilersync skills install --dev: symlink a localboilersync-skillscheckout into~/.agents/skillsand~/.claude/skillsby running itsscripts/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/templatehttps://github.com/org/repo#path/to/templatehttps://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
.boilersyncare rendered and emitted without that extension. - Files with
.starteras 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_snakeandname_pretty. template.jsondefaultscan 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/_workspacesuffix from the target directory name. - If a template references
github_user, BoilerSync tries to populate it withgh api user --jq .loginbefore 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.