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.
Commands:
completion
config
containers
doctor Run all doctor checks and display results.
download Download artifacts from job runs.
experimental Experimental commands (may change or be removed without notice)
hello Show message to confirm credentials allow access to PROJECT_NAME
init Initialize a new Artefacts project.
login Log in to Artefacts using your browser.
logout Log out from Artefacts.
organization Manage Artefacts organizations.
project Manage Artefacts projects.
run Run JOBNAME locally
run-remote Run JOBNAME in the cloud by packaging local sources.
whoami Show current login status.
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 [ARGS]...
Options:
--help Show this message and exit.
install
Install shell completion to the current environment. The support is from Click, covering bash, zsh, fish and powershell at this time.
Usage:
artefacts completion install [OPTIONS]
Options:
--help Show this message and exit.
uninstall
Uninstall shell completion by removing invocation of our generated script.
Usage:
artefacts completion uninstall [OPTIONS]
Options:
--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.
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.
--description TEXT Optional description for this run
--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!
download
Download artifacts from job runs.
Usage:
artefacts download [OPTIONS] [JOB] [RUN_ID] [ARTIFACT]
artefacts download <job> Download all artifacts
artefacts download <job> --list List all artifacts
artefacts download <job> <run_id> Download all artifacts for run
artefacts download <job> <run_id> --list List artifacts for run
artefacts download <job> <run_id> <artifact> Download a specific artifact
Arguments:
JOB Job name (resolves to latest) or job UUID
RUN_ID Run ID (e.g., 0_reach_goal)
ARTIFACT Artifact filename (e.g., simulation.mcap)
Options:
-p, --project TEXT Project name
-c, --config TEXT Config file
-o, --output TEXT Output directory
-y, --yes Skip confirmation prompts
--list List artifacts instead of downloading
--help Show this message and exit.
Examples:
artefacts download basic
artefacts download basic --list
artefacts download basic 0_reach_goal simulation.mcap
experimental
Experimental commands (may change or be removed without notice)
Usage:
artefacts experimental [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
remote
Run JOBNAME on a remote TARGET machine via SSH/rsync.
The source code is synced to the target, then executed with --in-container.
A virtualenv with the matching artefacts version is auto-provisioned on the
remote. Assumes SSH key authentication is configured and rsync is available
on both machines.
Usage:
artefacts experimental remote [OPTIONS] JOBNAME TARGET [CONTAINER_ENGINE_ARGS]...
Options:
--config TEXT Artefacts configuration file.
--description TEXT Optional description for this run
--help Show this message and exit.
hello
Show message to confirm credentials allow access to PROJECT_NAME
If PROJECT_NAME is not provided, the function tries to get the name from any Artefacts configuration file available, and proceed with that name. Without a valid file or a name, the function reports a usage error.
Usage:
artefacts hello [OPTIONS] PROJECT_NAME
Options:
--config TEXT Artefacts configuration file.
--help Show this message and exit.
init
Initialize a new Artefacts project.
This command sets up everything you need to run tests with Artefacts:
- Logs you in (if needed)
- Selects the target organization/project
- Creates the project on Artefacts (if needed)
- Generates an artefacts.yaml config file
After running this, you can immediately run:
artefacts run <jobname> <command>
Usage:
artefacts init [OPTIONS]
Options:
-p, --project TEXT Project name in org/project format (default:
interactive)
--help Show this message and exit.
login
Log in to Artefacts using your browser.
This uses the OAuth Device Authorization flow:
- You’ll get a code to enter in your browser
- Log in with Google or email
- The CLI receives your credentials automatically
Usage:
artefacts login [OPTIONS]
Options:
--help Show this message and exit.
logout
Log out from Artefacts. Removes stored credentials from this machine.
Usage:
artefacts logout [OPTIONS]
Options:
--help Show this message and exit.
organization
Manage Artefacts organizations.
Usage:
artefacts organization [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
create
Create a new organization.
SLUG must be a valid organization identifier (lowercase letters, numbers, hyphens).
Usage:
artefacts organization create [OPTIONS] SLUG
Options:
--help Show this message and exit.
Example:
artefacts organization create my-new-org
project
Manage Artefacts projects.
Usage:
artefacts project [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
create
Create a new project. PROJECT_NAME must use org/project-name format.
Usage:
artefacts project create [OPTIONS] PROJECT_NAME
Options:
--help Show this message and exit.
Example:
artefacts project create myorg/my-new-project
info
Show information about a project.
PROJECT_NAME must use org/project-name format. If omitted, the value is read from the ‘project’ field of the local artefacts.yaml, or chosen from your logged-in account.
Usage:
artefacts project info [OPTIONS] PROJECT_NAME
Options:
--help Show this message and exit.
list
List projects in an organization.
If ORGANIZATION is omitted, it is read from the org part of the ‘project’ field in the local artefacts.yaml, or from your logged-in account.
Usage:
artefacts project list [OPTIONS] [ORGANIZATION]
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).
dockerfileallows 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 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, and --noisolation.
--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.
--track-resources Track and report resource usage time-series data to your
project in Artefacts. Current reports on CPU and memory
usage.
--show-stats Show resource usage summary statistics. Current reports
on CPU and memory usage.
--unsafe-teardown Safe teardown (default) makes sure all sub-processes
started by the run are terminated. Unsafe teardown
includes all sub-process PIDs detected during the run,
which may include PIDs reused by the OS (unsafe because
possibly processes that became unrelated could get
terminated, if owned by the same user). Please use at
your own risks.
--help Show this message and exit.
Without --in-container, this command runs directly in your current shell environment. If
your project depends on a virtual environment, activate it first — see
Using a Python virtual environment for your project.
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.
whoami
Show current login status.
Usage:
artefacts whoami [OPTIONS]
Options:
--help Show this message and exit.