beerst/dorun repository overview

dorun ("do-run"): Run a command--from a distribution image ("distro"), installed image, running container, or local shell--using compact syntax, default typical options, target command options and arguments, and enhanced execution options

Usage: dorun [dorun-options] [repository][/image][:version] [container] [: target-command] [target-options/arguments]

dorun options:      -b -B bind-dir@name -V version -u/-U -k/-K -d run/exec-opts  [-r REPL-options]  [-w/-W web-UI-options]  [-s/-S/-F script-options]  -DIqvXh
     Defaults:      -b/-B no local/sped'd dir binds; -V latest/spec'd version; -u/-U pull image as-needed; -k/-K create/delete temporary container; -d no image/container options; -F/-s no script-gen; -DIqvh no std-IO, std messaging, no help

Target-executable/command:
  [repository][/image][:version]    Run "repository"-deployed or default installed "/image" of specified ":version" or default latest version... 
  [container]                       ...to use named or default temporary "container"...
    ...OR default instead use local system...
  [: command] [options/arguments]   ...to execute specified ": command" or default image-named command, with optional command "options/arguments"

Examples:
: [dorun] beerst/pubdoc -h                       # Execute default image-named command "pubdoc -h" ("help") with temporary container from installed or latest version of repository-hosted image "pubdoc"
: [dorun] -b /earest:1013 -s my_EARe.txt         # Bind current directory (-s) to temporary container from installed ("/") image "earest" version "1013" to execute detault image-named command "earest -s myEARe.txt"
: [dorun] my_container ls                        # With active container "my_container" run specified command "ls"
: [dorun] -r : cc myCode.c                       # Every few seconds, repeat-execute (-r) command "cc myCode.c" on local system if myCode.c has changed

"Quick help":                dorun -qh
Help with REPL repeat-eval:  dorun -hr
Help with web-UI:            dorun -hw
Help with container admin:   dorun -hc
Help with dorun scripts:     dorun -hs
Complete dorun help:         dorun -h
More about a dorun script:   dorun-script -hS :  _or_  DORUN_SCRIPT=dorun-script dorun -hS

Features for running target executable containers and command lines ("executables"):
- Simple syntax to specify OCI executable to run: default options run image-named command with optional command-line arguments
- Source-embedded "dot-options" modify executable's command-line options, applied before other options; by default, each delimited by leading space+period (e.g. " .v"), dorun options tail-delimited by ".:"
- Command-line "Read/Eval/Preview/Loop" ("REPL") interactive processing, including interactive dot-options
- Web user interface ("web-UI") for interactive processing, with default and customizable UI features (requires Linux-based target-executable image)
- Standalone script generation to simplify running an executable with specific arguments, options, and dorun features



Container execution options:

-b                    Bind local current directory to running container as /image-name, so container has access to local files
-B bind-dir@name      Bind specified directory to running container as /name; repeatable
-V version            Run the specified (docker-tagged) version of the image, _instead of_ image-spec-specified or default "latest" version
-u                    Update target image with latest image from repo (or as specified by environment variable IMAGE_SPEC); overrides default that updates "as-needed"
-U                    Update installed dorun utility (used by dorun scripts) with latest image from repo (or as specified by environment variable DORUN_IMAGE_SPEC)
-k                    Execute target command in, and keep active, container with specified name or default name "dorun__image-name"
-K                    Remove specified active container
-d run/exec-options   Add docker options to "run" command or (if repeating) to "exec" command; must appear at end of dorun options, must not repeat features of other options e.g. -k

-r/-R REPL-options    Create/run auto-refresh version of command output ("Read-Eval-Preview-Loop" for interactive command line)
                        Options -R:  [-][auto-apply-interval][:outputFile-name|/pattern/|(command)][:exit-test-timeout|(command)][:REPL-UI-gener]; exit-test-command returns "exit status" to exit
                        Defaults:    do interactive REPL (else just create "LIVE" file); auto-apply every 3 seconds; output file is last-modified .html file; timeout after 10 minutes; standard "LIVE" REPL-UI
                        Example:     -R "7::300"  # repeat every 7 second, up to 5 minutes

-w/-W web-UI-options  Create/launch web-UI processing of container input/output (web application for interactive workflow); -r to auto-apply
                        Note: Requires docker installed on dorun execution system
                        Options -w:  [web-UI-name][:port][:select-File-types][:focus-file-name|/pattern/|(command)]
                        Defaults:    image-name; port 80; local files of any type selectable; focus file is latest-modified file of any type (-w - to default all)
                        Options -W:  [web-UI-omits][:gen-UI-command]
                        Defaults:    all applicable web-UI features (else command-separated tag list of WEB_UI features to omit); standard web-UI (else command to output web-UI based on standard) (-W - to default all)
                        Example:     -w myapp:82:.txt,.html:_EX.txt -W SAVE_OUTPUT  # "myapp" web-UI on port 82, selectable local text/HTML files, focus file latest "example" file, omit save-output feature

-s/-S script-options  Generate or inspect (-S) a "dorun script" to execute a dorun command line with options and arguments; supports optional runtime options and arguments for dorun and/or target command, tail-delimited by ":"
                        Options -s:  script-name[:dorun-options][:docker-run-options][:dorun-update-docker-run-options]
                        Defaults:    required script-name; no persistent dorun-/docker-run-/dorun-update-docker-run-options, same dorun-update-docker-run-options as docker-run-options
                        Options -S:  environment variables to change script settings, e.g. DORUN_OPTS="-b"
                        Defaults:    enviroment variable DORUN_SCRIPT=script-name required by "dorun -S", or self-inferred by dorun script
                        Example:     -s "dopubdoc:-b:--platform linux/x86_64:-" beerst/pubdoc >dopubdoc  # "dopubdoc" script that binds current directory, adds cross-platform compatibility 

-c                    For specified running container or temporary container, launch a command-line interface (CLI); requires image with available /bin/bash
                        Equivalent:  [dorun] -d "-it" [image-spec] [container] : /bin/bash
                        Example:     -c beerst/pubdoc              # CLI for new pubdoc image container named dorun_cli__pubdoc
                        Example:     -Kc beerst/pubdoc myCLI       # CLI for new pubdoc image container named myCLI (first removes any prior active my_CLI)
                        Example:     -c dorun_wui__earestudio__80  # CLI for running container dorun_wui__earestudio__80 (to list running containers: docker container ls)
  
Other dorun options:
-D                    NOT YET IMPLEMENTED Do NOT process source-embedded dot-options
-I                    For command input, use redirected or piped input, e.g. instead of from file or terminal
-q                    Show minimum or no progress and summary messages 
-v                    Show maximum progress and summary messages
-X                    Preview eXecution commands with context, but don't execute
-h / -qh / -h[rwcs]   Show all help, or "quick help", or help with REPL/web-UI/container-admin/script-generation


Interactive processing with REPL "Read/Eval/Preview/Loop" (-r)...

To run an interactive REPL for installed image "pubdoc" to repeat-execute its _default image-named_ target command "pubdoc" on local file "myDoc.md":
: [dorun] -b -r /pubdoc -n myDoc.md

To create an auto-refresh "pubdoc_LIVE.html" file for the output file "myDoc.html" generated by "pubdoc" on local file "myDoc.md":
: [dorun] -b -R - /pubdoc -n myDoc.md


REPL works with any target command line to repeatedly execution the command line based on a specified or default repeat interval, timeout duration, or exit test.

REPL characteristics and features:

- Command line is evaluated if an exit test returns non-blank result; default exit test compares evident target command line's evident source file to evident assocated output file
- Interactive REPL command-line controls for real-time adjustment to target ommand options and more
- Automatic "live" HTML preview of evident or specified output 
- Support for multiple useful workflows, such as:
   - "Edit/preview" interactive workflow, external editor for changes to source file along with output preview in second window
   - "Edit/adjust" interactive workflow, with REPL controls to adjust settings and view results in direct ouptout or second "live" HTML preview window

REPL interactive controls:
  x | q          Exit (quit) REPL
  h | ?          Show help for dorun commands
  . | - | SPACE  Apply specified command-line option(s) to running container (see below)

Dot-options: (to interactively apply command-line options)
  . opt          (e.g. ".a")                  Add option to persistent REPL options, prepended to command-line options, source-embedded options, and persistent REPL options 
                                              (e.g. ".A" changes "command -b 123 file" to "command -A -b 123 file")
                                              Note: Will toggle option on/off for commands that support toggling
  . /opt         (e.g. "./a" or "./b 123")    Eval once, with option prepended to command-line options, source-embedded options, and persistent REPL options 
                                              (e.g. "./A" changes _once_ the "command -b 123 file" to "command -A -b 123 file")
  . ![opt]       (e.g. ".!a" or ".!")         Delete persistent REPL option (or delete all)
  ENTER          (no entry)                   Eval now

Dot-options may also be embedded and persisted in input source at start of line or after whitespace (e.g. within a source comment line), optionally followed by [\.]#-delimited comments.


Interactive web user interface (web-UI) (-w, -W, -r)...

To launch a minimal web-UI "pubdocw" for the installed or latest repo-hosted target image "pubdoc" to interactively apply its target container command "pubdoc -qI":
: [dorun] -b -w pubdocw beerst/pubdoc -qI

To launch a full-featured "EARe Studio" web-UI "earestudio" for the updated-latest (-u) repo-hosted target image "earest" to interactively apply its target container command "earest" with standard transforms (-s):
: [dorun] -K -u -b -B ${HOME}/Downloads@SAVED -w earestudio::.txt,.eare:/_EARe\.txt/ -W :earest_genWebUI.sh beerst/earest : earest -q -s -pP -I

Web-UI requirements:

- Target image must be based on Linux (e.g. from Ubuntu); target image and container are NOT required to have any intrinsic HTTP features
- Target container must have a target command plus options executable by /bin/bash and accepts a source file as input and outputs to standard-out

Web-UI characteristics and features:

- After initial launch, web-UI runs continuously, like any web server, with NO routine re-launch required
- Web-UI is accessible by any web browser on host system at URL "web-UI-name:port-num" (e.g. "localhost:82//do/myWebUI"); short-form URL w/o "/do" OK if web-UI host has public IP address
- Web-UI is accessible by web browser remotely if web-UI host system has web-UI port (e.g. default port "80") open for http I/O
- Source content to apply may be entered directly into source text area, or selected from the local system with "choose" button, or loaded by drag-dropping local file onto "choose"
- "Focus-file" feature enables application of a candidate file on the web-UI host system, such as a default source file for web-UI run on same system; candidates discovered by:
   - Directories to search set by -b (for current directory) and -B (for directory name-tagged as "SAVED")
   - Evident specified focus filename or filepath in top few lines of applied source textarea
   (Note this feature is available and apparent only in web browser running on same system as web-UI)
- Default focus-file candidate selection supports use of the latest modified file for additional useful workflows, such as:
   - Restoring work in progress across mutiple web-UI sessions
   - External editor for editing source file
   - "Auto-apply" during interactive workflow, using -r option
   (Note these workflows are generally restricted by web browser security constraints to web-UI running on local system, with candidate local directories specified by -b/-B)
- Web-UI requires no customization for basic, full-featured workflow; defaults for web-UI title, headings, and other UI elements provide necessary context 
- Web-UI may be customized by -w/-W/-r command-line options at launch, or dynamically by web-UI "generator" command specified by -W at launch
- Custom web-UI generation modifies default web-UI layout and its customizable web-UI feature placeholders, to create each applied instance of web-UI, including presented web content 
   - For details and examples of default layout, placeholders, and modifiable feature specifations, see reference files temporarily available after launch, listed in launch summary message
- Auto-apply command-line option -r customizes web-UI with a fully-interactive experience that require NO user action to continually refresh content presentation   
   - Combined with focus-file feature, auto-apply supports "two-window" workflow with source file editing with an external editor, and "live" results in separate web-UI window
- Target command dot-options UI available if enabled by web-UI customizations, with optional _dorun_ options tail-delimited by ".:"

- Tip: Generated files used by web-UI "save" features remain available temporarily at host system URL "/tmp"


dorun script generation/inspection (-s, -S) and features...

A dorun script generated by "dorun -s" can simplify running a target command with fixed specifications for dorun options, target image and container, and base target command line options and arguments.

To create a simple dorun script (-s) "dopubdoc" for repo-hosted target image "pubdoc" to execute its (default) same-named container command ""pubdoc" and attach host system stdin to its container:
: [dorun] -s dopubdoc:-I -b beerst/pubdoc >dopubdoc; chmod a+x dopubdoc   # Generate script "dopubdoc" that includes fixed "durun" options "-I -b", save it, and make it executable

At runtime, additional target command options and arguments may follow the script name in the command line, as with any command-line utility:
: dopubdoc -n myDoc.md   # Install/use latest repo-hosted "dorun" to install/run a repo-hosted latest "pubdoc" image to execute a temporary container base command "pubdoc -b" with added command option "-n" to process "myDoc.md"

To create a dorun script (-s) "doearestudio" for the repo-hosted target image "earest" to launch full-featured web-UI "earestudio":
: [dorun] -s "doearestudio:-K -b -B ${HOME}/Downloads@SAVED -w earestudio\:80\:.txt,.eare\:/_EARe\.txt/ -W \:earest_genWebUI.sh" beerst/earest -q -s -pP >doearestudio; chmod +x doearestudio

The "-S" option can simplify replicating or creating variations of existing dorun scripts, for incremental changes or different versions, by specifying only the _modifications_ to script-specification variables such as DORUN_OPTS.

For complete specifications about a script, including ways to customaize its behavior:
: doearestudio -S :  # Note trailing ":" colon
 ...or for shorter "quick-inspect"...
: doearestudio -qS :

To specify a script to inspect:
: DORUN_SCRIPT=dopubdoc dorun -S

To change script specifications before running, set related environment variables:
: DORUN_OPTS="-b" dopubdoc myDoc.md

Generally, to create any dorun script for a target image/container/command-line:
: [dorun] -s "script-name[:dorun-/:docker-exec-/:dorun-update-docker-run-options]" execution-target-specs

The -s argument "script-name" is required, and should match the name used for the saved script file. "dorun-runtime-options" specifies dorun options (e.g. "-b") to include in fixed specifications.

Special-purpose "docker-run-options" and "dorun-update-docker-run-options" specify which "docker run -d" and "docker run" options to apply when executing the command line or updating the dorun container, respectively.
These "docker-run" options may be used to e.g., specify a docker "--platform linux/x86_6" to make an image run on non-x86 systems. For "dorun-update-docker-run-options", specify "-" to have it match "docker-run-options".

To customize a dorun script, add statements to (only) its top section. Subsequent script inspection with -[h]S will preserve these custom statements, for potential replication by -s script generation.

Script _execution_ characteristics and features:

- Adjust runtime options for dorun, tail-delimited with colon ":", e.g.:           doMyScript.sh -v -b  :  ...
- Preview eXecution commands with context, but don't execute:                      doMyScript.sh -X  ...
- Force-update script's installed target image (-u) and dorun_utility (-U):        doMyScript.sh -uU : ...
- Attach host system stdin to container command that processes stdin:              doMyScript.sh -I : ... 
- Inspect script to replicate or create a variation (and save custom statements):  doMyScript.sh -S
- Change script default specifications with associated environment variables:      SCRIPT_CMD, IMAGE_SPEC, DORUN_OPTS, RUN_OPTS, TMPDIR, DORUN_IMAGE_SPEC, DORUN_UPDATE_RUN_OPTS
(See generated script-specified settings and documentation at the top of a generated script to learn more!)

dorun: From image beerst/dorun, runs container command dorun
- Runs dorun with option(s) -b, plus runtime options and arguments
- Uses compact dorun syntax, typical default options, target command options and arguments, and enhanced execution features; requires bash shell

Usage:                   dorun [dorun-opts-continued ] command-line-continued

Runs:                    [dorun]  dorun dorun_exec -b ...

Installs/updates dorun:  docker run --rm [pull_opt]  beerst/dorun ... >/tmp/dorun_exec__dorun

For script summary:      dorun -hS
For more about dorun:    dorun -qh :

Created 2026.09.14 07:44 by: [dorun] -s 'dorun:::' beerst/dorun dorun_exec -b

Usage tips:
- Make script executable:                                             chmod a+x dorun
- Adjust dorun runtime options, tail-delimit with colon ":"; e.g.:    dorun -v -b ...
- Preview eXecution commands with context, but don't execute:         dorun -X ... ...
- Use redirected or piped input, e.g. instead of file or terminal:    dorun -I ... ...
- Backslash-escape quoted command options (e.g. those with spaces):   dorun -a 123 -b \'Hello World\'
- Force-update installed target image (if applicable):                dorun -u ...
- Force-update dorun's installed dorun utility (note trailing ":"):   dorun -U :
- Change script defaults with associated environment variables:       SCRIPT_CMD, IMAGE_SPEC, DORUN_OPTS, RUN_OPTS, DORUN_IMAGE_SPEC, DORUN_UPDATE_RUN_OPTS
- Inspect to learn or adjust specs (e.g. by "DORUN_OPTS='-b'"):       dorun -S :
- (Re)install latest release of this script (if applicable):          docker run --pull always beerst/dorun cat dorun >dorun; chmod a+x dorun

Summary date:               Mon Sep 14 07:50:11 PDT 2026
Help with build/deploy/release:     make help-build
Build summary:              dorun_summary.txt  	(or: make summary)
README markdown:            dorun_README.md  	(or: make readme)
Help with run/launch/admin: dorun_admin_help.txt  	(or: make help-admin)
makefile for admin tasks:   dorun_admin_makefile  	(for use on host system)

Settings from make command-line arg=value, dockerfile directives, env variables, or defaults:
  Dockerfile:               dorun_dockerfile  	(default: most-recently-touched file in current dir with name *[dD]ockerfile*)
  Image      VERSION:       2609140750    (default: "WIP")
  Image      NAME:          dorun  	(default: basename of dockerfile [first] WORKDIR)
  Base image BASE:          ubuntu  	(from dockerfile FROM)
  Docker     BUILD_ARGS:    NA=n/a        (from environment or n/a, to apply during build)
  Git        GIT_REPO:        	(from git environment or n/a; uncommitted files or n/a: )
  Docker     DOCKER_REPO:   beerst  	(required for "release" and for _remote_ "deploy", or n/a)
  Options: (typically from same-named dockerfile ARG/ENV)
    OPTS_RUN_TEST:          
    OPTS_RUN_PROD:          
    OPTS_LAUNCH_TEST:       
    OPTS_LAUNCH_PROD:       
    OPTS_SHELL_TEST:        
    OPTS_SHELL_PROD:        

Available make actions:
  build, build-clean, deploy, release, summary, help

Custom actions from dockerfile ARG/ENV or environment variables OPTS_CUSTOM_action, or applied directly by dorun_admin_makefile (or n/a):
  
Uncommited local changes not pushed to git repo  (or n/a):
  

Files and directories COPYed from sources to image destination (or n/a):
  dorun_exec   /bin
  dorun        .
  dorun_admin_makefile dorun_dockerfile                 .
  dorun_summary.txt dorun_admin_help.txt dorun_README*  .
 
README markdown for e.g. image/usage description in repository (or n/a):
  dorun_README.md