Command Line Interface

Every whitehall command, as whitehall --help lists them. The ones with a page of their own link to it; this is the full surface.

Global flag

Interactive is the default: where a verb needs a phone and finds two, it draws a menu. --non-interactive turns that off, for a script that would rather have the error. WHITEHALL_NON_INTERACTIVE or CI in the environment does the same, and so does not being at a terminal.

Making and running

Source, or a name

build, install, run and package all take either. Which one you meant is decided the way a shell decides it — ./script versus script on $PATH:

So whitehall install . is build . piped into install, with the build's own cache deciding whether any work happens. Nothing bypasses the store, and there is one cache rather than two.

Cleaning

Plain clean belongs to a project, the way cargo clean does: with no whitehall.toml it refuses and does nothing. The flags are global and work from anywhere.

Checking

Code quality

Dependencies and packages

whitehall deps add io.coil-kt/coil-compose
whitehall deps add --dev io.mockk/mockk
whitehall deps list

The top-level add, remove and update are the Termux package verbs — the phone's own libraries, in [packages]. Given a Maven coordinate they print the deps spelling and exit 1. The tables these write to are documented under Configuration.

Signing

Toolchain

Java, Gradle and the Android SDK are downloaded and managed for you, cached in ~/.whitehall/toolchains/ and shared across projects while staying version-isolated. There is no separate setup step — the first build fetches what it needs.

whitehall doctor

The first thing to run, and the thing to run when something is wrong. It reports the SDK and adb, the NDK, the Android target for cargo, CPython, Go, Java and Gradle, and every device on adb by name — then says which door this directory is and the one command that opens it.

       Found the Android SDK and adb in ~/.whitehall/toolchains/android
       Found the NDK 26.1.10909125
       Found CPython 3.13.9-0 for arm64-v8a
      Device Pixel · 1A2B3C4D5E6F7G

        Here a tool — Cargo.toml

  whitehall shell      then `cargo run`, on the phone

    Finished everything is here

Borrowing the environment

The managed toolchain is not on your PATH, which is deliberate — it is what keeps projects from fighting over versions. These let you reach into it anyway:

whitehall exec java -version
whitehall which gradle
whitehall shell

Devices and emulators

$ whitehall device
      Device Pixel · 1A2B3C4D5E6F7G

Naming a phone

Every verb that touches a device takes -d/--device, and it means the same thing everywhere. Give it a serial, the start of one, or the model name — the name the status lines have been using all along. Case and _, - and spaces are ignored, so Pixel_10_Pro_XL, "pixel 10 pro xl" and pixel10pro are the same query. Two matches is a refusal that lists them, never a guess. $ANDROID_SERIAL and whitehall device pin choose a phone when -d is absent.

whitehall run myapp -d pixel
whitehall test -d 1A2B
whitehall clean --programs -d "pixel 10 pro"

Wear OS

whitehall build --wear
whitehall dev --wear

See Wear OS.

See Also

• whitehall dev — the edit loop
• whitehall run — start it and attach to its output
• whitehall build — release builds and signing
• Configuration — what these commands read and write