Command Line Interface

Every whitehall command. The five you will use daily have pages of their own; this is the full surface.

Project

Command	What it does
`init <name>`	Create a new project
`build <source>`	Any source → an image in the store. The only verb that takes source
`run <image>`	An image, as a tool: install hidden, launch, stream the output here
`install <image>`	An image, as an app: an icon in the drawer
`dev`	The `.wh` edit loop — watch, rebuild, hot-reload
`images`	List the store: name, door, size, source. `--all` includes scratch runs
`package <image>`	Write it out as `<name>.apk`, to hand to another phone
`compile`	Transpile to Kotlin only — no APK
`check`	Check syntax without building. The fast one
`clean`	Remove this project's build artifacts

Cleaning

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

Command	What it does
`clean`	Build output, plus the images nothing can rebuild or nobody asked for
`clean --programs`	Uninstall the programs `cargo run` left on the phone
`clean --programs --all`	Those the ones `install` gave an icon, too
`clean --images`	Empty the image store
`clean --packages`	Empty the Termux package cache

compile, build, install and run all accept a single .wh file as well as a project directory, so a one-file experiment does not need a whitehall.toml.

Code quality

Command	What it does
`format`	Format `.wh` files. Opinionated, zero-config
`format --check`	Fail if anything is unformatted. For CI
`lint`	Lint for errors and style
`lint --fix`	Apply the fixable ones

Dependencies

Command	What it does
`deps add <dep>`	Add a dependency to `whitehall.toml`, resolving the version
`deps add --dev <dep>`	Add as a test dependency
`deps remove <dep>`	Remove one
`deps list`	List every dependency with its resolved version

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.

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.

Command	What it does
`toolchain install`	Pre-download everything this project needs
`toolchain list`	Show what is installed
`toolchain clean`	Remove all cached toolchains
`doctor`	What this machine has, and what to type next

`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 Blazer · 4B141FDCH0001U

        Here a tool — Cargo.toml

  whitehall shell      then `cargo run`, on the phone

    Finished everything is here

doctor reads the disk and downloads nothing, so it is safe on a bad connection — a missing thing is a line, not a wait. Nothing it reports is an error: the toolchain fetches what it needs at the moment it needs it.

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:

Command	What it does
`exec <cmd>`	Run a command with the project's toolchain environment
`which <cmd>`	Where that command resolves to. Alias for `exec which`
`shell`	An interactive shell with the environment already set

whitehall exec java -version
whitehall which gradle
whitehall shell

Devices and emulators

Command	What it does
`device`	List the phones this machine can reach
`emulator`	Manage emulators — list, start, create
`adb …`	Run `adb` from the managed SDK
`emu …`	Run the emulator binary directly, e.g. `whitehall emu -avd myavd`
`avdmanager …`	Manage Android Virtual Devices

$ whitehall device
      Device Blazer · 4B141FDCH0001U
       Found 1 device

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.

whitehall run myapp -d blazer
whitehall test -d 4B14
whitehall clean --programs -d "pixel 10 pro"

whitehall emulator list
whitehall emulator start <name>
whitehall adb logcat

Use whitehall adb rather than a system adb. It is the one from the SDK this project builds against, so it cannot disagree with the APK you just installed.

Wear OS

whitehall build --wear
whitehall run --wear

See Wear OS.

Command Line Interface

Project

Cleaning

Code quality

Dependencies

Toolchain

whitehall doctor

Borrowing the environment

Devices and emulators

Naming a phone

Wear OS

See Also

`whitehall doctor`