Skip to content

CLI Reference

The droidfarm CLI interacts with a DroidFarm cluster via the Kubernetes API.

Installation

# Coming soon
brew install christopherime/tap/droidfarm

Download the latest binary for your platform from the GitHub Releases page.

# Linux amd64
curl -Lo droidfarm https://github.com/christopherime/droidfarm/releases/latest/download/droidfarm-linux-amd64
chmod +x droidfarm && sudo mv droidfarm /usr/local/bin/

git clone https://github.com/christopherime/droidfarm.git
cd droidfarm
make build-cli
# Binary at: bin/droidfarm

Global flags

  -n, --namespace string    Kubernetes namespace (default "droidfarm-system")
      --kubeconfig string   Path to kubeconfig file (default: KUBECONFIG env or ~/.kube/config)
      --context string      kubectl context to use

Commands

droidfarm get pools

List all DevicePools and their device status.

droidfarm get pools

NAME            TEMPLATE            MIN  MAX  READY
staging-pool    android14-basic     1    8    3
ci-pool         android13-ci        2    4    2

droidfarm get sessions

List all TestSessions.

droidfarm get sessions

NAME                   POOL           PHASE     ENDPOINT                   AGE
myapp-e2e-7x9k2        staging-pool   Running   http://10.0.0.5:4723/...   2m
myapp-e2e-3p1ls        staging-pool   Pending   -                          10s

droidfarm get templates

List all DeviceTemplates.

droidfarm get templates

NAME                ANDROID  PROFILE
android14-basic     14       pixel_6
android13-ci        13       pixel_4a

droidfarm submit-test

Create a TestSession and optionally wait for it to reach Running state.

droidfarm submit-test --pool staging-pool --timeout 45m

Created TestSession: myapp-e2e-7x9k2
Waiting for session to reach Running...
[10:23:01] Phase: Pending
[10:23:15] Phase: Preparing
[10:23:47] Phase: Running

AppiumEndpoint: http://10.0.0.5:4723/wd/hub
StreamURL:      https://droidfarm.example.com/stream/myapp-e2e-7x9k2

Flags:

Flag Default Description
-p, --pool required DevicePool name
--timeout 30m Session timeout
--appium-configmap "" ConfigMap name with Appium capabilities
-w, --wait true Wait until Running or Failed

droidfarm watch-session <name>

Watch a TestSession and print phase transitions in real time.

droidfarm watch-session myapp-e2e-7x9k2

[10:23:01] Phase: Pending
[10:23:15] Phase: Preparing
[10:23:47] Phase: Running
  AppiumEndpoint: http://10.0.0.5:4723/wd/hub
  StreamURL:      https://droidfarm.example.com/stream/myapp-e2e-7x9k2
[10:54:12] Phase: Succeeded

Flags:

Flag Default Description
--timeout 60m Maximum watch duration

droidfarm delete session <name>

Delete a TestSession (the device is released back to the pool).

droidfarm delete session myapp-e2e-7x9k2

TestSession "myapp-e2e-7x9k2" deleted

droidfarm complete session <name>

Mark a TestSession as Succeeded or Failed, releasing the device back to the pool. Use this when your external test runner finishes and you want to signal the result.

droidfarm complete session myapp-e2e-7x9k2 --result pass
droidfarm complete session myapp-e2e-7x9k2 --result fail

TestSession "myapp-e2e-7x9k2" marked as Succeeded

Flags:

Flag Default Choices
-r, --result pass pass, fail, error

droidfarm logs session <name>

Stream logs from the device pod assigned to a TestSession.

droidfarm logs session myapp-e2e-7x9k2
droidfarm logs session myapp-e2e-7x9k2 --container appium --follow

... Cuttlefish startup output ...
2026-05-09T10:23:44.001Z INFO  webrtc: listening on :8443
2026-05-09T10:23:47.322Z INFO  adb: device connected

Flags:

Flag Default Description
--container cuttlefish Container: cuttlefish, appium, apk-installer
--tail 100 Number of lines to tail (0 = all)
--follow false Stream logs continuously

droidfarm get-artifact <session>

Print artifact location information for a completed TestSession.

droidfarm get-artifact myapp-e2e-7x9k2 --output ./test-results/

If status.artifactURL is set, prints a curl download command. If status.deviceRef is set, prints a kubectl cp command to copy recordings from the pod.

Flags:

Flag Default Description
-o, --output ./artifacts/ Local output directory