CLI¶
The caddforge CLI is the main user interface for running workflows and inspecting jobs.
Open documentation¶
Install caddforge-docs to enable the optional documentation command. Version
0.3.0 is tagged and awaiting package-index publication; install the source checkout with
python -m pip install ../caddforge-docs for now. Once that release is available:
The planned public bundle includes this package automatically. Core-only and selective plugin installations add it separately. See the version matrix for current availability.
The command serves the documentation bundled with the installed docs release, opens the default
browser, and runs until Ctrl+C. No source checkout, documentation build tools, or internet connection
are needed. It defaults to 127.0.0.1 with an automatically assigned port:
caddforge docs --host 0.0.0.0 --port 8001
caddforge docs --host localhost --no-browser
caddforge docs --host ::1
--host accepts hostnames, IPv4, and IPv6 addresses. Wildcard bindings open a loopback browser URL;
remote clients should use the server's reachable address and printed port. --no-browser suppresses
automatic opening. If no browser can be launched, the server stays available at the printed URL.
The command is absent when the docs package is not installed.
Discover tools¶
Show a config template¶
Example:
Run a workflow¶
Examples:
caddforge run docking unidock --config unidock.yaml
caddforge run md openbpmd --config openbpmd.yaml
caddforge run fep openfe-abfe --config abfe.yaml
Pack a Slurm environment¶
Create a relocatable Conda environment archive and its managed SHA-256 sidecar:
# Pack the active environment.
caddforge pack-env --output /shared/envs/caddforge-dev.tar.gz
# Pack a named environment.
caddforge pack-env --name caddforge --output /shared/envs/caddforge.tar.gz
# Pack an explicit environment prefix.
caddforge pack-env --prefix /scratch/$USER/envs/caddforge \
--output /shared/envs/caddforge.tar.gz
--name and --prefix are mutually exclusive. The output must end in .tar.gz. Existing archive
or sidecar files are protected unless --force is supplied:
For an intentionally modified Conda environment whose package metadata references missing files,
--ignore-missing-files forwards the corresponding conda-pack option. The resulting archive may
be incomplete, so use this only when those omissions are understood:
The command keeps the conda-pack percentage bar on one updating terminal line, streams normal
messages, prints periodic elapsed-time and archive-size heartbeats during quiet periods, and reports
hashing progress. On success it prints the archive path, sidecar path, digest, size, elapsed time,
and the slurm_env_pack_path config entry.
The generated sidecar is named <archive>.sha256 and uses standard sha256sum format. See the
Slurm backend guide for cache and compatibility behavior.
Jobs¶
caddforge status <job-id>
caddforge logs <job-id>
caddforge logs <job-id> --follow
caddforge export <job-id>
logs --follow prints newly synchronized stdout until the job reaches a terminal state. Use
--poll-interval <seconds> to change the default one-second check interval. Follow mode tolerates
temporary log-file and registry outages, handles scratch-synchronized snapshot replacement, and
suppresses duplicate lines carrying the same event=<sequence> identifier. Press Ctrl+C to stop
following without cancelling the job.
Workflow results are stored in the job run directory by default. Use caddforge export <job-id> to
copy results/ back to the submission directory, or set export_results: true in the workflow
config to do that automatically when the job finishes.