Command line¶
simrun is the command line of people and scripts: it submits, follows, compares, cancels and cleans up runs, and simrun edit opens a workflow file in the Editor of the web app. On a cluster it runs on the machine of the working trees and reads three environment variables, which the MCP server reads alike:
| variable | meaning |
|---|---|
SIMRUN_URL |
the address of the service, e.g. http://simrun.cluster.internal |
SIMRUN_TOKEN |
a token of the tokens file of the service, which names the person or the agent |
SIMRUN_STORE |
optional: the run store as it is mounted on this machine, e.g. /mnt/cluster, where the client writes the snapshots itself; without it the client uploads them to the service |
export SIMRUN_URL=http://simrun.cluster.internal
export SIMRUN_TOKEN=...
export SIMRUN_STORE=/mnt/cluster
Every command takes --json (except logs, which prints the logs as text, and edit, which runs until it is stopped) and prints machine-readable JSON instead of tables. A refusal of the service is printed to stderr with exit code 1.
With --local on a command, no variable is needed: it talks to the local service of the current directory, see Local mode.
Commands¶
| command | what it does |
|---|---|
simrun submit WORKFLOW |
snapshot the sources and submit a workflow; prints the run in the state submitting, or with --wait follows it to its end |
simrun wait RUN |
wait for a run to end; exit 0 if it succeeded, 1 if it failed or was cancelled, 2 on timeout |
simrun status RUN |
the state of a run and its tasks with their progress |
simrun list |
the runs, filtered by group, agent, state and owner |
simrun logs RUN TASK |
the logs of the pods of a task |
simrun outputs RUN TASK |
list the output files of a task, or download them with --to DIR |
simrun edit WORKFLOW |
serve the Editor of the web app for a workflow file: saves go into the file, runs use the working trees |
simrun estimate WORKFLOW |
the plan and the expected duration of every task of a submission |
simrun compare RUN RUN... |
the provenance and the summaries of the tasks of runs side by side |
simrun cancel RUN |
cancel a run |
simrun cleanup |
remove ended runs and the snapshots nothing refers to |
simrun usage |
the bytes of the store per group and run |
simrun serve |
run the service in the foreground: --local the local service of the current directory, else the service of SIMRUN_CONFIG |
submit¶
| option | meaning |
|---|---|
--source NAME=PATH |
a source, the path of a git working tree; repeated, the model first |
--group GROUP |
the group of the run, e.g. a study |
--single-server |
place the pieces of every task on one server |
--reserve NODE |
reserve a node for the run |
--local |
use the local service of the current directory, see Local mode |
--docker |
with --local: run a command task in its image with docker instead of directly |
--snapshot |
with --local: copy and install the sources as on the cluster instead of recording their provenance only |
--wait / --no-wait |
follow the run to its end (a live line per task on a terminal, plain lines otherwise) and exit like wait; the default with --local, else --no-wait |
--timeout SECONDS |
with --wait: give up after this long, exit 2; refused without waiting |
The client copies every working tree with its uncommitted changes into snapshots/<name>/ of the store, or without SIMRUN_STORE uploads the files the store lacks to the service which writes the snapshot, and sends its provenance, see Snapshots and environments.
edit¶
| option | meaning |
|---|---|
--source NAME=PATH |
a source, as for submit; snapshotted when the session opens and at every run |
--group GROUP |
the group of the runs started from the Editor which name none |
--local |
use the local service of the current directory |
--snapshot |
with --local: copy and install the sources at every run |
The command opens an edit session in the service, prints the link of the Editor and runs until Ctrl-C, which closes the session and exits 0 (a second Ctrl-C exits without waiting for the close): it writes the saves of the browser into the file, runs the workflow of the browser as submit does, and sends a change of the file or of the working trees to the browser. A file which does not exist is a new workflow.
wait¶
--timeout is in seconds, without it the command waits for the end of the run. The service answers a long poll which the client repeats, so no connection is held for hours.
outputs¶
simrun outputs <run> <task> # the files and their sizes
simrun outputs <run> <task> --to results # download them into results/
The files come through the API, so no mount of the store is needed. With --json the list is [{"path", "bytes"}], or with --to the paths written.
status, list and logs¶
list takes --group, --agent, --state (submitting, queued, running, succeeded, failed, cancelled) and --owner; the runs of an owner include the ones of their agents. logs prints the last --tail lines (300 by default, 0 for all) of every pod of the task: the logs kept in the store once the task is final, else the ones of its live pods.
estimate and compare¶
estimate takes the options of submit but --group. compare reads the provenance of the runs and the summary.json of their tasks.
cancel, cleanup and usage¶
cleanup removes the runs which ended more than --older-than days ago (30 by default), only the ones of --group or only --failed runs, and the snapshots no remaining run refers to; --dry-run lists what it would remove.
serve¶
simrun serve --local # the local service of the current directory
simrun serve --local --idle-exit 1800 # exits after 30 min without a request and without a live run
simrun serve --local --stop # stops the local service of the current directory, cancelling its runs
simrun serve --port 8000 # the service of SIMRUN_CONFIG, as uvicorn --factory simrun.service.app:serve
serve --local runs the service of the current directory with the local backend, which runs the tasks as processes on this machine: its store is .simrun/store/, its scratch .simrun/scratch/, its index .simrun/simrun.sqlite and its tokens .simrun/tokens.yaml (with a .gitignore of everything, so none of it lands in git), it listens on 127.0.0.1 only, on a free port unless --port names one, and serves the web app at /ui/. It prints simrun at http://127.0.0.1:<port>/ui/ (token in .simrun/service.json); .simrun/service.json (mode 0600) holds the pid, the port, the token, the URL, a random instance of this start and the environment of the service (its python, its simrun version, a hash of the task types it found, whether it runs in the background) while it runs; a client sends the token only to a server which answers that instance at /local/instance. Ctrl-C, SIGTERM or SIGHUP (the terminal closed) cancels the runs and waits for their processes, printing what it waits for, so no process of a run outlives a graceful stop; a service which starts after one which was killed (SIGKILL, out of memory) kills the processes that one left running. --stop stops the service of the current directory the same way and waits for its end. One service runs per directory; a second one is refused with exit code 3. A command which needs the local service starts it in the background when none runs (python -m simrun serve --local --idle-exit 1800, its output in .simrun/service.log); a service in the background which runs with another environment than the command is restarted when it has no live run and no open request, else the command warns and uses it.