# CLI Reference Site [llms.txt](/llms.txt) --- 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 Download all artifacts artefacts download --list List all artifacts artefacts download Download all artifacts for run artefacts download --list List artifacts for run artefacts download 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: 1. Logs you in (if needed) 2. Selects the target organization/project 3. Creates the project on Artefacts (if needed) 4. Generates an artefacts.yaml config file After running this, you can immediately run: artefacts run **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: 1. You'll get a code to enter in your browser 2. Log in with Google or email 3. 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). * `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 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. > [!NOTE] > 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](/getting-started/#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. ---