3 releases

0.2.6 May 13, 2024
0.2.5 May 10, 2024

#569 in Development tools

Custom license and LGPL-3.0

503 lines


pbj is a command line tool to generate sensible tdd software development projects from declarative templates written in TOML.

Typescript and Python project templates are built in. Just install it and go.

pbj generate -t python PROJECT_NAME

pbj generate -t typescript PROJECT_NAME

See the Templates section for details on customization and Origin for why this tool exists.


pbj is avaialable on https://crates.io. Source is available on it’s github page: https://github.com/electric-hand/pbj.

Simplest installation is via cargo.

cargo install pbj


Currently there is only one command: generate.


Generate a project. Aliased to g.

the command

  • parses and loads a template by name — pbj looks for a file named <<template>>.toml in a known set of configuration folders

  • adds production dependencies

  • adds development dependencies (if supported by your language/tooling)

  • runs any post generation commands specified

  • generates source, test and config files as declared in the template


  • pbj generate -t python PROJECT_NAME

  • pbj g PROJECT_NAME — using config file

High on my list of todos is a command for template skeleton generation and a command to initialize a config with defaults.


pjb looks for a config.toml file (used for setting default arguments) and template files in the following locations in the following order. First one found wins.

The config dirs are system dependent and provided by the dirs crate)

Templates are looked for and loaded from the templates subdirectory in the above config locations.


A simple config file that specifies default arguments. Defaults and example can be found here.


The default template to use. Provides a default for the -t or --template argument to the generate command.


The string to use for prefix separation. Used if you provide a prefix to your project via the -p or --prefix argument to the generate command. Defaults to _

pbj g -p 1234 many_moons will generate a project directory 1234_many_moons with the $PROJECT_NAME set to many_moons.


The file variant to use. Provides a default for the -v or --variant argument to the generate command.


Custom Templates

A starter template can be copy/pasted from the github templates folder or one can be manually authored with he format below.



the executable binary used to 'run' the language. This is tested to exist and be on the path.

the version of the language required. NOT USED.

user friendly name of the template. NOT USED.


A list of runtime "production" dependencies.

A list of runtime "development" dependencies.


The project tool used for initialization, dependency management and running tests.


Command for the project.tool that initializes a new project using the project.tool.binary

Command and arguments to add "production" dependencies.

Command and arguments to add "development" dependencies.

Command to run unit tests.


A set of arbitrary commands to execute after the project initialization. Pretty much allows you do whatever you like.

the command to run.

list of arguments to pass to the command above.


the (relative to root) project directory to put the source code files generated by the [[code.source]] files.

the (relative to root) project directory to put the source code files generated by the [[code.test]] files.


files generated relative to the source directory in the [code.directories] table. Follows the file format


files generated relative to the source directory in the [code.directories] table. Follows the file format


files generated relative to the root directory. Follows the file format

file format

the path to generate the file to (can contain folders). The path is relative. The directory the path starts from varies.

an optional key used to generate variations of the template. If specified on the command line, will override files with the same file path. Files without a variant specified have an implicit variant of default.

the contents to write to the file


There is a preprocessing pass on the TOML that does ultra basic variable substitution.


Any use of this special variable will be replaced by the project name provided on the command line.

Random Bits

Leetcode support

One of the drivers for building this tool was a desire to work on algorithmic/interview problems locally.

The intention is to use the prefix argument and leet file variant to do so.

pbj generate -p 1293 -t python shortest_path generates a project that correlates to the problem number but does not include the prefix in any of the generated code. The files lend themseles to the leetcode format.


I needed to do a ton of little projects (mostly coding katas, leetcode, etc.) and had forgotten how to set up typescript projects from scratch with:

  • good configuration

  • healthy layout

  • immediately runnable unit tests

There are other project generators out there — yeoman, npm-based create scripts — but I don’t like how opaque they are. I wanted something fully declarative with a readable project declaration.

This started as a super basic bashscript but then I wanted to jam on python and after a copy past decided to do some better automation.


~103K SLoC