The gws CLI
The gws command-line interface is the main entry point for developing on the Constellab platform. It bundles everything you need to run and test the server, scaffold new code (bricks, tasks, apps), inspect the lab (resources, scenarios, databases), and manage your development environment. Every command is a subcommand of a command group — for example gws server run or gws brick generate.
The general shape of any command is:
gws [GLOBAL OPTIONS] [ARGUMENTS] [OPTIONS]
Add -h or --help at any level to see the available commands and options, for example gws --help, gws server --help, or gws server test --help.
Global options
These options apply to the CLI as a whole and are placed before the command group.
# List every installed brick and its version
gws --version
# Run any command with verbose logging
gws --log-level=DEBUG server run
Command groups
The CLI is organized into command groups by purpose. Each group has its own documentation page describing every command, its options, and examples.
Conventions across the CLI
- Confirmation on destructive actions: irreversible commands (such as
dev-env reset, scenario start, and scenario stop) require an explicit --yes / -y flag or an interactive confirmation. - JSON output: inspection commands accept
--format json for machine-parseable output, in addition to the default human-readable tables. - Database targeting: commands that touch a database accept
--db <brick_name>, defaulting to gws_core. - Current directory as default: many
brick commands operate on the brick in the current folder when no path is given.
Installation
The CLI ships as the gws-cli package. To build and install it from source, run the following from the brick root:
cd gws_cli
pip install .
To test the CLI locally without installing, run it directly from source:
python gws_cli/gws_cli/main_cli.py server run
Before testing a fresh local build, remove any previous artifacts and uninstall a pre-installed copy:
rm -rf gws_cli/dist
pip uninstall gws-cli -y
