HPCBOX CLI
The hpcbox command-line tool lets you monitor and manage workflow runs directly from a terminal, without opening the GUI. It is useful when you are connected via SSH, working in a headless environment, or want to script workflow monitoring.
Installation
The hpcbox binary is distributed as part of the HPCBOX Cluster App package. After installation it is typically available at:
/opt/drz/apps/hpcbox/latest/clusterapp/hpcbox-cluster-app-latest/dist/hpcbox-cli/hpcbox
Add this directory to your PATH to use hpcbox without a full path:
export PATH="/opt/drz/apps/hpcbox/latest/clusterapp/hpcbox-cluster-app-latest/dist/hpcbox-cli:$PATH"
Add that line to your ~/.bashrc or ~/.bash_profile to make it permanent.
Commands
hpcbox list
Lists all workflow runs from the current session and previous sessions.
hpcbox list [--all]
By default only active (not yet finished) runs are shown. Use --all to include completed and failed runs that have not been cleaned up.
RUN ID WORKFLOW STATUS STARTED HOST
──────────────────────────────────────────────────────────────────────────────────────────────────────────────
a3f8b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c openfoam running 2026-06-16 09:14 login01
hpcbox status <run-id>
Shows detailed status for a single run, including step-by-step progress.
hpcbox status <run-id>
You can supply a unique prefix of the run ID instead of the full UUID — for example hpcbox status a3f8b2.
Run ID : a3f8b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c
Workflow : openfoam
File : /home/user/workflows/openfoam.hpcbox
Host : login01
PID : 12345
Started : 2026-06-16 09:14:00
Ended : —
Final status: running
Steps (updated 2026-06-16 09:25:10):
✓ meshing completed
▶ simulation running
· postprocess pending
Step icons:
| Icon | Meaning |
|---|---|
✓ | Completed successfully |
✗ | Failed |
▶ | Currently running |
· | Pending (not yet started) |
? | Unknown (executor state lost) |
hpcbox attach <run-id>
Attaches to a running workflow and streams live log output and step status updates to the terminal.
hpcbox attach <run-id>
Press Ctrl+C to detach. The workflow keeps running — detaching does not stop it.
When the executor finishes, the connection closes automatically and ── Executor disconnected. Run complete. ── is printed.
Attach only works from the same login node where the workflow was started. If you started the workflow on login01, you must be on login01 to attach. See Different Login Nodes below.
hpcbox cancel <run-id>
Sends a termination signal to the workflow executor, stopping the run gracefully.
hpcbox cancel <run-id>
The executor receives the signal and stops after the current step completes its cleanup. Any HPC jobs already submitted by previous steps may still be running in the queue — check the Queue tab in the GUI or use qstat to manage them.
Cancel only works from the same login node where the workflow was started. If the run is on a different node, the CLI will print the exact command to run after SSH-ing to the correct node.
Different Login Nodes
On clusters with multiple login nodes, the attach and cancel commands require you to be on the same node where the workflow is executing. The hpcbox list and hpcbox status commands work from any node because they read only the status files in ~/.drizti/hpcbox/runs/.
If you try to attach or cancel from the wrong node, the CLI will tell you which node to use:
error: this run is executing on login01 but you are on login02.
SSH into login01 and run: hpcbox cancel a3f8b2c1
Run Directories
All workflow state is stored under ~/.drizti/hpcbox/runs/. Each run has its own subdirectory named after its run ID. See Workflow Run Directories for details on the file format.