The pocketshare CLI

pocketshare does everything the website does from a terminal: search phones, rent one with a spending cap, connect it to adb and Android Studio, install builds, take screenshots, read Logcat and end the rental. Every command takes --json for scripts and CI.

Install

The CLI is one executable with no dependencies. Download the file for your computer from https://pocketshare.io/downloads/cli/latest/ (the newest release; each version also stays at https://pocketshare.io/downloads/cli/<version>/), with SHA256SUMS and its signature:

Platform	File
Windows (x64)	`pocketshare-windows-x64.exe`
macOS (Apple silicon)	`pocketshare-darwin-arm64`
macOS (Intel)	`pocketshare-darwin-x64`
Linux (x64)	`pocketshare-linux-x64`
Linux (arm64, Raspberry Pi)	`pocketshare-linux-arm64`

macOS and Linux
Windows

base=https://pocketshare.io/downloads/cli/latest
curl -fsSLO "$base/pocketshare-linux-x64" -O "$base/SHA256SUMS" -O "$base/SHA256SUMS.sig"
# Check the download against the signed checksums (see below), then:
chmod +x pocketshare-linux-x64
sudo mv pocketshare-linux-x64 /usr/local/bin/pocketshare
pocketshare version

On macOS the executables aren’t notarized yet: the first time, allow it under System Settings › Privacy & Security, or run xattr -d com.apple.quarantine pocketshare.

$base = "https://pocketshare.io/downloads/cli/latest"
$ProgressPreference = "SilentlyContinue"   # much faster downloads in Windows PowerShell
foreach ($f in "pocketshare-windows-x64.exe", "SHA256SUMS", "SHA256SUMS.sig") {
  Invoke-WebRequest "$base/$f" -OutFile $f
}
# Check the download against the signed checksums (see below): the two hashes must match.
(Get-FileHash pocketshare-windows-x64.exe -Algorithm SHA256).Hash.ToLower()
Select-String pocketshare-windows-x64.exe SHA256SUMS
# Put it in a folder and add that folder to your PATH (open a new terminal afterwards):
$dir = "$env:LOCALAPPDATA\PocketShare"
New-Item -ItemType Directory -Force $dir | Out-Null
Move-Item pocketshare-windows-x64.exe "$dir\pocketshare.exe"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$dir", "User")
& "$dir\pocketshare.exe" version

The signature check below needs OpenSSL 3 (the openssl in Git for Windows is often 1.1, which lacks -rawin). The executable isn’t code-signed yet, so SmartScreen may show “Windows protected your PC”: choose More info, then Run anyway.

Check the download

Every release has SHA256SUMS and release-manifest.json, each with a detached Ed25519 signature (.sig) made with the PocketShare release key (pocketshare-release-2026.pub.pem, key oLkDjloA3xXQmioSxTrBuKFygyrt867Jrm3PNSyyLSE). Save the key, then check the signature and your file (OpenSSL 3 or later):

cat > pocketshare-release-2026.pub.pem <<'EOF'
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAoLkDjloA3xXQmioSxTrBuKFygyrt867Jrm3PNSyyLSE=
-----END PUBLIC KEY-----
EOF
openssl pkeyutl -verify -pubin -inkey pocketshare-release-2026.pub.pem -rawin \
  -in SHA256SUMS -sigfile SHA256SUMS.sig
sha256sum --ignore-missing -c SHA256SUMS

You need adb (Android SDK platform-tools) only for pocketshare connect and run. The CLI uses --adb PATH, $ADB, the SDK in $ANDROID_HOME or $ANDROID_SDK_ROOT, the SDK where Android Studio installs it (%LOCALAPPDATA%\Android\Sdk, ~/Library/Android/sdk or ~/Android/Sdk), or adb on your PATH, in that order.

pocketshare login

login prints a link to pocketshare.io with the code already filled in (https://pocketshare.io/app/device?code=…). Open it, check that the code matches the one in your terminal and approve it; the CLI stores an API key for your account (readable only by you). With a key you already have:

pocketshare login --api-key -        # reads the key from stdin, so it stays out of your history

In CI, set POCKETSHARE_API_KEY instead; nothing is stored. POCKETSHARE_API_URL points the CLI at another API (for example a local one).

Rent and use a phone

pocketshare phones search --android ">=13" --max-price 5
pocketshare rent <phone-id> --max-spend 2          # a spending cap is required
pocketshare sessions                               # your rentals
pocketshare install app-debug.apk                  # the rental may be left out with one open
pocketshare screenshot -o screen.png
pocketshare logcat --package com.example.app --priority E
pocketshare connect                                # the phone appears in `adb devices`
pocketshare open                                   # the rental in your browser
pocketshare stop                                   # end it: billing stops, the phone is wiped

Command	What it does
`login`, `logout`, `whoami`	Sign in (device code or `--api-key`), forget the key (it stays valid until you revoke it on pocketshare.io’s API keys page), show the account.
`phones search`, `phones show`	Find phones by model, brand, Android version and price.
`rent <phone-id> --max-spend $`	Rent with a spending cap; `--connect` connects when ready; `--agent` makes it an agent rental. Instead of an ID, `--model`, `--brand`, `--android` and `--max-price` rent the cheapest match, and `--wait 10m` waits for one to be free.
`sessions` (or `rentals`), `status [<rental>]`	Your rentals; one rental’s state and cost.
`connect [<rental>]`	Local ADB endpoint for Android Studio, adb, scrcpy and test tools.
`install [<rental>] <apk or https URL>`	Install or update an app (`--grant` grants runtime permissions).
`screenshot [<rental>] [-o file.png]`	Save a screenshot.
`logcat [<rental>]`	Recent Logcat lines (`--lines`, `--package`, `--priority`, `--filter`, `--clear`).
`open [<rental>]`	Open the rental’s page on pocketshare.io (`--print` just prints the link).
`stop [<rental>]`	End the rental.
`balance`, `usage`	Credit, and what recent rentals cost.
`topup [--amount $]`	Add credit on pocketshare.io.
`agent-limits [--daily $] [--idle-minutes N]`	Limits for AI agent rentals (see MCP server).
`mcp`	Run the MCP server for AI agents over stdio.
`run [filters] --max-spend $ -- <command>`	For CI: rent, connect, run the command with `ANDROID_SERIAL` set, save artifacts and always end the rental (Use PocketShare in CI).

Exit codes

Code	Meaning
0	Done
1	Failed (for example the install failed or the rental ended)
2	Bad usage: unknown command or option
3	Not signed in, key revoked, or the key lacks the permission
4	Credit or a spending limit stopped it
5	PocketShare unreachable or busy; retry later
6	No matching phone available (`rent` and `run` by model or filters, after `--wait`)

With --json, every command prints one JSON object; errors print {"error": "<code>", "message": "..."} and still set the exit code.

In CI

pocketshare run rents a phone, connects it to adb, runs your tests with ANDROID_SERIAL set, saves a screenshot and Logcat, and always ends the rental, with templates for GitLab CI and GitHub Actions: see Use PocketShare in CI.

export POCKETSHARE_API_KEY=psk_…            # a key with phones:read, rentals:read and rentals:write
pocketshare run --model "Pixel 9a" --max-spend 1 --wait 10m --timeout 30m   --artifacts artifacts -- ./gradlew connectedDebugAndroidTest

For scripts that drive the steps themselves, rent --json prints the rental ID:

rental=$(pocketshare rent --model "Pixel 9a" --max-spend 1 --wait 10m --json | jq -r .rentalId)
pocketshare install "$rental" app/build/outputs/apk/debug/app-debug.apk
pocketshare screenshot "$rental" -o artifacts/screen.png
pocketshare stop "$rental"