Command line interface

The buildenv tools comes with a command-line interface, described on this page.

This interface is supported by the different ways to invoke the buildenv tool:

• by calling one of the generated loading scripts:

  • on Linux: ./buildenv.sh <args>

  • on Windows: buildenv.cmd <args>

• by calling the buildenv command once the venv is loaded:

  • in venv: buildenv <args>

• by calling through tool wrappers, e.g.:

  • uvx buildenv <args> – see uvx documentation

  • pipx run buildenv <args> – see pipx documentation

General arguments

Here is the general buildenv command help page:

usage: buildenv [-h] [-V]
                {install,init,shell,run,list,lock,unlock,upgrade} ...

Build environment manager

positional arguments:
  {install,init,shell,run,list,lock,unlock,upgrade}
                        sub-commands:
    install             install build environment loading scripts and setup
                        project from template
    init                create venv and initialize extensions (implicitly done
                        with shell and run commands)
    shell               start an interactive shell with loaded build
                        environment (default if no sub-command is specified)
    run                 run command in build environment
    list                list installed packages in the current build
                        environment
    lock                lock build environment packages versions
    unlock              unlock build environment packages versions
    upgrade             upgrade build environment packages to their latest
                        version

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit

Common arguments (also usable in sub-commands)

• -h or --help: displays the help message and exits; this works for all sub-commands as well.

• -V or --version: displays the buildenv tool version and exits

• -p PROJECT or --project PROJECT: identifies the project folder (default is current folder)

• --shell SHELL: force using specified shell (by default, always spawn a bash shell, even on Windows)

Default command

When invoked without sub-command, the buildenv command line interface will execute the shell sub-command.

install sub-command

usage: buildenv install [-h] [--project PROJECT] [--shell {bash,cmd}]
                        [--backend {pip,uv,uvx,pipx}] [--add PACKAGE]
                        [--template TEMPLATE | --no-template | --list-templates]
                        [--extra-template TEMPLATE]
                        [--ignore-template TEMPLATE] [--no-clean]

install build environment loading scripts and setup project from template

options:
  -h, --help            show this help message and exit
  --project PROJECT, -p PROJECT
                        project folder (default: .)
  --shell {bash,cmd}    force using specified shell (default: bash)
  --backend {pip,uv,uvx,pipx}
                        force using specified backend
  --add PACKAGE         additional package to install in this environment (can
                        be specified multiple times)
  --no-clean            don't clean legacy buildenv files

project template options:
  --template TEMPLATE, -t TEMPLATE
                        main template used to create a new project (overrides
                        default template)
  --no-template         forces project install without any template
  --list-templates      prints all available project templates and exit
  --extra-template TEMPLATE, -X TEMPLATE
                        adds extra project template support (can be specified
                        multiple times)
  --ignore-template TEMPLATE, -I TEMPLATE
                        removes extra project template support (can be
                        specified multiple times)

This sub-command allows to:

• create or update the build environment loading scripts in the specified project

• setup a new project using one of the provided templates

Choosing a backend

By default, the used environment backend is detected from the one used to launch the install command; e.g. if the uvx buildenv install command is invoked, the selected backend will be uvx.

It it possible to override this detection by using the –backend option.

Using templates

The templates related options are described in the project templates documentation.

init sub-command

usage: buildenv init [-h] [--project PROJECT] [--shell {bash,cmd}] [--force]
                     [--no-ext] [--skip-ext SKIPPED_EXTENSIONS]

create venv and initialize extensions (implicitly done with shell and run
commands)

options:
  -h, --help            show this help message and exit
  --project PROJECT, -p PROJECT
                        project folder (default: .)
  --shell {bash,cmd}    force using specified shell (default: bash)
  --force, -f           force extensions re-initialization
  --no-ext              ignore all extensions on initialization
  --skip-ext SKIPPED_EXTENSIONS
                        skip specified extension(s) on initialization (can be
                        specified multiple times)

This sub-command creates the venv (if needed) and initializes extensions in the current project folder. It is implicitely called when using the shell or the run sub-commands.

If the initialization was previously fully completed, this command has no effect.

The initialization can be performed again only if the --force option is used.

It is possible to skip some extensions on init, by using the following options:

• --skip-ext EXT: skip a given extension (by its id)

• --no-ext: skip all extensions

shell sub-command

usage: buildenv shell [-h] [--project PROJECT] [--shell {bash,cmd}]
                      [--command COMMAND]

start an interactive shell with loaded build environment (default if no sub-
command is specified)

options:
  -h, --help            show this help message and exit
  --project PROJECT, -p PROJECT
                        project folder (default: .)
  --shell {bash,cmd}    force using specified shell (default: bash)
  --command COMMAND, -c COMMAND
                        command and arguments to be executed in build
                        environment

This sub-command invokes an interactive shell with the build environment enabled (i.e. original python venv + all enabled extensions provided by buildenv tool).

Just type exit to quit this interactive shell.

To be compatible with usual shells interface, it is possible to use the -c option to specify the command to be executed; e.g. as you can run bash -c echo hello, you can do the same with buildenv shell -c echo hello

Note

Running either buildenv shell -c echo hello command or buildenv run echo hello command behave exactly the same way.

run sub-command

usage: buildenv run [-h] [--project PROJECT] [--shell {bash,cmd}] ...

run command in build environment

positional arguments:
  CMD                   command and arguments to be executed in build
                        environment

options:
  -h, --help            show this help message and exit
  --project PROJECT, -p PROJECT
                        project folder (default: .)
  --shell {bash,cmd}    force using specified shell (default: bash)

This sub-command invokes the provided command with the build environment enabled (i.e. original python venv + all enabled extensions provided by buildenv tool), then returns.

list sub-command

usage: buildenv list [-h] [--project PROJECT] [--shell {bash,cmd}]

list installed packages in the current build environment

options:
  -h, --help            show this help message and exit
  --project PROJECT, -p PROJECT
                        project folder (default: .)
  --shell {bash,cmd}    force using specified shell (default: bash)

This sub-command lists all installed packages the current buildenv environment (similarly to pip list, except that, depending on used backend, the pip command is not always available).

lock sub-command

usage: buildenv lock [-h] [--project PROJECT] [--shell {bash,cmd}]

lock build environment packages versions

options:
  -h, --help            show this help message and exit
  --project PROJECT, -p PROJECT
                        project folder (default: .)
  --shell {bash,cmd}    force using specified shell (default: bash)

This command locks the current build environment. The locking behavior depends on the used environment backend.

unlock sub-command

usage: buildenv unlock [-h] [--project PROJECT] [--shell {bash,cmd}]

unlock build environment packages versions

options:
  -h, --help            show this help message and exit
  --project PROJECT, -p PROJECT
                        project folder (default: .)
  --shell {bash,cmd}    force using specified shell (default: bash)

This command unlocks the current build environment. The unlocking behavior depends on the used environment backend.

upgrade sub-command

usage: buildenv upgrade [-h] [--project PROJECT] [--shell {bash,cmd}]

upgrade build environment packages to their latest version

options:
  -h, --help            show this help message and exit
  --project PROJECT, -p PROJECT
                        project folder (default: .)
  --shell {bash,cmd}    force using specified shell (default: bash)

This sub-command upgrades packages installed in python venv to their latest available version.

Note

If the used environment backend is immutable, and this command is launched from an interractive shell, it will spawn a new sub-shell with the upgraded venv.