Engineer Commandline

Engineer is primarily invoked at the command line. The command is aptly called engineer, or engineer.exe on Windows. It accepts five basic top-level commands: build, clean, serve, emma and init, which each accept additional parameters.

Common Arguments

All of the Engineer commands accept the following arguments:

-h, --help

Display help for the command.

-v, --verbose

Display verbose command line output. You can see extremely verbose output by specifying the option twice. For example:

engineer build -vv

Changed in version 0.2.3.

-s, --settings, --config

Specify the path to the settings file to use. Defaults to config.yaml if not provided.


While the engineer init command does accept this argument, it does not use it in any way.


engineer init

Initialize a directory with a basic structure for an Engineer site, optionally including sample content. Note that using the init command is not required to create an Engineer site; all it does is a create a general purpose folder structure, a settings file, and optionally some sample content.


engineer init [-h] [-v] [-s CONFIG_FILE] [-m {azure}] [--sample] [--force]
-m, --mode

Initializes a site structure designed for deployment to a specific hosting service such as Azure. See Deploying Engineer Sites for more details. Valid options:

  • azure: Initializes a site for deployment to Azure.

By default, the init command does not create sample content to provide a starting point for a new site. By passing this option, however, sample content will be created.

Changed in version 0.5.0: Replaced the --no-sample option with this, effectively reversing the default.

-f, --force

Forcefully initialize a folder as an engineer site even if the target folder is not empty. Use with caution!

engineer build

Build an Engineer site from an input settings file and other source files.


engineer build [-h] [-v] [-s CONFIG_FILE] [-c]
-c, --clean

Clear all caches and the output directory prior to building. This parameter is equivalent to engineer clean but immediately runs a build after.

engineer clean

Clears all caches and the output directory. This can be useful if you’re seeing strange errors such as changes not being picked up properly or you simply want to ‘start fresh.’


engineer clean [-h] [-v] [-s CONFIG_FILE] [-p PORT]

engineer serve

Starts the built-in Engineer development server. The dev server will serve up a site’s output directory contents at http://localhost:8000. You can press Ctrl-C to stop the dev server when you’re done with it. Note that serve does not build a site, so you should run engineer build before you run engineer serve. Also keep in mind that if you make changes to the site source, such as posts or whatnot, you’ll need to manually rebuild the site in order for those changes to be reflected. Adding the capability to autodetect changes and rebuild the site as needed are planned but not yet implemented.


It’s not a good idea to use the dev server to serve your site in production. While it’s probably capable of this since it uses under the covers, it hasn’t been tested or designed for that purpose. Besides, part of the benefit in using Engineer in the first place is that you can just copy the output to an existing production web server and go. Why take on additional overhead of running your own server if you don’t need to?


engineer serve [-h] [-v] [-s CONFIG_FILE] [-p PORT]
-p, --port

Specify the port the development server should run on. If not specified, the default is 8000.

New in version 0.2.3.

engineer emma

Documentation TBD.


engineer emma [-h] [-v] [-s CONFIG_FILE] [-p PORT] [--prefix PREFIX] (-r | -g | -u)