whitehall run

Start it and attach me to its output.

Usage

whitehall run <image | path> [-- args…]

run installs the image, launches it, and streams what it says into your terminal. That is one meaning, not two — what varies is the transport:

The image is	You get
a tool (a crate, a script, a Go or Zig program)	its stdout and stderr over the socket, and its exit code. It feels like running it locally
an app (a .wh project)	a force-stop, a cleared logcat, a launch, and logcat streamed here

Whitehall's own lines go to stderr while it runs, the way cargo's do, so whitehall run tool > out.png produces the file it would on a laptop.

Source, or a name

Both work. Which one you meant is decided the way a shell decides it — ./script versus script on $PATH:

whitehall run .          # build this directory, then run what came out
whitehall run ./foo      # build foo/, then run it
whitehall run foo        # the image called foo, already in the store

A bare word is always an image name, even when a directory of that name is sitting right there. whitehall run . is build . piped into run, with the build's own cache deciding whether any work happens — nothing bypasses the store, and there is one cache rather than two.

Arguments

Anything after the image, or after --, belongs to the program:

whitehall run mytool --name phone
whitehall run mytool -- --release   # `--` when the flag would collide

An app takes no argv. Saying so beats accepting the words and dropping them somewhere the author will never find them.

Options

Flag	What it does
-d, --device <id>	Which phone. Takes a serial, the start of one, or the model name (-d pixel). Auto-selects when only one is connected
-r, --release	Build a release image first (default: debug). Only for the form that takes a path

whitehall device lists what is connected.

run versus install

Two verbs on one image. Neither is an "app mode" or a "tool mode":

Verb	Means
run	Start it and attach me to its output
install	Put it on the phone, launchable by hand

An image ships with its launcher entry disabled, so a fresh run leaves no icon in the drawer — and a run on one you already installed does not take the icon away. install is the verb that enables it.

This is not the edit loop

Iteration belongs to the language's own toolchain inside the context:

whitehall shell
(whitehall) $ cargo run          # a tool: built for the phone, run there, output here
(whitehall) $ python3 main.py    # the phone's Python
(whitehall) $ go run .           # and `go test ./...`

For an app, which has no other toolchain, the loop is whitehall dev — watch, rebuild, hot-reload. There is no run --watch.

Logs and cleanup

whitehall adb logcat                  # adb, with the managed SDK
whitehall clean --programs            # uninstall what `cargo run` left on the phone
whitehall clean --programs --all      # those given an icon by `install`, too
whitehall images                      # what's in the store
whitehall images --all                # including scratch runs

See Also

• whitehall build — any source → an image
• whitehall dev — the edit loop for an app
• install, images, package, clean
• whitehall logs — logcat that names your .wh files
• All commands