Skip to content

Latest commit

 

History

History
665 lines (540 loc) · 50.6 KB

cli.md

File metadata and controls

665 lines (540 loc) · 50.6 KB

The eb-local command

eb-local builds and installs software with EasyBuild on top of EESSI 2026.06, into a directory you or your project own, and prints the shell lines that load EESSI and what you installed. This page describes the static binary on this branch's main. The 1.x Bash script, frozen until it is removed in 4.0.0, has a build, env, dev and clean only.

Synopsis

eb-local [OPTION]... <easyconfig> [eb options]
eb-local [OPTION]... --explain <easyconfig> [eb options]
eb-local eb [--] [eb options]
eb-local --explain eb [--] [eb options]
eb-local [OPTION]... env [--strict] [--json]
eb-local [OPTION]... dev [--strict] [--pure] [--json] [--buildenv MODULE] [--envrc] [--lock | --locked] [MODULE...]
eb-local rpath-wrappers [--for FAMILY | --unwrapped]
eb-local check [--recursive] [--quiet] [--json] FILE...
eb-local check (--module NAME/VERSION... | --dev | --prefix DIR) [--recursive] [--quiet] [--json]
eb-local [OPTION]... submit [--on NAME,...] [--print] <easyconfig> [eb options]
eb-local [OPTION]... list [--json | --missing] [NAME[/VERSION]...]
eb-local [OPTION]... doctor [--json] [--strict] [--workspace PATH] [--cvmfs] [--cvmfs-parallel N] [--mpi]
eb-local lmod-cache --modulepath DIR[:DIR] --cache-dir DIR --timestamp FILE [--spider CMD] [--verify]
eb-local lmod-cache --prefix DIR [--eessi-version VER] [--update-cmd CMD] [--dry-run]
eb-local modulerc --module-tree DIR [--default MODULE]...
                   [--alias NAME=MODULE]... [--hide MODULE]... [--dry-run | --check] [--json]
eb-local [OPTION]... clean [--logs-older-than DAYS] [--no-logs] [--sources] [--workspaces]
                           [--dry-run] [--delete] [--json]
eb-local [OPTION]... config [--check | --env | --get KEY] [--json]
eb-local [OPTION]... profiles [--json]
eb-local [OPTION]... uninstall NAME/VERSION... [--target TARGET] [--dry-run] [--delete] [--usage-log FILE]
eb-local [OPTION]... restore NAME/VERSION... [--dry-run]
eb-local site [list | show NAME | install NAME | check FILE] [--set KEY=VALUE]... [--to FILE] [--force]
eb-local overlay materialize --overlay FILE --base PATH [--out-dir DIR] [--dry-run | --check]
eb-local overlay bump [--eb-stack PATH] [--] [eb-stack package bump options...]
eb-local overlay plan [--eb-stack PATH] [--] [eb-stack package plan options...]
eb-local help | -h | --help | --version

OPTION is one of --profile NAME, --project DIR and --config FILE, which the options below describe.

eb-local --help prints:

eb-local: install and build software on top of EESSI 2026.06, into a
directory you own.

  eb-local <easyconfig> [eb options]   build and install with EasyBuild
  eb-local --explain <easyconfig> [eb options]
                                       the commands that build runs, as shell lines,
                                       its checks as comments; creates and runs nothing
  eb-local eb [--] [eb options]        load EESSI-extend and run eb; no site file, no Slurm job.
                                       At most one of EESSI_USER_INSTALL, EESSI_PROJECT_INSTALL,
                                       EESSI_SITE_INSTALL, EESSI_CVMFS_INSTALL may be set, and a
                                       present empty value counts as set; with none set, the
                                       module uses $HOME/eessi and nothing is exported.
                                       eb runs only if the module's install path is in the
                                       tree that variable selects
  eb-local --explain eb [--] [eb options]
                                       the script eb runs, with its arguments; runs nothing
  eb-local env [--strict] [--json]       lines that make your installed modules visible;
                                       --strict exits when the EESSI init file is missing
                                       (also when EB_LOCAL_ENV_STRICT=1)
  eb-local dev [--strict] [--pure] [--json] [--buildenv MODULE] [--envrc] [--lock | --locked] [MODULE...]
                                       the same, plus MODULEs and a build environment,
                                       so gcc, make, cmake and meson just work;
                                       --strict exits when the EESSI init file is missing
                                       (also when EB_LOCAL_ENV_STRICT=1);
                                       --buildenv names the build environment to load;
                                       --json prints the change as JSON, for env too;
                                       --envrc writes that line to .envrc for direnv;
                                       --pure purges loaded modules and LD_* first;
                                       --lock records what loads in eb-local.lock,
                                       --locked loads exactly that again
  eb-local rpath-wrappers [--for FAMILY | --unwrapped]
                                       lines that put RPATH wrappers for the compilers
                                       on PATH first; dev uses them when no build
                                       environment exists for the loaded compilers.
                                       --unwrapped: only clang, clang++, flang,
                                       flang-new and ld.lld, where no wrapper comes
                                       first; dev adds them after a build environment
  eb-local check [--recursive] [--quiet] [--json] FILE...
                                       whether a program or library built here runs here:
                                       its architecture, loader, run paths and libraries;
                                       --recursive audits resolved DT_NEEDED libraries too
  eb-local check (--module NAME/VERSION... | --dev | --prefix DIR) [--recursive] [--quiet] [--json]
                                       the same for every ELF file in those installations,
                                       the dev tree, or DIR; a file that is not ELF is skipped.
                                       --quiet prints a file only when it has a problem
  eb-local submit [--on NAME,...] [--print] <easyconfig> [eb options]
                                       one batch job per node type the site file lists
                                       in build.node_types, each building the recipe for
                                       its CPU target; --print shows the jobs instead.
                                       Deprecated, and removed in 4.0.0: --explain
                                       prints an sbatch line for each node type
  eb-local list [--json | --missing] [NAME[/VERSION]...]
                                       what you installed, for which CPU targets, and
                                       what this node's target lacks; --json prints one
                                       line of JSON with schema_version 1; --missing
                                       lists only modules missing on this node's target
  eb-local doctor [--json] [--strict] [--workspace PATH] [--cvmfs] [--cvmfs-parallel N] [--mpi]
                                       what in this shell, node or configuration would
                                       stop a build or a module load; changes nothing;
                                       --json prints one line of JSON with schema_version 1.
                                       --strict exits 1 on warn lines as well as FAIL.
                                       --workspace probes PATH without starting a build.
                                       --cvmfs checks the CernVM-FS client.
                                       --cvmfs-parallel N (1 to 8) reads repository
                                       metadata from N tasks inside an allocation.
                                       --mpi reports libfabric and UCX, and inside an
                                       allocation runs a two-rank hello per approved transport
  eb-local lmod-cache --modulepath DIR[:DIR] --cache-dir DIR
                      --timestamp FILE [--spider CMD] [--verify]
                                       write Lmod's spiderT.lua for those module
                                       directories, and a timestamp one second
                                       older, so Lmod trusts the cache. A spider
                                       that fails leaves both files unchanged.
                                       --spider names the spider program;
                                       default: spider. --verify compares
                                       cached and uncached module inventories.
                                       Does not read the site file
  eb-local lmod-cache --prefix DIR [--eessi-version VER] [--update-cmd CMD]
                      [--dry-run]
                                       for every CPU target under DIR, refresh
                                       .lmod/cache with Lmod's cache updater
                                       (like EESSI's update_lmod_caches.sh).
                                       --dry-run lists targets; existing
                                       --modulepath mode is unchanged
  eb-local modulerc --module-tree DIR [--default MODULE]...
                     [--alias NAME=MODULE]... [--hide MODULE]... [--dry-run | --check] [--json]
                                       write DIR/.modulerc.lua with the
                                       defaults, aliases and hidden versions named;
                                       preserve other lines. --dry-run prints the file;
                                       --check reports drift and writes nothing;
                                       --json prints one line of JSON with schema_version 1
  eb-local clean [--logs-older-than DAYS] [--no-logs] [--sources] [--workspaces]
                 [--dry-run] [--delete] [--json]
                                       remove what eb-local left behind; --no-logs
                                       leaves the logs; --json prints one line of JSON
  eb-local config [--check | --env | --get KEY] [--json]
                                       the settings in force and where each came from;
                                       --check also reads every secret (values not shown);
                                       --env prints them as EB_LOCAL_* lines for export;
                                       --get prints one resolved key's value (secret sources only);
                                       --json is for the default output or --check, not --env or --get
  eb-local profiles [--json]           the profiles the configuration defines; --json
                                       prints one line of JSON with schema_version 1
  eb-local uninstall NAME/VERSION... [--target TARGET] [--dry-run] [--delete]
                                       [--usage-log FILE]
                                       remove an installation and its module file, for
                                       every CPU target (or only TARGET), to the trash with
                                       rtrash. --usage-log asks eb-keep-logs whether the
                                       prefix is in FILE, and removes nothing when that exits 2
  eb-local restore NAME/VERSION... [--dry-run]
                                       bring them back from the trash, read-only again
  eb-local site [list | show NAME | install NAME | check FILE] [--set KEY=VALUE]... [--to FILE] [--force]
                                       a site file from a template built in, or from a
                                       template file (a NAME with a slash); install
                                       writes config.toml beside this program, mode 644;
                                       site list takes --json for machine-readable output
  eb-local overlay materialize --overlay FILE --base PATH [--out-dir DIR] [--dry-run | --check]
                                       apply a digest-pinned overlay; writes a materialized
                                       easyconfig and provenance.toml, or refuses when the
                                       base digest changed; --dry-run validates and lists
                                       the outputs without writing them; --check reports drift
                                       and writes nothing
  eb-local overlay bump [--eb-stack PATH] [--] [eb-stack package bump options...]
  eb-local overlay plan [--eb-stack PATH] [--] [eb-stack package plan options...]
                                       run eb-stack package bump or plan by subprocess only
  eb-local help | --version

Every command but eb takes --profile NAME, --project DIR (a shared project
directory instead of $HOME/eessi) and --config FILE. Use env and dev with eval:

  eval "$(eb-local env)"
  eval "$(eb-local dev FFTW/3.3.10-GCC-15.2.0)"

Configuration: the site file (the first of config.toml beside this program,
/etc/eb-local/config.toml, eb-local.conf beside this program and
/etc/eb-local.conf), then ~/.config/eb-local/config.toml,
then EB_LOCAL_* variables (EB_LOCAL_SECRET_NAME=SOURCE for a secret),
then options. Builds use the allocation's own
node-local mount; a successful build removes its workspace unless
EB_LOCAL_KEEP_WORK=1. Secrets reach eb's environment only, and logs
written during a build are cleaned of them. A build gets every secret,
unless build.secrets or EB_LOCAL_BUILD_SECRETS names the ones it gets.

--config FILE, or EB_LOCAL_CONFIG=FILE without it, is read in place of the
site file when root or this program's owner owns it, otherwise in place of
your ~/.config/eb-local/config.toml when you own it; the other file is
still read, and only a site file may set the storage settings.

Arguments

The first word names the command. Without a command, the words go to eb in the order given, the easyconfig and eb's own options, and eb-local builds. --profile, --project, --config, -h and --help are eb-local's wherever they come, and --explain is eb-local's before the first word that goes to eb. After eb, every word goes to eb except -h and --help; after eb --, every word does, so eb-local eb -- --help prints eb's help. --env as the first word is env, as in the 1.x script.

Options

Option Meaning
--profile NAME Use the profile NAME, in place of EB_LOCAL_PROFILE and default_profile.
--project DIR Install into, and load from, the project directory DIR instead of the prefix, as the project setting does.
--config FILE Read FILE in place of the site file when root or the owner of this program owns it; otherwise in place of ~/.config/eb-local/config.toml, when you own it. The other file is still read.
--explain Before an easyconfig, or before eb: print what would run, and create and run nothing.
-h, --help, help Print the usage on stdout and exit 0.
--version Print the version line on stdout and exit 0.
--json On list, check, doctor, modulerc, clean, config, profiles, and site list: print one line of JSON with schema_version 1 on stdout instead of the text report. Not with config --env or config --get.

Each option that takes a value also takes it after an equals sign, as in --profile=gpu. An empty value is refused either way, with OPTION needs a value. eb refuses --profile, --project and --config, since it reads the install mode from the environment; site, check and rpath-wrappers take them and do not use them.

The version line names the program, its version, the target and optimize mode of the build, the Zig version, and the commit given to zig build as -Dcommit, or unknown. Built with zig build --release=safe -Dcommit=0123abc, it prints:

eb-local 3.2.0 (x86_64-linux-musl, safe, zig 0.17.1, 0123abc)

Since v3.1.0, no CLI flag was removed or renamed. The command line added --strict and --json on env, --json, --envrc, --pure, --lock and --locked on dev, --unwrapped on rpath-wrappers, --recursive on check, --cvmfs, --cvmfs-parallel and --mpi on doctor, lmod-cache (single-target and --prefix modes, with --verify), modulerc, overlay, site check, and --target and --usage-log on uninstall.

Commands

A build

Build <easyconfig> with EasyBuild through EESSI-extend, for the CPU target of this node, and install it into the prefix, or into the project directory with --project. A build runs only inside a Slurm job, in a workspace of its own in the job's node-local mount, <storage.node_local_root>/<storage.node_local_mount>. Outside a job it builds nothing: it names the allocation the site suggests, and an sbatch line for each node type in build.node_types, and exits 2. Its first line names the command that prints what it runs:

eb-local: what this runs: eb-local --explain pigz-2.8-GCCcore-15.2.0.eb --robot

A build that succeeds removes its workspace, unless EB_LOCAL_KEEP_WORK is 1, and ends with the line that makes what it installed visible:

eb-local: done. To use the modules in a new shell or job:
  eval "$(eb-local env)"

A failed build keeps its workspace until the job ends. A build exits with eb's status. In a shell without a module command, a build, env and dev source the first Lmod init they can read: $LMOD_PKG/init/bash, or /usr/share/lmod/lmod/init/bash with LMOD_PKG unset, then /etc/profile.d/lmod.sh, then EESSI's own, the one eb-local eb sources; eb-local doctor names the one a build would source. Stopped by a signal, it removes the secret values from the logs and then stops with the same signal.

--explain

Print the script a build runs, and create and run nothing, inside a Slurm job or outside one. The output is, in order: comments that say where the build installs, the checks it makes first, and whether each secret reaches eb; the variables it sets for the script, with W standing for its workspace; a set -- line with the script's arguments; and the script itself. With build.node_types in the site file, the comments also hold an sbatch line for each node type, which runs the same build as a batch job there.

The script does what you would type to use EESSI-extend by hand: clear the install variables a login shell may carry, set one of EESSI_USER_INSTALL or EESSI_PROJECT_INSTALL, load EESSI/2026.06, then EESSI-extend, which reads that variable as it loads, check that the install path EESSI-extend set is in <prefix>/versions, and run eb. With W set to a workspace a build made, which holds build, cache, cargo, source-index and tmp, such as one a failed build kept or one kept with EB_LOCAL_KEEP_WORK=1, bash runs the printed text as a build runs its script; the checks before it and the cleaning of logs after it are eb-local's own.

eb

Load EESSI and EESSI-extend in a bash with no profile and no rc file, and run eb with the arguments, with no site file and no Slurm job. EESSI-extend takes the install mode from the install variables, of which at most one of EESSI_USER_INSTALL, EESSI_PROJECT_INSTALL, EESSI_SITE_INSTALL and EESSI_CVMFS_INSTALL may be set; a present, empty one counts. With more than one set, eb runs nothing and the command exits 3.

Variable Mode Prefix Process umask
EESSI_USER_INSTALL user created when the value is not empty 077
EESSI_PROJECT_INSTALL project not created; its owner sets the group and the setgid bit 002
EESSI_SITE_INSTALL site the init's site software path 022
EESSI_CVMFS_INSTALL cvmfs the EESSI software path 022
none user $HOME/eessi, which need not exist before the module loads 077

The module sets EASYBUILD_UMASK to the same end, with the sticky bit for a user prefix and the setgid bit for a project, and eb gets no --umask, so that value stands. An argument of eb's still overrides it: --umask=022 is what a user-namespace build needs when Lmod, running as uid 0, skips a directory that others cannot search. The module's help text says $HOME/EESSI; on EESSI 2026.06 it uses $HOME/eessi. Before EESSI-extend loads, the script unsets host Rust and CMake wrappers, such as RUSTC_WRAPPER and CMAKE_C_COMPILER_LAUNCHER, and puts the compatibility layer's usr/bin, with its ld, first on PATH, even when rustc is not installed. EasyBuild builds under $WORKING_DIR/easybuild; the module sets WORKING_DIR to /tmp/$USER when it is not set, and eb leaves it as you set it. --profile, --project and --config are not options of eb, which stops with exit 2 when given one; the 1.x Bash script has no eb command.

Once EESSI-extend has loaded, the script exits 2 before eb runs when the install path the module set is outside the tree the install variable selects, or when EASYBUILD_INSTALLPATH_SOFTWARE or EASYBUILD_INSTALLPATH_MODULES is set. Otherwise the command exits with eb's status.

With EB_LOCAL_EESSI_EXTEND set, not empty and not 0, every argument of eb-local goes to eb, as after eb-local eb --.

--explain eb

Print the script eb runs, after a set -- line with its arguments, and run nothing. With more than one install variable set, it prints nothing on stdout and exits 3.

env

Print the shell lines that load EESSI and then EESSI-extend for the prefix, or the project directory, which puts the modules installed there on MODULEPATH. Run them with eval "$(eb-local env)". When stdout is a terminal, it also says on stderr that the lines change nothing until the shell runs them.

Option Meaning
--strict Check that the EESSI init file exists in the emitted lines and exit 2 if absent (also when EB_LOCAL_ENV_STRICT=1). The exit is in the lines, so it ends the shell that evaluates them: meant for a job script, not an interactive shell.
--json Print, in place of the lines, the change they make to the environment, as one line of JSON.

With --json, eb-local runs the lines in a bash child and prints how that shell's environment then differs from the caller's: {"schema_version":1,"kind":"env","set":[{"name":...,"value":...}],"unset":[...]}, both lists sorted by name. A shell that cannot evaluate POSIX lines applies it; in nushell:

def --env --wrapped eb [...args] {
  let change = (^eb-local ...$args --json | from json)
  $change.set | reduce --fold {} {|var, acc| $acc | upsert $var.name $var.value } | load-env
  hide-env --ignore-errors ...$change.unset
}
eb env
eb dev FFTW/3.3.10-GCC-15.2.0

Only variables are in the change. Shell functions and aliases, such as Lmod's module, stay in the bash child, so a later module load in the other shell is not possible this way; name the modules on the dev line. What the lines print goes to stderr. If the lines fail in bash, nothing is printed and the status is 1.

dev

Print the lines env prints, then the lines that load the modules dev.modules names and those named on the line, then a build environment, and that set EB_LOCAL_DEV_PREFIX to <prefix>/dev/<EESSI version>/<CPU target>, with the GPU target appended when EESSI found one.

Option Meaning
--strict Check that the EESSI init file exists in the emitted lines and exit 2 if absent (also when EB_LOCAL_ENV_STRICT=1). As for env, the exit ends the shell that evaluates the lines.
--json Print the change the lines make to the environment as one line of JSON, as env --json does, with kind dev.
--buildenv MODULE Load MODULE as the build environment whatever the compilers, as dev.buildenv does.
--envrc Write the line that evaluates this dev to .envrc in the working directory, for direnv, and print nothing on stdout.

dev --envrc MODULE... writes three lines to .envrc:

# >>> eb-local dev >>> rerun `eb-local dev --envrc` to change these lines
eval "$(/path/to/eb-local dev MODULE...)"
# <<< eb-local dev <<<

The program is named by its own path, and --config, --profile, --project and --buildenv are repeated on the line. A block already in the file is replaced and every other line is kept; a file without one gets it appended. A begin line without its end line is refused. Run direnv allow once per change. direnv evaluates the file in bash and gives the calling shell the change, so the environment follows the directory in bash, zsh, fish, nushell and the other shells direnv has a hook for, and is taken back on leaving it. As with --json, only variables reach the calling shell.

--pure Before anything loads, run module purge and unset LD_LIBRARY_PATH, LD_PRELOAD and LD_AUDIT.
--lock Run the lines in a bash child and write what loaded to eb-local.lock in the working directory; print nothing on stdout.
--locked Print the lines that load exactly the modules of eb-local.lock, from a purged shell. Takes no MODULE.

dev --lock MODULE... records what a dev environment resolved to: stack.module, the EESSI version, the CPU target (EESSI_SOFTWARE_SUBDIR), the accelerator target, and every loaded module with its version, in load order, the build environment among them. The file is one line of JSON with kind dev-lock. It is not written when the lines load no module.

dev --locked loads that list and nothing else: it purges first, as --pure does, and names every module in full, so Lmod resolves nothing. A lock written with another stack.module is refused. When the shell's CPU target is not the lock's, the lines say so and load none of its modules; node types with the same CPU target share their binaries, so a lock from one loads on the other. --json and --envrc work with --locked: dev --envrc --locked writes the locked line to .envrc.

Without --pure, the modules the shell already has stay loaded beside the ones dev names, and the loader variables stay as they are, with a warning for LD_LIBRARY_PATH. With it, the build environment is the stack, the named modules and the build environment only. Sticky modules survive module purge. A site that preloads a library for every process (XALT through LD_PRELOAD) loses that in this shell.

A MODULE starts with a letter or digit and holds letters, digits, ., _, +, - and single slashes, with none at the end. With LD_LIBRARY_PATH set in the shell, dev warns on stderr.

rpath-wrappers

Write RPATH wrappers for the compilers and linkers on PATH into a directory below $XDG_CACHE_HOME/eb-local, or $HOME/.cache/eb-local without it, and print the lines that put that directory first on PATH and name it in EB_LOCAL_RPATH_WRAPPERS. The names it wraps are gcc, g++, c++, cc, gfortran, clang, clang++, flang, flang-new, icx, icpx, ifx, nvc, nvc++, nvfortran, ld, ld.bfd, ld.gold and ld.lld.

Option Meaning
--for FAMILY Say on stderr that no build environment for the FAMILY compilers is available, as dev does.
--unwrapped Wrap only the clang, clang++, flang, flang-new and ld.lld on PATH that no other wrapper comes before, and print nothing when there are none.

Without --unwrapped, finding nothing to wrap is exit 1.

check

For each FILE, print its machine, its program interpreter (the loader), its RPATH or RUNPATH, and where each library it needs resolves, ignoring LD_LIBRARY_PATH, then one line for all of them:

eb-local check: no problems

A problem is a line of its own, after problem:, below the line it concerns:

Problem When
built for MACHINE; this node is MACHINE The file is for another architecture.
the loader is the host's, not the compatibility layer's under DIR EESSI is loaded, and the file names a loader outside its compatibility layer.
RUNPATH, which LD_LIBRARY_PATH overrides and the libraries' own dependencies ignore; link with --disable-new-dtags for RPATH The file records RUNPATH rather than RPATH.
run paths into the TARGET software tree; this shell is TARGET: build it again on this node type A run path, or a directory in LD_LIBRARY_PATH, leads into the tree of a CPU target other than $EESSI_SOFTWARE_SUBDIR.
LIBRARY does not exist The file names a library by its path, and there is none.
LIBRARY is not found No run path, no directory in LD_LIBRARY_PATH and none of the loader's directories holds the library.
LIBRARY is found only through LD_LIBRARY_PATH The same, but a directory in LD_LIBRARY_PATH holds it.
LIBRARY comes from the host, not from EESSI EESSI is loaded, and the library resolves outside it.

By default, check follows only the libraries the file names directly; --recursive follows resolved DT_NEEDED shared libraries transitively and audits each unique resolved library once.

--module NAME/VERSION, --dev and --prefix DIR audit every ELF file in place of the files named on the line. A file that is not ELF is skipped, and a symbolic link is not followed, so a link cannot point the audit outside the tree. --module may be repeated, and further NAME/VERSION words after it name more modules. Each must be installed. Every CPU target's installation is audited, and the module files are not: they are not ELF. --dev reads EB_LOCAL_DEV_PREFIX when it is set, and otherwise <prefix>/dev/$EESSI_VERSION/$EESSI_SOFTWARE_SUBDIR, with $EESSI_ACCELERATOR_TARGET appended when that is set. --prefix is any directory and does not read the site file. The three are alternatives to naming files, and to each other. --quiet prints a file only when it has a problem, and still ends with the summary line. With no ELF file in the tree, and without --quiet, check says eb-local check: no ELF files and then eb-local check: no problems.

--json prints one line of JSON with schema_version 1, kind check, problem_count, unreadable, elf_count, and a files array of path, machine and problems. The shape is in check.schema.json.

It exits 0 when there are no problems, 1 when there are, and 2 when a named file cannot be read or is not ELF, or when a file in a tree cannot be read. A file that is not ELF is not a failure of a tree audit. With --json, these codes are unchanged; only the summary on stdout is JSON.

submit

Send one batch job for each node type in build.node_types, each running this eb-local with the same easyconfig, options and configuration. submit is deprecated, and is removed in 4.0.0; --explain prints the same jobs as sbatch lines.

Option Meaning
--on NAME,... Only the node types named.
--print Print the jobs, and submit nothing.

--on and --print come before the easyconfig; the words after it go to eb. It exits 1 when sbatch refuses a job, and 2 when the site file has no build.node_types.

list

Print each module installed in the prefix, or the project directory, with a column for each CPU target it has a tree for, x where the module is built for that target and - where it is not. With EESSI loaded, the column of this node's target is marked *, and the modules it lacks are named. A NAME keeps the modules of that name, and a NAME/VERSION that module.

--missing prints only the sorted NAME/VERSION lines missing on the loaded CPU target, or nothing when every matching module is built there, and exits 2 when EESSI is not loaded. --missing and --json cannot be used together. --json prints one line of JSON with schema_version 1, kind list, the prefix, filters, empty, CPU targets, modules with a built boolean per target, missing_on_node, and nullable node_target and hint. The shape is in list.schema.json.

doctor

Print one line for each check of what would stop a build, eb-local eb or a module load, each starting ok, info, warn or FAIL, then a line that says whether anything stops a build. It checks the site file, the secrets a build reads (never their values), the prefix and its permissions, install variables and LD_LIBRARY_PATH left in the shell, the EESSI init eb-local eb sources, the allocation's node-local mount, whether EESSI is loaded and your modules are on MODULEPATH, the Lmod init a build sources where the shell has no module command, eessi-arch-guard, and rtrash. With --workspace PATH, it also creates, writes, renames, executes and removes a small probe in that existing directory. It reports the file-system type, whether the storage is node-local or shared, free bytes and inodes, a noexec mount, and whether the effective XDG_CACHE_HOME (or $HOME/.cache when unset) is inside the workspace. The check does not create a build workspace and never starts a build. It names an entry of PERL5LIB, PYTHONPATH, R_LIBS*, CMAKE_PREFIX_PATH or PKG_CONFIG_PATH, and a compiler-wrapper variable (CC, CXX, FC, F77, F90, F95, CPP, the OMPI_, MPICH_ and I_MPI_ forms, RUSTC_WRAPPER, CCACHE_*, SCCACHE_* and CMAKE_*_COMPILER_LAUNCHER), that resolves outside the approved prefixes. A build keeps that entry unless build.clear_foreign_prefixes is set. It reports the path /etc/localtime resolves to, warns when that file is its own bind mount, and warns about a host library directory a container runtime injected, including /.singularity.d/libs and a directory named by APPTAINER_CONTAINLIBS or SINGULARITY_CONTAINLIBS. With --cvmfs, it also checks the CernVM-FS repository named by EESSI_CVMFS_REPO, or /cvmfs/software.eessi.io. It reports whether that mount is present, a stale FUSE mount, or returning an input/output error. It reports the HTTP proxy in force: CVMFS_HTTP_PROXY in the environment wins over /etc/cvmfs/default.conf, default.local, domain.d and config.d, and a value taken from the environment is named as one a host can inject. DIRECT is direct mode. When cvmfs_config is on PATH, it runs cvmfs_config probe and cvmfs_config chksetup; a stale mount skips the probe. --cvmfs-parallel N, or doctor.cvmfs_parallel when the flag is omitted, reads repository metadata from N tasks, and only inside an allocation. It uses srun -n N stat when srun is on PATH, and otherwise reads from N processes of its own. A build does not run these checks and does not set a CernVM-FS variable. With --mpi, it reports whether fi_info and ucx_info are on PATH, and any Slurm CPU or memory bind in SLURM_CPU_BIND, SLURM_CPU_BIND_LIST and SLURM_MEM_BIND. Inside an allocation it compiles a two-rank hello with mpicc and runs it with mpirun -np 2 for each transport in doctor.mpi_transports. The hello for ofi is run with OMPI_MCA_pml set to cm and OMPI_MCA_mtl set to ofi. The hello for ucx is run with OMPI_MCA_pml set to ucx and OMPI_MCA_mtl set to ^ofi. Those variables are set only on that hello. A build does not set them, and it does not set FI_PROVIDER. Outside an allocation the hello is not compiled. Where the shell has a module command, a build keeps it and its MODULEPATH, so doctor checks that a directory on MODULEPATH holds stack.module. Inside a job with EESSI loaded, it asks eessi-arch-guard, where that is on PATH, as a build asks it, and shows the target it selects; a guard that cannot select one is a warn, since a build's own run of it decides. With a site file, what stops a build is a FAIL, and what stops only eb-local eb is a warn; without one, builds cannot run, so what stops eb-local eb is the FAIL. It changes nothing, and exits 1 when a line says FAIL.

Option Meaning
--json Print one JSON document instead of human-readable lines.
--strict Exit 1 whenever a warn line appears as well as FAIL, setting failed to true in --json.
--workspace PATH Probe the existing absolute directory PATH and report its storage and cache isolation.
--cvmfs Check the CernVM-FS client. Off unless this flag, or --cvmfs-parallel, is given.
--cvmfs-parallel N Also read repository metadata from N tasks, 1 to 8, inside an allocation. Implies --cvmfs.
--mpi Report libfabric, UCX and Slurm binding, and run a two-rank hello per site-approved transport inside an allocation. Off unless this flag is given.

--json prints one line of JSON with schema_version 1, kind doctor, site_file, failed, lines (level and text), and summary. The shape is in doctor.schema.json. With --json, exit 1 still means failed is true (a FAIL line, or a warn line under --strict); scripts read failed in the document.

lmod-cache

Write spiderT.lua in --cache-dir from Lmod's spider -o spiderT, for every directory in --modulepath, then set --timestamp one second older than that file. Lmod treats a newer timestamp as a stale cache and does not show the modules the cache names. A spider that cannot start, exits non-zero, or writes nothing leaves the cache and the timestamp as they were. With --verify, the command first writes the candidate to a temporary directory inside --cache-dir. It points a temporary LMOD_RC at the candidate and compares normalized output from module --terse avail with and without LMOD_IGNORE_CACHE=yes. It atomically replaces spiderT.lua only when both inventories parse and match. An inventory mismatch or parsing failure leaves the previous cache and timestamp unchanged.

With --prefix, the command walks every CPU target under the prefix (versions/*/software/… or software/…), prepends each accelerator's modules/all directory on that CPU (as EESSI's filesystem-layer update_lmod_caches.sh does), and runs Lmod's update_lmod_system_cache_files into <cpu>/.lmod/cache. --dry-run lists each target, cache directory and colon-separated MODULEPATH; it changes no file.

It does not read the site file. --profile, --project and --config are accepted and ignored.

Option Meaning
--modulepath DIR[:DIR] The module directories, separated by colons. Absolute. Required without --prefix.
--cache-dir DIR The directory that receives spiderT.lua. Absolute. Required without --prefix. Created if it is missing.
--timestamp FILE The timestamp file Lmod compares with the cache. Absolute. Required without --prefix.
--spider CMD The spider program for single-target mode. Default: spider on PATH.
--verify In single-target mode, compare the candidate cache inventory with uncached module discovery before replacing the cache.
--prefix DIR Walk DIR for CPU targets and refresh each .lmod/cache with Lmod's cache updater. Absolute.
--eessi-version VER With --prefix, only DIR/versions/VER/software; default is every versions/*/software.
--update-cmd CMD Lmod's update_lmod_system_cache_files program. Default: DIR/compat/linux/$(uname -m)/usr/share/Lmod/libexec/update_lmod_system_cache_files.
--dry-run With --prefix, list targets only.

Exit 0 means both files were written or every prefix target was updated. Exit 2 is a missing, relative, or conflicting option. Exit 127 means spider, the cache updater, or module with --verify could not be started. With --verify, any inventory parsing or comparison failure exits 1; otherwise any other exit is spider's or the cache updater's, and caches are left as they were on failure.

modulerc

Write or update .modulerc.lua at the root of --module-tree. The command adds only the defaults, aliases and hidden versions named explicitly; it never examines the tree to select a default. Existing lines are preserved, and a line already present is not duplicated.

Option Meaning
--module-tree DIR The absolute module tree containing .modulerc.lua. Required.
--default MODULE Add module_version("MODULE", "default"). Repeatable.
--alias NAME=MODULE Add module_alias("NAME", "MODULE"). Repeatable.
--hide MODULE Add hide_version("MODULE"). Repeatable.
--dry-run Print the complete resulting file and leave the tree unchanged.
--check Print whether the requested directives would update the file, write nothing, and exit 1 when they would.
--json Print one JSON document with schema_version 1 instead of text; see modulerc.schema.json.

At least one directive option is required. --dry-run and --check cannot be used together. --json works with write, --dry-run (including content in the JSON) and --check (keeping exit 1 on drift). Any invalid UTF-8 byte in a path, directive, or content is replaced with the Unicode replacement character U+FFFD, so non-UTF-8 paths or contents do not round-trip. Running the same command again produces identical file contents. This command does not read the site file; --profile, --project and --config are accepted and ignored.

overlay

Keep site recipe changes in a digest-pinned overlay file instead of copying an upstream easyconfig. materialize applies [replace], [patches], and [dependencies.add] / [dependencies.replace] tables, refuses when base_digest no longer matches the base file, and writes materialized-<name> plus provenance.toml.

Subcommand Meaning
materialize Read --overlay FILE and --base PATH; write outputs under --out-dir (default: beside the overlay). --dry-run validates the inputs and lists both output paths without creating them. --check compares the materialized recipe and provenance against disk without writing, exiting 0 when up to date and 1 when either would update. Exit 2 when the base digest drifted or both --dry-run and --check are given.
bump Run eb-stack package bump with every argument after -- (including --help, --config, --profile, and --project); --eb-stack PATH names the program when it is not on PATH.
plan Run eb-stack package plan the same way.

The overlay format is documented in Recipe overlay file. These commands do not read the site file.

clean

Remove what eb-local left in the prefix, or the project directory: by default the build logs in .eb-local/logs older than clean.logs_older_than_days.

Option Meaning
--logs-older-than DAYS The logs more than DAYS whole days old, in place of clean.logs_older_than_days; DAYS is at most 99999.
--no-logs No logs.
--sources The downloaded source archives in .eb-local/sources too.
--workspaces Your build workspaces in the job's node-local mount too; only inside the Slurm job that made them.
--dry-run Print what would be removed, and remove nothing.
--delete Delete for good when clean.trash does not move files to the trash.
--json Print one JSON document with schema_version 1 instead of text.

Files go to the trash with rtrash as clean.trash says; workspaces are deleted. A directory among the logs, such as the reprod_* copies of a failed build's easyconfig, easyblocks and hooks, goes whole once neither it nor anything in it is newer than the cutoff: the copies keep their originals' older times, and a file added to a directory makes the directory new. clean never follows a symbolic link out of the installation directory. With clean.trash none, or auto and no rtrash on PATH, it removes nothing without --delete, and exits 1. If any item or build workspace cannot be removed, clean warns and exits 1 (including with --json, where removed_items and removed_workspaces report the actual counts). With --json, stdout holds one line of JSON with schema_version 1, kind clean, prefix, dry_run, action (nothing, dry-run, trashed, deleted, workspaces-only or refused), items (path and kind), workspaces, removed_items and removed_workspaces; see clean.schema.json. Any invalid UTF-8 byte in a path is replaced with the Unicode replacement character U+FFFD, so non-UTF-8 paths do not round-trip.

config

Print every setting in force, with where its value came from: default, a file and line with its layer and profile, a variable, or an option. The configuration files lists the settings.

Option Meaning
--check Also read each secret, and print ok, or FAILED: and why, where the file that set it would be; never the value.
--env Print the settings as export EB_LOCAL_... lines for a shell, with each secret's source and never its value.
--get KEY Print the resolved value of KEY (one item per line for list keys; secret sources only), exiting 1 when unset or empty and 2 when KEY is unknown.
--json Print one line of JSON instead of the table; with --check, secret rows include status (listed, ok, or failed with optional detail). Not with --env or --get.

It exits 1 with --check when a secret cannot be read or the project directory cannot be used. With --json, the same holds; the document has check_failed true.

--json without --check prints schema_version 1, kind config, profile, check (false), check_failed (false), settings, and secrets listed only (with detail set to null). With --check, check is true and each secret row records whether it could be read. The shape is in config.schema.json.

profiles

Print each profile the configuration files define, with the layer and the file that define it, or no profiles are defined.

--json prints schema_version 1, kind profiles, and a profiles array of name, layer and path. The shape is in profiles.schema.json.

uninstall

Remove each installation NAME/VERSION names, for every CPU target, with its module files and the links EasyBuild makes to them from modules/CLASS/, and print what it removes. EasyBuild leaves an installation read-only; uninstall makes its directories writable first.

Option Meaning
--target TARGET Remove and check dependents only in the CPU tree matching TARGET (a full target such as x86_64/amd/zen4, or a short name when unique; an ambiguous short name exits 2 and lists the candidate trees).
--dry-run Print what would be removed, and remove nothing.
--delete Delete for good when clean.trash does not move files to the trash.
--usage-log FILE Ask eb-keep-logs whether the install prefix is named in FILE, and remove nothing when that command exits 2.

It removes nothing, and exits 2, when another module installed in the prefix loads one named and is not named too. With clean.trash none, or auto and no rtrash on PATH, it removes nothing without --delete, and exits 1.

--usage-log FILE runs eb-keep-logs used --prefix PREFIX --require-none FILE after that dependents check and before anything is listed or removed. PREFIX is the install prefix. eb-local does not read FILE. When that command exits 0, uninstall goes on as it would without the option, including a dry run. When it exits 2, or any other status, or eb-keep-logs is not on PATH or cannot be run, uninstall removes nothing, exits 2, and prints what eb-keep-logs wrote. Without --usage-log, uninstall does not run eb-keep-logs. restore does not take the option, and uninstall takes it once.

restore

Bring each NAME/VERSION that uninstall moved to the trash back, for every CPU target, with rtrash restore, and make it read-only again.

Option Meaning
--dry-run Print what would come back, and restore nothing.

One that is not in the trash for the prefix is exit 2, and so is a path in the trash more than once, as after two uninstall runs: it restores nothing, and names the rtrash restore command for that path. rtrash restore on one path brings back read-only files in writable directories: rtrash moves a directory, and empties the trash, only when its directories are writable.

site

Print or write a site file from a template: slurm, built in, or a template file of the site's own, named with a slash.

Word or option Meaning
list Print each built-in template and its placeholders; site alone does the same. --json prints one line of JSON; see site_list.schema.json.
show NAME Print the site file the template NAME makes.
install NAME Write that site file to config.toml beside this program, mode 644.
check FILE Validate an existing site file as a site configuration layer without installing it.
--set KEY=VALUE Fill the placeholder KEY; may be given more than once.
--to FILE With install: write FILE instead.
--force With install: replace a file that exists.

show and install check that the file loads as a site file first. A value with a quote, a backslash or a control character is refused.

Exit status

Status Meaning
0 Done, or nothing to do.
1 check found a problem; doctor printed a FAIL; config --check could not read a secret or use the project directory; lmod-cache --verify failed or lmod-cache --prefix found no target; modulerc --check would update the file; overlay materialize --check would update the outputs; clean or uninstall had something to remove and no way to, or clean failed to remove some items or build workspaces; rpath-wrappers found nothing to wrap; submit: sbatch refused a job.
2 Refused, with the reason on stderr after eb-local:, or the command line was wrong; a build outside a Slurm job; check could not read a file.
3 eb or --explain eb: more than one install variable is set.
N A build or eb: eb exited N.

Commands that take --json use the same exit codes as their text output. Refusals and usage errors still print on stderr; only the report on stdout becomes one JSON line. Any invalid UTF-8 byte in a path or string field is replaced with U+FFFD, so non-UTF-8 strings do not round-trip. With --json, check still exits 1 for problems and 2 when a file cannot be read; doctor still exits 1 when failed is true in the document; config --check --json still exits 1 when check_failed is true.

The 1.x Bash script

The Bash script eb-local, 1.x, is frozen: it gains no commands, and it is removed in 4.0.0, when the test suite's default run against it ends too. It needs GNU coreutils, util-linux findmnt, Lmod and an EESSI 2026.06 mount, and has no profiles or secrets. It reads one site file, eb-local.conf: the file EB_LOCAL_CONFIG names, else the one beside the script, else /etc/eb-local.conf, used only when it is a regular file, not a symbolic link, not writable by group or others, and owned by root, the script's owner or you. Its key = value lines are the 1.x keys The configuration files lists.

See also