Artenv

artenv is a tool for managing Artemis versions and analysis environments. Like pyenv or rbenv, it lets you switch Artemis environments and analysis directories with a single command.

Starting with v2, Apptainer container images can be handled as Artemis versions in addition to native installations. Using Apptainer images reduces the need to install ROOT, yaml-cpp, and Artemis separately on each machine. It also makes it easier to keep analysis environments consistent across machines and collaborators.

Concepts

artenv manages the Artemis runtime environment and the analysis directory separately.

• version: An Artemis runtime environment. This can be a native installation or an Apptainer image.
• environment: A working environment for each experiment or analysis. It stores the version to use, working directory, git repository, artlogin settings, and related configuration.
• template: A template used to create a new analysis directory. Templates are fetched from external git repositories.

First, register an Artemis version with artenv version install or artenv version register. Then register an analysis environment with artenv register. After registration, you can switch environments as follows.

artenv shell h424
artenv default h424

artenv shell <env> switches only the current shell. artenv default <env> sets the default environment used by newly opened shells.

Requirements

• bash
• git
• yq v4 with TOML support
• apptainer when using Apptainer versions

Shell integration is available for bash and zsh.

Installation

Clone the artenv repository.

git clone https://github.com/yano404/artenv.git ~/.artenv

Add the following to .bashrc or .zshrc.

export ARTENV_ROOT="$HOME/.artenv"
export PATH="$ARTENV_ROOT/bin:$PATH"
eval "$(artenv init -)"

Restart the shell.

exec $SHELL

Shell Completion

artenv provides completion scripts for bash and zsh.

For bash, source the completion script from .bashrc or a similar startup file.

source "${ARTENV_ROOT}/completions/artenv.bash"

For zsh, add the completion directory to fpath and initialize compinit.

fpath=("${ARTENV_ROOT}/completions" $fpath)
autoload -Uz compinit
compinit

Quick Start

1. Prepare an Artemis Version

If Apptainer is available, the easiest way is to pull a container image and register it as a version.

artenv version install latest

When a tag is specified, the URI, version name, and SIF destination can be omitted. In this example, a version named artemis_apptainer-latest is registered, and the image is saved to $ARTENV_ROOT/images/artemis_apptainer-latest.sif.

Available tags can be listed with:

artenv version install --list

You can also register an Apptainer image interactively.

$ artenv version install --apptainer
Enter the pull URI [oras://ghcr.io/yano404/artemis_apptainer:latest]>
Enter the version name> artemis-latest
Enter the path to save SIF [/home/yano/.artenv/images/artemis-latest.sif]>
Configuration:
  URI                    oras://ghcr.io/yano404/artemis_apptainer:latest
  VERSION                artemis-latest
  SIF                    /home/yano/.artenv/images/artemis-latest.sif
OK? (y/N)> y

If you already have a .sif image, you can register it as a version.

$ artenv version register artemis-apptainer
Select version type
1) native
2) apptainer
#? 2
Enter the path to Apptainer image (.sif)> /path/to/artemis.sif
artemis-apptainer was registered

For a native installation, register the paths to Artemis, ROOT, and yaml-cpp.

$ artenv version register artemis-native
Select version type
1) native
2) apptainer
#? 1
Enter the path to artemis> /path/to/artemis
Enter the path to root> /path/to/root
Enter the path to yaml-cpp> /path/to/yaml-cpp
artemis-native was registered

Use --native to build Artemis from source and register it.

$ artenv version install --native
Enter the path to root> /home/yano/local/root/v6.32.04
Enter the path to yaml-cpp> /home/yano/local/yaml-cpp/v0.8.0
Enter the path to the source of artemis> /home/yano/src/artemis/develop
Enter the path to build directory> /home/yano/build/artemis/artdev
Enter the install prefix> /home/yano/local/artemis/artdev
Configuration:
  ROOTSYS                /home/yano/local/root/v6.32.04
  YAML_CPP_LIB           /home/yano/local/yaml-cpp/v0.8.0/lib
  YAML_CPP_CMAKE         /home/yano/local/yaml-cpp/v0.8.0/lib/cmake
  ARTEMIS_SOURCE         /home/yano/src/artemis/develop
  BUILD_DIR              /home/yano/build/artemis/artdev
  INSTALL_PREFIX         /home/yano/local/artemis/artdev
OK? (y/N)> y
Will you register this version to artenv? (y/N)> y
Enter the version name> artemis-native
artemis-native was registered

2. Register or Create an Analysis Directory

After preparing a version, make the analysis directory available to artenv. If you already have an analysis directory, register it with artenv register. If you want to create a new analysis directory, use artenv new to create a working directory from a template, then register it.

Register an Existing Analysis Directory

If you already have an analysis directory, register it as an environment.

$ artenv register h424
Select the artemis version
1) artemis-native
2) artemis_apptainer-latest
#? 2
artemis_apptainer-latest was selected
Enter the path to working directory> /path/to/analysis_directory
Use artlogin? (y/n)> n
Enter the path to git repos (optional)> /path/to/git_repos or URL of git repos
h424 was registered

When using artlogin, a git repository must be specified.

Use artlogin? (y/n)> y
Enter the path to git repos (required)> /path/to/git_repos or URL of git repos

Activate the registered environment with:

artenv shell h424

For batch jobs or HPC setup scripts, environments can also be registered non-interactively.

artenv register h424 \
  --version artemis_apptainer-latest \
  --work /path/to/analysis_directory \
  --singleuser

For a shared artlogin environment, use --multiuser and --repos.

artenv register h424 \
  --version artemis_apptainer-latest \
  --work /path/to/shared_directory \
  --repos /path/to/upstream.git \
  --multiuser

Create an Analysis Directory from a Template

Use artenv new to create a new analysis directory. artenv new creates a basic directory structure from a template. The generated directory is only an analysis skeleton, so you still need to edit the detector configuration, steering files, parameter files, and related files for your experiment.

Before creating an analysis directory with artenv new, fetch template repositories.

artenv templates update

By default, artemis-templates is used as the default repository. List fetched templates with:

artenv templates ls

Create a working directory from a template.

artenv new /path/to/work -t default/standard

If the template name is unique, the repository name can be omitted.

artenv new /path/to/work -t standard

You can also omit -t and select a template interactively.

$ artenv new art
Select the template
1) default/standard
#? 1
created /path/to/art from template default/standard

After creating the directory, edit the necessary settings and register it as an environment.

artenv register h424 \
  --version artemis_apptainer-latest \
  --work /path/to/art \
  --singleuser

Command Structure

Since v2.1, commands are organized by target.

• environment commands: run directly under artenv, such as artenv register, artenv ls, artenv info, and artenv shell.
• version commands: run under the version group, such as artenv version ls, artenv version register, and artenv version install.
• template commands: run under the templates group, such as artenv templates ls and artenv templates update.
• utility commands: artenv doctor, artenv upgrade, artenv commands, and related commands.

The older flat commands remain as deprecated aliases. For example, artenv register-env is equivalent to artenv register, artenv register-version is equivalent to artenv version register, and artenv install is equivalent to artenv version install. For new documentation and workflows, grouped commands are recommended.

Set ARTENV_NO_DEPRECATION=1 to suppress deprecation notices.

Environment Commands

artenv ls

Lists registered environments. An environment marked with * is the currently active environment.

$ artenv ls
  artdev
  e545
* e559
  h424

Use --all to include archived environments.

artenv ls --all

artenv register

Registers an analysis environment.

artenv register <env-name> [options]

When executed, it asks you to select one of the registered Artemis versions and enter settings such as the working directory and artlogin configuration.

$ artenv register h424
Select the artemis version
1) artemis-native
2) artemis_apptainer-latest
#? 2
artemis_apptainer-latest was selected
Enter the path to working directory> /path/to/analysis_directory
Use artlogin? (y/n)> n
Enter the path to git repos (optional)> /path/to/git_repos or URL of git repos
h424 was registered

Each item can be specified with options. If all required options are given, the environment can be registered non-interactively, which is useful in HPC setup scripts and batch jobs.

artenv register h424 \
  --version artemis_apptainer-latest \
  --work /path/to/analysis_directory \
  --singleuser

Available options are:

option	meaning
--version <version>	Artemis version to use. It must be registered and not archived.
--work <dir>	Working directory. It must already exist.
--repos <url-or-path>	Path or URL of the git repository. Required with --multiuser.
--multiuser	Enables artlogin. Saved as use_artlogin = true.
--singleuser	Disables artlogin. Saved as use_artlogin = false.

On a TTY, omitted items are entered interactively as before. On a non-TTY, interactive input is not available, so --version and --work are required. If --multiuser is not specified, the environment is registered as a single-user environment.

Register a shared artlogin environment as follows.

artenv register h424 \
  --version artemis_apptainer-latest \
  --work /path/to/shared_directory \
  --repos /path/to/upstream.git \
  --multiuser

artenv info

Displays details of an environment. If no argument is given, it displays the currently active environment.

artenv info
artenv info h424

Example of a native environment:

$ artenv info e559
- env: e559
- artemis version: artemis-e559
  - artemis: /home/quser/local/artemis/artemis-e559 [OK]
  - root: /home/quser/local/root/v6.26.10 [OK]
  - yaml-cpp lib: /home/quser/local/yaml-cpp/yaml-cpp-0.6.3/lib [OK]
  - yaml-cpp cmake: /home/quser/local/yaml-cpp/yaml-cpp-0.6.3/lib/cmake [OK]
- analysis directory: /home/yano/work/e559/art [OK]
- working directory: /home/yano/work/e559/art [OK]
- git repository:
- use artlogin: NO

Example of an Apptainer environment:

$ artenv info e559-apptainer
- env: e559-apptainer
- artemis version: artemis-apptainer
  - type: apptainer
  - image: /path/to/artemis.sif [OK]
  - binds: <none>
- analysis directory: /home/yano/work/e559/art [OK]
- working directory: /home/yano/work/e559/art [OK]
- git repository:
- use artlogin: NO

artenv shell

Switches the environment used in the current shell. If no argument is given, it prints the currently active environment.

artenv shell h424
artenv shell

artenv default

Sets the default environment used by newly opened shells. If no argument is given, it prints the current default environment.

artenv default h424
artenv default

artenv new

Creates a working directory from a template.

artenv new <dir> -t <template>

<template> is specified as <repo>/<template>. If the template name is unique, the repository name can be omitted.

artenv new /path/to/work -t default/standard
artenv new /path/to/work -t standard

Use --multiuser to create a project skeleton shared by multiple users. In this mode, artenv new creates only the shared directory and the upstream bare repository; it does not register an environment.

artenv new --multiuser /shared/myproject -t default/standard

artenv edit

Opens the environment TOML config with $VISUAL or $EDITOR. On save, the file is validated as TOML.

artenv edit h424
artenv edit

artenv remove

Removes an environment.

$ artenv remove e559
Remove environment 'e559'? (y/N)> y
e559 was removed

artenv archive / unarchive

Archives an unused environment without deleting it. Archived environments are hidden from the normal artenv ls output, but they can still be referenced and activated.

$ artenv archive e545
e545 was archived

$ artenv ls
* e559
  h424

$ artenv ls --all
  e545 (archived)
* e559
  h424

$ artenv unarchive e545
e545 was unarchived

Version Commands

artenv version

Displays the currently active Artemis version. artenv version current can be used for the same purpose.

$ artenv version
artemis-e559

artenv version ls

Lists registered Artemis versions. A version marked with * is the currently active version.

$ artenv version ls
* artemis-e559
  artemis-root-6.26.10
  develop

Use --all to include archived versions.

artenv version ls --all

artenv version register

Registers an existing native installation or .sif image as an Artemis version.

artenv version register <version-name>

First, select the version type.

Select version type
1) native
2) apptainer
#?

For a native version, enter the paths to the installed Artemis, ROOT, and yaml-cpp on the host. For an Apptainer version, enter the path to an existing .sif image.

artenv version install

Prepares and registers an Artemis version. It supports pulling an Apptainer image, building a native installation, and updating an existing Apptainer image.

artenv version install latest
artenv version install --list
artenv version install --apptainer
artenv version install --native
artenv version install --update artemis-latest

--update re-pulls an Apptainer version registered by artenv version install. It checks the registry digest and overwrites the SIF after confirmation if an update is available.

$ artenv version install --update artemis-latest
Checking registry...
Update:
  VERSION                artemis-latest
  URI                    oras://ghcr.io/yano404/artemis_apptainer:latest
  SIF                    /home/yano/.artenv/images/artemis-latest.sif
  DIGEST                 sha256:121ea823...
OK? (y/N)> y

artenv version info

Displays version configuration. If no argument is given, it displays the currently active version.

artenv version info
artenv version info artemis-latest

artenv version edit

Opens the version TOML config with $VISUAL or $EDITOR. On save, the file is validated as TOML.

artenv version edit artemis-latest
artenv version edit

artenv version remove

Removes a registered version. If any environment uses that version, removal is stopped.

$ artenv version remove artemis-e559
artenv: version 'artemis-e559' is used by the following environments:
  - e545
remove these environments first, or use --force

Use --purge to also remove the SIF under $ARTENV_ROOT/images when removing an Apptainer version.

$ artenv version remove --purge artemis-latest
Remove version 'artemis-latest'? (y/N)> y
removed image: /home/yano/.artenv/images/artemis-latest.sif
artemis-latest was removed

artenv version archive / unarchive

Versions can be archived in the same way as environments. Archived versions are hidden from artenv version ls, but they are not deleted.

artenv version archive artemis-old
artenv version ls --all
artenv version unarchive artemis-old

Template Commands

Templates used by artenv new are cached under $ARTENV_ROOT/templates/<repo>/. Template repositories are configured in $ARTENV_ROOT/template-repos/<name>.toml.

artenv templates update

Clones or updates configured template repositories. If no argument is given, all enabled repositories are processed.

artenv templates update
artenv templates update default

artenv templates ls

Lists fetched templates in the form <repo>/<template>.

artenv templates ls

artenv templates repos

Lists configured template repositories.

artenv templates repos

Template Repository Configuration

A template repository is configured with a TOML file like the following.

$ARTENV_ROOT/template-repos/default.toml

[repo]
url = "https://github.com/yano404/artemis-templates.git"
enabled = true
ref = "main"
description = "Artemis analysis templates"

template-repos/default.toml is created from share/template-repos/default.toml on first use. Because it is treated as runtime data, it can be edited for your own environment while avoiding conflicts during git pull.

Authentication for private repositories is left to git SSH keys or credential helpers. artenv does not store credentials.

Local Templates

Templates placed under $ARTENV_ROOT/templates/local/ can be used as local/<template>. The local namespace is not processed by artenv templates update.

Multi-user Projects

artenv new --multiuser is a mode for creating a project skeleton shared by multiple users. Unlike normal artenv new, it does not expand a template directly into a working directory. Instead, it creates an empty shared directory and an upstream bare repository initialized from the template.

artenv new --multiuser /shared/myproject -t default/standard

This command creates:

• /shared/myproject: an empty shared directory. Its mode is 2770, with setgid and group write enabled.
• /shared/myproject/myproject.git: an upstream bare repository seeded from the template.

Use --repo <path> to change the upstream repository location. As of v2.3.0, only local paths are supported; URLs and remote destinations such as user@host:path are rejected.

artenv new --multiuser /shared/myproject \
  --repo /shared/repos/myproject.git \
  -t default/standard

artenv new --multiuser does not register an environment. After running it, register the environment by specifying the shared directory and upstream repository shown by the command.

artenv register myproject \
  --version <version> \
  --work /shared/myproject \
  --repos /shared/myproject/myproject.git \
  --multiuser

Each user activates the multi-user environment and then runs artlogin <name>. artlogin creates a per-user checkout under the shared directory, so users share the same upstream repository history while keeping separate working directories.

Apptainer Support

When an environment using an Apptainer version is active, the following commands are automatically executed inside the container.

• artemis
• cmake
• make
• root

Use artexec to run arbitrary commands inside the container.

artexec ./make.sh
artexec bash
artexec which root

ART_WORK_DIR is automatically bind-mounted into the container. If additional paths need to be bind-mounted, add binds to the environment config.

$ARTENV_ROOT/envs/h424.toml

[env]
version = "artemis-latest"
work = "/path/to/work"
binds = ["/extra/path1", "/extra/path2"]

In v2.3.0, artlogin is also available for Apptainer environments. For environments with use_artlogin = true, USE_ARTLOGIN=YES is set and the artlogin function is defined on the host side. The per-user checkout created by artlogin is placed under the shared working directory, so the same directory is visible from the container wrappers.

Configuration Files

Settings are stored as TOML files under $ARTENV_ROOT.

Version Configuration

Example of a native version:

$ARTENV_ROOT/versions/artemis-native.toml

[version]
type = "native"
artsys = "/path/to/artemis"
rootsys = "/path/to/root"
yamllib = "/path/to/yaml-cpp/lib"
yamlcmake = "/path/to/yaml-cpp/cmake"

Example of an Apptainer version:

$ARTENV_ROOT/versions/artemis-latest.toml

[version]
type = "apptainer"
uri = "oras://ghcr.io/yano404/artemis_apptainer:latest"
image = "/path/to/artemis.sif"
digest = "sha256:..."

uri and digest are saved when the version is registered by artenv version install. When an existing .sif is registered by artenv version register, only image is stored.

Environment Configuration

$ARTENV_ROOT/envs/h424.toml

[env]
version = "artemis-latest"
work = "/path/to/work"
git_repos = "/path/to/git_repos"
use_artlogin = false
binds = ["/extra/path"]

Environments with use_artlogin = true are treated as multi-user environments. binds is used for environments that use an Apptainer version.

Utility Commands

artenv doctor

Checks registered environments and the state of the artenv store.

artenv doctor
artenv doctor h424
artenv doctor --all
artenv doctor --orphans

--orphans checks the whole store and reports unreferenced .sif images, environments that refer to missing versions, and *.artlogin.sh files without corresponding environments. If a problem is found, the command exits with a non-zero status.

artenv migrate

Migrates v1 symlink-based settings to v2 TOML-based settings.

artenv migrate

artenv upgrade

Updates artenv itself to the latest release tag.

artenv upgrade

It fetches tags from the remote repository and checks out the latest vX.Y.Z tag. Ending up on a detached HEAD at a release tag is intentional.

artenv upgrade updates only tracked core files. Runtime data such as versions/, envs/, templates/, template-repos/, and images/ are gitignored and are not changed.

If tracked files have local changes, artenv upgrade stops without stashing them. Save those changes yourself before running it again if needed.

git -C "$ARTENV_ROOT" stash
artenv upgrade
git -C "$ARTENV_ROOT" stash pop

Apptainer images are not updated by artenv upgrade. To update an image, run artenv version install --update <version> separately.

artenv commands

Lists available commands.

artenv commands

artenv --version

Displays the artenv version.

$ artenv --version
artenv v2.3.0 (09fe58c)