CLI Reference¶
HTMap provides a command line tool called htmap that exposes a subset
of functionality focused around monitoring long-running maps without needing
to run Python yourself.
View the available sub-commands by running:
htmap --help # View available commands
Some useful commands are highlighted in the Tips and Tricks section at Separate Job Submission/Monitoring/Collection.
Here’s the full documentation on all of the available commands:
htmap¶
HTMap command line tools.
htmap [OPTIONS] COMMAND [ARGS]...
Options
- -v, --verbose¶
Show log messages as the CLI runs.
- --version¶
Show the version and exit.
autocompletion¶
Enable autocompletion for HTMap CLI commands and tags in your shell.
This command should only need to be run once.
Note that your Python environment must be available (i.e., running “htmap” must work) by the time the autocompletion-enabling command runs in your shell configuration file.
htmap autocompletion [OPTIONS]
Options
- --shell <shell>¶
Required Which shell to enable autocompletion for.
- Options:
bash | zsh | fish
- --force¶
Append the autocompletion activation command even if it already exists.
- --destination <destination>¶
Append the autocompletion activation command to this file instead of the shell default.
clean¶
Clean up transient maps by removing them.
Maps that have never had a tag explicitly set are assigned randomized tags and marked as “transient”. This command removes maps marked transient (and can also remove all maps, not just transient ones, if the –all option is passed).
htmap clean [OPTIONS]
Options
- --all¶
Remove non-transient maps as well.
components¶
Print out the status of the individual components of a map.
htmap components [OPTIONS] TAG
Options
- --status <status>¶
Print out only components that have this status. Case-insensitive. If not passed, print out the stats of all components (the default).
- Options:
UNKNOWN | UNMATERIALIZED | IDLE | RUNNING | REMOVED | COMPLETED | HELD | SUSPENDED | ERRORED
- --color, --no-color¶
Toggle colorized output (defaults to colorized).
Arguments
- TAG¶
Required argument
edit¶
Edit a map’s attributes (e.g., its memory request).
Edits do not affect components that are currently running. To “restart” components so that they see the new attribute value, consider vacating their map (see the vacate command).
htmap edit [OPTIONS] COMMAND [ARGS]...
disk¶
Set a map’s requested disk.
Edits do not affect components that are currently running. To “restart” components so that they see the new attribute value, consider vacating their map (see the vacate command).
htmap edit disk [OPTIONS] TAG DISK
Options
- --unit <unit>¶
- Options:
KB | MB | GB
Arguments
- TAG¶
Required argument
- DISK¶
Required argument
memory¶
Set a map’s requested memory.
Edits do not affect components that are currently running. To “restart” components so that they see the new attribute value, consider vacating their map (see the vacate command).
htmap edit memory [OPTIONS] TAG MEMORY
Options
- --unit <unit>¶
- Options:
MB | GB
Arguments
- TAG¶
Required argument
- MEMORY¶
Required argument
errors¶
Show execution error reports for map components.
htmap errors [OPTIONS] [TAGS]...
Options
- -p, --pattern <pattern>¶
Act on maps whose tags match glob-style patterns. Pass -p multiple times for multiple patterns.
- --all¶
Act on all maps.
- --limit <limit>¶
The maximum number of error reports to show (0, the default, for no limit).
Arguments
- TAGS¶
Optional argument(s)
hold¶
This command holds a map. The components of the map will not be allowed to run until released (see the release command).
HTCondor may itself hold your map components if it detects that something has gone wrong with them. Resolve the underlying problem, then use the release command to allow the components to run again.
htmap hold [OPTIONS] [TAGS]...
Options
- -p, --pattern <pattern>¶
Act on maps whose tags match glob-style patterns. Pass -p multiple times for multiple patterns.
- --all¶
Act on all maps.
Arguments
- TAGS¶
Optional argument(s)
logs¶
Print the path to HTMap’s current log file.
The log file rotates, so if you need to go further back in time, look at the rotated log files (stored next to the current log file).
htmap logs [OPTIONS]
Options
- --view, --no-view¶
If enabled, display the contents of the current log file instead of its path (defaults to disabled).
path¶
Get paths to parts of HTMap’s data storage for a map.
This command is mostly useful for debugging or interfacing with other tools. The tag argument is a map tag, optionally followed by a colon (:) and a target.
If you have a map tagged “foo”, these commands would give the following paths (command -> path):
htmap path [OPTIONS] TAG
Arguments
- TAG¶
Required argument
pause¶
This command pauses a map. The running components of a paused map will keep their resource claims, but will stop actively executing. The map can be un-paused by resuming it (see the resume command).
htmap pause [OPTIONS] [TAGS]...
Options
- -p, --pattern <pattern>¶
Act on maps whose tags match glob-style patterns. Pass -p multiple times for multiple patterns.
- --all¶
Act on all maps.
Arguments
- TAGS¶
Optional argument(s)
reasons¶
Print the hold reasons for map components.
HTCondor may hold your map components if it detects that something has gone wrong with them. Resolve the underlying problem, then use the release command to allow the components to run again.
htmap reasons [OPTIONS] [TAGS]...
Options
- -p, --pattern <pattern>¶
Act on maps whose tags match glob-style patterns. Pass -p multiple times for multiple patterns.
- --all¶
Act on all maps.
Arguments
- TAGS¶
Optional argument(s)
release¶
This command releases a map, undoing holds. The held components of a released map will become idle again.
HTCondor may itself hold your map components if it detects that something has gone wrong with them. Resolve the underlying problem, then use this command to allow the components to run again.
htmap release [OPTIONS] [TAGS]...
Options
- -p, --pattern <pattern>¶
Act on maps whose tags match glob-style patterns. Pass -p multiple times for multiple patterns.
- --all¶
Act on all maps.
Arguments
- TAGS¶
Optional argument(s)
remove¶
This command removes a map from the Condor queue. Functionally, this command aborts a job.
This function will completely remove a map from the Condor queue regardless of job state (running, executing, waiting, etc). All data associated with a removed map is permanently deleted.
htmap remove [OPTIONS] [TAGS]...
Options
- -p, --pattern <pattern>¶
Act on maps whose tags match glob-style patterns. Pass -p multiple times for multiple patterns.
- --all¶
Act on all maps.
- --force¶
Do not wait for HTCondor to remove the map components before removing local data.
Arguments
- TAGS¶
Optional argument(s)
rerun¶
Rerun (part of) a map from scratch.
The selected components must be completed or errored. See the subcommands of this command group for different ways to specify which components to rerun.
Any existing output of rerun components is removed; they are re-submitted to the HTCondor queue with their original map options (i.e., without any subsequent edits).
htmap rerun [OPTIONS] COMMAND [ARGS]...
components¶
Rerun selected components from a single map.
Any existing output of re-run components is removed; they are re-submitted to the HTCondor queue with their original map options (i.e., without any subsequent edits).
htmap rerun components [OPTIONS] TAG [COMPONENTS]...
Arguments
- TAG¶
Required argument
- COMPONENTS¶
Optional argument(s)
map¶
Rerun all of the components of any number of maps.
Any existing output of re-run components is removed; they are re-submitted to the HTCondor queue with their original map options (i.e., without any subsequent edits).
htmap rerun map [OPTIONS] [TAGS]...
Options
- -p, --pattern <pattern>¶
Act on maps whose tags match glob-style patterns. Pass -p multiple times for multiple patterns.
- --all¶
Act on all maps.
Arguments
- TAGS¶
Optional argument(s)
resume¶
This command resumes a map (reverses the pause command). The running components of a resumed map will resume execution on their claimed resources.
htmap resume [OPTIONS] [TAGS]...
Options
- -p, --pattern <pattern>¶
Act on maps whose tags match glob-style patterns. Pass -p multiple times for multiple patterns.
- --all¶
Act on all maps.
Arguments
- TAGS¶
Optional argument(s)
retag¶
Change the tag of an existing map.
Retagging a map makes it not transient. Maps that have never had an explicit tag given to them are transient and can be easily cleaned up via the clean command.
htmap retag [OPTIONS] TAG NEW
Arguments
- TAG¶
Required argument
- NEW¶
Required argument
set¶
Change a setting in your ~/.htmaprc file.
htmap set [OPTIONS] SETTING VALUE
Arguments
- SETTING¶
Required argument
- VALUE¶
Required argument
settings¶
Print HTMap’s current settings.
By default, this command shows the merger of your user settings from ~/.htmaprc and HTMap’s own default settings. To show only your user settings, pass the –user option.
htmap settings [OPTIONS]
Options
- --user¶
Display only user settings (the contents of ~/.htmaprc).
status¶
Print a status table for all of your maps.
Transient maps are prefixed with a leading “*”.
htmap status [OPTIONS]
Options
- --state, --no-state¶
Toggle display of component states (defaults to enabled).
- --meta, --no-meta¶
Toggle display of map metadata like memory, runtime, etc. (defaults to enabled).
- --format <format>¶
Select output format: plain text, JSON, compact JSON, or CSV (defaults to plain text)
- Options:
text | json | json_compact | csv
- --live, --no-live¶
Toggle live reloading of the status table (defaults to not live).
- --color, --no-color¶
Toggle colorized output (defaults to colorized).
stderr¶
Look at the stderr for a map component.
htmap stderr [OPTIONS] TAG COMPONENT
Options
- --timeout <timeout>¶
How long to wait (in seconds) for the file to be available. If not set (the default), wait forever.
Arguments
- TAG¶
Required argument
- COMPONENT¶
Required argument
stdout¶
Look at the stdout for a map component.
htmap stdout [OPTIONS] TAG COMPONENT
Options
- --timeout <timeout>¶
How long to wait (in seconds) for the file to be available. If not set (the default), wait forever.
Arguments
- TAG¶
Required argument
- COMPONENT¶
Required argument
transplants¶
Manage transplant installs.
htmap transplants [OPTIONS] COMMAND [ARGS]...
info¶
Display information on available transplant installs.
htmap transplants info [OPTIONS]
remove¶
Remove a transplant install by index.
htmap transplants remove [OPTIONS] INDEX
Arguments
- INDEX¶
Required argument
vacate¶
This command vacates a map. The running components of a vacated map will give up their claimed resources and become idle again.
Checkpointing maps will still have access to their last checkpoint, and will resume from it as if execution was interrupted for any other reason.
htmap vacate [OPTIONS] [TAGS]...
Options
- -p, --pattern <pattern>¶
Act on maps whose tags match glob-style patterns. Pass -p multiple times for multiple patterns.
- --all¶
Act on all maps.
Arguments
- TAGS¶
Optional argument(s)
version¶
Print HTMap and HTCondor Python bindings version information.
htmap version [OPTIONS]
wait¶
Wait for maps to complete.
htmap wait [OPTIONS] [TAGS]...
Options
- -p, --pattern <pattern>¶
Act on maps whose tags match glob-style patterns. Pass -p multiple times for multiple patterns.
- --all¶
Act on all maps.
Arguments
- TAGS¶
Optional argument(s)