CLI Reference
This page provides documentation for our command line tools.
artefacts
A command line tool to interface with ARTEFACTS
Usage:
artefacts [OPTIONS] COMMAND [ARGS]...
Options:
--version Show the version and exit.
--help Show this message and exit.
config
Usage:
artefacts config [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
add
Set configuration for PROJECT_NAME
Usage:
artefacts config add [OPTIONS] PROJECT_NAME
Options:
--help Show this message and exit.
delete
Delete configuration for PROJECT_NAME
Usage:
artefacts config delete [OPTIONS] PROJECT_NAME
Options:
--help Show this message and exit.
path
Get the configuration file path
Usage:
artefacts config path [OPTIONS]
Options:
--help Show this message and exit.
completion
Install or uninstall shell completion for the artefacts CLI. Supports bash, zsh, and fish on Linux and macOS. Windows support is experimental with PowerShell.
We have tested completion with installs using pip, uv tools and pipx with
no problem. Other install methods like uv, pixi or conda do not work
currently because command prefixing seems to break (e.g. uv run artefacts run).
Usage:
artefacts completion [OPTIONS] COMMAND
Options:
--help Show this message and exit.
install
Install shell completion to the current environment.
Usage:
artefacts completion install [OPTIONS]
Options:
--help Show this message and exit.
uninstall
Uninstall shell completion by removing invocation of our setup script from your shell configuration.
Usage:
artefacts completion uninstall [OPTIONS]
Options:
--help Show this message and exit.
containers
Usage:
artefacts containers [OPTIONS] COMMAND [ARGS]...
Options:
--debug / --no-debug
--help Show this message and exit.
build
Usage:
artefacts containers build [OPTIONS]
Options:
--path TEXT [Deprecated since 0.8.0; please see --root] Path to the
root of the project.
--root TEXT Path to the root of the project.
--dockerfile TEXT Path to a custom Dockerfile. Defaults to Dockerfile under
`path` (see option of the same name).
--name TEXT [Deprecated since 0.8.0; not used and will disappear
after 0.8.0] Name for the generated image
--config TEXT Path to the Artefacts configuration file. It defaults to
`./artefacts.yaml`
--only OPTIONAL Optional list of job names to process. The default is to
process all jobs.
--help Show this message and exit.
check
Usage:
artefacts containers check [OPTIONS] IMAGE_NAME
Options:
--help Show this message and exit.
run
Usage:
artefacts containers run [OPTIONS] JOBNAME [ENGINE_ARGS]...
Options:
--config TEXT Path to the Artefacts configuration file. It defaults to
`./artefacts.yaml`
--with-gui BOOLEAN Show any GUI if any is created by the test runs. By
default, UI elements are run but hidden---only test logs
are returned. Please note GUI often assume an X11
environment, typically with Qt, so this may not work
without a appropriate environment.
--help Show this message and exit.
doctor
Run a quick health check that displays an overview of the Artefacts features and extensions that are immediately available on your system. This command provides a concise summary of supported modules, loaded plugins, and configuration status, helping you verify that the CLI environment is ready for use.
Usage:
artefacts doctor
Options:
--help Show this message and exit.
Sample Output:
Checking run environment...
Basic requirements
tar available on PATH..........................................🟢
gzip available on PATH.........................................🟢
Artefacts API reachable........................................🟢
At this point `artefacts` is functional for local and remote runs.
We next check recommended and extra settings available.
Recommended settings
In a Python virtual environment (standard).....................🟢
Shell completion installed.....................................🟡
GPU available..................................................🟢
Docker available...............................................🟢
Docker executable by your user.................................🟢
Docker can use a GPU...........................................🟢
Robotics Frameworks and Simulators tested on Artefacts
ROS2 available in this session (ROS_VERSION set)...............⚫️
dora available on PATH.........................................🟢
gz available on PATH...........................................⚫️
Recommended optional features marked with 🟡 require additional settings.
🟢 You are all set!
hello
Show message to confirm credentials allow access to PROJECT_NAME
Usage:
artefacts hello [OPTIONS] PROJECT_NAME
Options:
--help Show this message and exit.
run
Run JOBNAME locally
- Directly in the shell by default.
- Inside a packaged container when using the –in-container option.
In container mode: * Images are built automatically if missing. * Currently 1
image per job found in artefacts.yaml. * Images are rebuilt at each run
(relatively fast when no change). * dockerfile allows to specify an
alternative Dockerfile.
Usage:
artefacts run [OPTIONS] JOBNAME [CONTAINER_ENGINE_ARGS]...
Options:
--config TEXT Artefacts configuration file.
--dryrun Run with no tracking nor test execution
--nosim Skip configuring a simulator resource provided by
Artefacts
--noupload Do not upload to Artefacts files generated during a run
(e.g. rosbags)
--noisolation Break the 'middleware network' isolation between the
test suite and the host (in ROS1: --reuse-master flag;
in ROS2: --disable-isolation flag). Primarily for
debugging
--description TEXT Optional description for this run
--skip-validation Skip configuration validation, so that unsupported
settings can be tried out, e.g. non-ROS settings or
simulators like SAPIEN.
--in-container [Experimental] Run the job inside a package container.
The container image is build if it does not exist yet,
with default name as "artefacts" (please use --with-
image to override the image name). This option overrides
(for now) --dryrun, --nosim, --noisolation and
--description.
--dockerfile TEXT [Experimental] Path to a custom Dockerfile. Defaults to
Dockerfile in the run directory. This flag is only used
together with `--in-container`
--with-image TEXT [Deprecated and unused from 0.8.0; Image names are now
internally managed] Run the job using the image name
passed here. Only used when running with --in-container
set.
--no-rebuild [Experimental] Override the default behaviour to always
rebuild the container image (as we assume incremental
testing).
--with-gui Show any GUI if any is created by the test runs. By
default, UI elements are run but hidden---only test logs
are returned. Please note GUI often assume X11 (e.g.
ROS), typically with Qt, so this may not work without a
appropriate environment.
--help Show this message and exit.
run-remote
Run JOBNAME in the cloud by packaging local sources. if a .artefactsignore
file is present, it will be used to exclude files from the source package.
Usage:
artefacts run-remote [OPTIONS] JOBNAME
Options:
--config TEXT Artefacts configuration file.
--description TEXT Optional description for this run
--skip-validation Skip configuration validation, so that unsupported
settings can be tried out, e.g. non-ROS settings or
simulators like SAPIEN.
--help Show this message and exit.