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 Flag Description Default --provider, -pLLM provider (GoogleGenAI, OpenAI, Anthropic, etc.) From config --model, -mModel name From config --device, -dDevice serial or IP Auto-detect --stepsMax execution steps 15--reasoningEnable planning mode false--visionEnable vision for all agents From config --tcpUse TCP instead of content provider false--debugVerbose logging false--save-trajectorySave execution (none, step, action) none--config, -cCustom config path config.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
# Google Gemini export GOOGLE_API_KEY = your-key droidrun "Archive old emails" \ --provider GoogleGenAI \ --model models/gemini-2.5-flash # OpenAI export OPENAI_API_KEY = your-key droidrun "Create shopping list" \ --provider OpenAI \ --model gpt-4o # Anthropic Claude export ANTHROPIC_API_KEY = your-key droidrun "Reply to latest email" \ --provider Anthropic \ --model claude-sonnet-4-5-latest # Local Ollama (free) droidrun "Turn on dark mode" \ --provider Ollama \ --model llama3.3:70b \ --base_url http://localhost:11434
# Complex task with planning droidrun "Organize inbox by sender" \ --reasoning \ --vision \ --steps 30 # Debug failing command droidrun "Book Uber to airport" \ --debug \ --save-trajectory action # Wireless execution droidrun "Clear cache" \ --device 192.168.1.100:5555 \ --tcp # Custom config droidrun "Enable 2FA" \ --config /path/to/config.yaml
Provider Options Provider Install Environment Variable GoogleGenAI uv pip install 'droidrun[google]'GOOGLE_API_KEYOpenAI uv pip install 'droidrun[openai]'OPENAI_API_KEYAnthropic uv pip install 'droidrun[anthropic]'ANTHROPIC_API_KEYDeepSeek uv pip install 'droidrun[deepseek]'DEEPSEEK_API_KEYOllama uv pip install 'droidrun[ollama]'None (local)
droidrun devicesList connected devices. droidrun devices # Output: # Found 2 connected device(s): # • emulator-5554 # • 192.168.1.100:5555
droidrun setupInstall Portal APK on device. # Auto-detect device droidrun setup # Specific device droidrun setup --device emulator-5554 # Custom APK droidrun setup --path /path/to/portal.apk
What it does:
Downloads latest Portal APK
Installs with all permissions
Auto-enables accessibility service
Opens settings if manual enable needed
droidrun pingTest Portal connection. # Test default communication droidrun ping # Test TCP mode droidrun ping --tcp # Specific device droidrun ping --device 192.168.1.100:5555
Success output: Portal is installed and accessible. You're good to go!droidrun connectConnect to device via TCP/IP. droidrun connect 192.168.1.100:5555
Prerequisites: # Enable wireless debugging (Android 11+) # Settings > Developer options > Wireless debugging # Or via USB: adb tcpip 5555 adb shell ip route | awk '{print $9}' # Get IP droidrun connect < I P > :5555
droidrun disconnectDisconnect from device. droidrun disconnect 192.168.1.100:5555
Record and replay automation sequences. droidrun macro listList saved trajectories. # Default directory droidrun macro list # Custom directory droidrun macro list /path/to/trajectories
Output: Found 3 trajectory(s): ┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓ ┃ Folder ┃ Description ┃ Actions ┃ ┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩ │ open-settings │ Opens settings app │ 3 │ │ enable-dark-mode │ Navigate to display... │ 8 │ └──────────────────┴───────────────────────────┴─────────┘
droidrun macro replayReplay recorded macro. # Basic replay droidrun macro replay trajectories/open-settings # Custom device and timing droidrun macro replay trajectories/login-flow \ --device emulator-5554 \ --delay 0.5 # Start from specific step droidrun macro replay trajectories/checkout \ --start-from 5 \ --max-steps 10 # Preview without executing droidrun macro replay trajectories/test --dry-run
Flags: Flag Description Default --device, -dDevice serial Auto-detect --delay, -tSeconds between actions 1.0--start-from, -sStart step (1-based) 1--max-steps, -mMax steps to run All --dry-runPreview only false
Recording Trajectories # Record at action level (most detailed) droidrun "Create alarm for 7am" --save-trajectory action # Record at step level droidrun "Export contacts" --save-trajectory step
Trajectory structure: trajectories/2025-10-16_14-30-45/ ├── macro.json # Action sequence ├── step_0.png # Screenshots ├── step_1.png └── ...
Configuration Override Priority
CLI flags (highest)Config file (config.yaml)Defaults (lowest)
Common Patterns Quick Test
Debug Task
Cost Optimization
Multiple Devices
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 < I P > :5555 # Verify droidrun ping --tcp
Environment Variables Variable Description Default GOOGLE_API_KEYGoogle Gemini API key None OPENAI_API_KEYOpenAI API key None ANTHROPIC_API_KEYAnthropic API key None DEEPSEEK_API_KEYDeepSeek API key None DROIDRUN_CONFIGConfig file path config.yaml
Setting variables: Linux/macOS
Windows PowerShell
Permanent (Linux/macOS)
export GOOGLE_API_KEY = your-key
Next Steps 
