bp-tool
A CLI that turns Bitrix24's binary .bpt business-process files into readable JSON for git and diffing
Low risk
We rate an entry low when it mostly gives the agent instructions and reference material.
Why this level
- Only works with local files, does not connect to the portal directly
- Deserializes only simple data types, no code execution
Install
Manual install
git clone https://github.com/mostachev/bp-tool.git && cd bp-tool && npm install && npm run build && npm linkAfter building, the bp-tool command is available globally.
This is third-party code. Review the repository files before installing.
What it does
Bitrix24 exports business process templates as a binary .bpt format (zlib over PHP serialize) that cannot be read or diffed directly. bp-tool decodes .bpt into JSON or XML, encodes JSON back into .bpt for re-import into the portal, shows a template summary (activity counts by type, parameters, variables, document fields), normalizes JSON by sorting keys for stable git diffs, compares two files with a unified diff and an exit code, and builds a Mermaid state diagram of the activity tree. During deserialization only arrays, strings, numbers and booleans are restored; no PHP objects are instantiated.
Who it is for. For Bitrix24 developers who want to version business processes in git and see meaningful diffs instead of a binary blob.
Good fit when
- You want to put a Bitrix24 business process into git with a readable change history
- You need to compare two template versions and see what actually changed
- You need a diagram of the template for documentation
Not a fit when
- You need direct access to a Bitrix24 portal: the tool only works with local .bpt files
- You need automation of the export or import step itself, not just file conversion
Example request
Decode template.bpt, normalize the JSON and show the activity tree as a Mermaid diagramLimitations
Only works with local .bpt files; exporting from the portal and importing back are manual steps done through the Bitrix24 UI. The maintainer recommends processing only files from trusted sources, meaning your own portal.
How to disable. Unlink the global command with npm unlink -g bp-tool and delete the project folder.
Security check
- Only works with local files, does not connect to the portal directly
- Deserializes only simple data types, no code execution
README in short
The English README (with a Russian version in README.ru.md) explains the binary .bpt problem and solves it with decode, encode, inspect, normalize, diff and graph commands, gives an example inspect output, a git workflow for versioning business processes, a description of the .bpt format by key, instructions for bundling a single binary via Node.js SEA, and a security section about deserializing only safe types. MIT license.
FAQ
Can JSON be converted back into Bitrix24's format?
Yes, the encode command builds a .bpt from JSON that can be imported into the portal, and diff confirms the files are identical after a round trip.
Which platforms does it run on?
Windows and Linux, needs Node.js 20 or newer, and can be bundled into a single binary via Node.js SEA.
Related
A skills library that gives coding agents a development process: brainstorming, planning, TDD, subagents and code review
Skills for real engineers by Matt Pocock
Skills For Real Engineers
Small composable skills for engineering with agents: plan grilling, TDD, bug diagnosis, code review and architecture
GitHub toolkit for spec-driven development: the specify CLI adds agent commands and skills to a project, from principles to implementation
Reference MCP servers
Model Context Protocol servers
Official reference MCP servers: Filesystem, Fetch, Git, Memory, Sequential Thinking, Time and Everything