Skip to main content

​
Overview

The Droidrun CLI lets you control Android and iOS devices using natural language commands powered by LLM agents.

​
Quick Start

# Setup device
droidrun setup

# Run a command (shorthand - no "run" needed)
droidrun "Open Spotify and play my Discover Weekly"

# Or explicit
droidrun run "Turn on Do Not Disturb"
Auto-configuration: If config.yaml doesn’t exist, Droidrun creates it from config_example.yaml automatically.Command shorthand: droidrun "task" is equivalent to droidrun run "task"

​
Commands

  • run
  • Device Management
  • Macros
Execute natural language commands on your device.

​
Usage

droidrun run "<command>" [OPTIONS]

# Shorthand (omit "run")
droidrun "<command>" [OPTIONS]

​
Common Flags

FlagDescriptionDefault
--provider, -pLLM provider (GoogleGenAI, OpenAI, Anthropic, etc.)From config
--model, -mModel nameFrom config
--device, -dDevice serial or IPAuto-detect
--stepsMax execution steps15
--reasoningEnable planning modefalse
--visionEnable vision for all agentsFrom config
--tcpUse TCP instead of content providerfalse
--debugVerbose loggingfalse
--save-trajectorySave execution (none, step, action)none
--config, -cCustom config pathconfig.yaml

​
Examples

  • Basic
  • LLM Providers
  • Advanced
# Simple command
droidrun "Open Settings"

# Multi-step task
droidrun "Send WhatsApp to John: I'll be late"

# Specific device
droidrun "Check battery" --device emulator-5554

​
Provider Options

ProviderInstallEnvironment Variable
GoogleGenAIuv pip install 'droidrun[google]'GOOGLE_API_KEY
OpenAIuv pip install 'droidrun[openai]'OPENAI_API_KEY
Anthropicuv pip install 'droidrun[anthropic]'ANTHROPIC_API_KEY
DeepSeekuv pip install 'droidrun[deepseek]'DEEPSEEK_API_KEY
Ollamauv pip install 'droidrun[ollama]'None (local)

​
Configuration

​
Override Priority

  1. CLI flags (highest)
  2. Config file (config.yaml)
  3. Defaults (lowest)

​
Common Patterns

droidrun "Turn on dark mode" \
  --provider GoogleGenAI \
  --model models/gemini-2.5-flash

​
Troubleshooting

# Check ADB
adb devices

# If unauthorized: Accept prompt on device
# If not listed: Try different USB port/cable
# Restart ADB
adb kill-server && adb start-server

# Verify installation
adb shell pm list packages | grep droidrun

# Reinstall
droidrun setup

# Enable accessibility manually
adb shell settings put secure enabled_accessibility_services \
  com.droidrun.portal/.DroidrunAccessibilityService

# Install provider
uv pip install 'droidrun[google,openai,anthropic]'

# Check API key
echo $GOOGLE_API_KEY

# Set if missing
export GOOGLE_API_KEY=your-key

# Increase steps
droidrun "Complex task" --steps 50

# Enable debug mode
droidrun "Task" --debug

# Try reasoning mode
droidrun "Multi-step task" --reasoning

# Enable TCP mode (USB connected first)
adb tcpip 5555

# Get device IP
adb shell ip route | awk '{print $9}'

# Connect
droidrun connect <IP>:5555

# Verify
droidrun ping --tcp

​
Environment Variables

VariableDescriptionDefault
GOOGLE_API_KEYGoogle Gemini API keyNone
OPENAI_API_KEYOpenAI API keyNone
ANTHROPIC_API_KEYAnthropic API keyNone
DEEPSEEK_API_KEYDeepSeek API keyNone
DROIDRUN_CONFIGConfig file pathconfig.yaml
Setting variables: 
export GOOGLE_API_KEY=your-key

​
Next Steps