Users¶

Android users on a connected device — listing, inspecting, creating, starting, switching, and removing users, and reading user state and capabilities. Relevant on multi-user devices (work profiles, guest users, Android Automotive).

`create_user` ¶

Create a full secondary Android user on a device: adb shell pm create-user NAME.

Creates the user only — it does not switch to it (use switch_user separately if that's the goal). name is shell-quoted before being sent to the device, verified live to handle spaces and shell metacharacters safely.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`name`	`str`	Display name for the new user. Can contain spaces.	required

Returns:

Type	Description
`CreateUserResult`	The serial, the newly assigned user_id, and the name requested.

Error handling

Propagates the same way most tools do (unlike check_adb_available): if the adb binary itself can't be found or is unresponsive, or the serial doesn't match a connected device, that surfaces as an actual tool error. Only the unreachable-serial failure path was verified live for this specific command — other real failure modes (e.g. a device's max-user-count limit) haven't been triggered and observed, so they'll surface as a generic backend error rather than a more specific one.

Example

Called with serial="emulator-5554", name="Guest". A typical response:

{
  "status": "success",
  "message": "Created user 12 (Guest) on emulator-5554.",
  "data": {"serial": "emulator-5554", "user_id": 12, "name": "Guest"},
  "error": null
}

`dump_user` ¶

Dump detailed Android user info for a device: adb shell dumpsys user.

UserManagerService's diagnostic dump — every user's state, flags, restrictions, and running/locked status — far more detail than get_current_user's bare user ID. No userId argument: verified live that dumpsys user's optional userId has no effect at all (dumpsys user 0, dumpsys user 10, and dumpsys user 9999 all produced identical output) — it always dumps every user on the device, so there's nothing to pass. For detail on just one specific user, use user_info instead.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required

Returns:

Type	Description
`UserDump`	The raw dumpsys text output, plus the serial requested.

Error handling

Propagates the same way most tools do (unlike check_adb_available): if the adb binary itself can't be found or is unresponsive, or the serial doesn't match a connected device, that surfaces as an actual tool error.

Example

Called with serial="emulator-5554". A typical response:

{
  "status": "success",
  "message": "Dumped users on emulator-5554 (23000 chars).",
  "data": {
    "serial": "emulator-5554",
    "output": "Current user: 10\n\nUsers:\n  UserInfo{0:null:811} ..."
  },
  "error": null
}

`get_current_user` ¶

Get the current Android user on a device: adb shell am get-current-user.

Relevant on multi-user devices (work profiles, guest users, Android Automotive) where more than one user account can exist; most single-user devices just report user 0 (the primary/owner user).

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required

Returns:

Type	Description
`CurrentUser`	The device's serial and its current Android user ID.

Example

Called with serial="emulator-5554". A typical response:

{
  "status": "success",
  "message": "Current user on emulator-5554 is 0.",
  "data": {"serial": "emulator-5554", "user_id": 0},
  "error": null
}

`get_user_capabilities` ¶

Get device-wide Android multi-user capabilities: what the platform build supports, not info about any one particular user.

Aggregates several underlying commands (pm supports-multiple-users, pm get-max-users, pm get-max-running-users, cmd user is-headless-system-user-mode, cmd user is-visible-background-users-supported, cmd user is-visible-background-users-on-default-display-supported) into one flat result — callers never need to know which underlying command family answers a given question. For detail on a specific existing user, use user_info, dump_user, or list_users instead.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required

Returns:

Type Description

UserCapabilities

The device's serial plus its multi-user support flags/limits. The three pm-backed fields (supports_multiple_users, max_users, max_running_users) are always populated on any adb-reachable device — multi-user support has existed since Android 4.2. The three cmd user-backed fields (headless_system_user_mode, visible_background_users_supported, visible_background_users_on_default_display_supported) are newer subcommands not available on every Android version; each is independently None when unsupported on this particular device rather than failing the whole call.

Error handling

Propagates the same way most tools do (unlike check_adb_available): if the adb binary itself can't be found or is unresponsive, or the serial doesn't match a connected device, that surfaces as an actual tool error for any of the six underlying commands. A non-zero exit from one of the three newer cmd user subcommands that is NOT a device/serial problem (e.g. an unrecognized subcommand on an older Android build) is not treated as an error — it degrades just that one field to None and the call still returns the rest of the data successfully. Unparseable output from one of the three older, stable pm commands is treated as a genuine unexpected-shape failure rather than a version-gating issue, since those commands have been stable since Android 4.2.

Example

Called with serial="emulator-5554". A typical response:

{
  "status": "success",
  "message": "emulator-5554 supports multiple users (max 4, max running 4).",
  "data": {
    "serial": "emulator-5554",
    "supports_multiple_users": true,
    "max_users": 4,
    "max_running_users": 4,
    "headless_system_user_mode": false,
    "visible_background_users_supported": false,
    "visible_background_users_on_default_display_supported": false
  },
  "error": null
}

`get_user_state` ¶

Get a started user's lifecycle state: adb shell am get-started-user-state.

Reports where a started user is in the ActivityManager lifecycle (BOOTING → RUNNING_LOCKED → RUNNING_UNLOCKING → RUNNING_UNLOCKED → STOPPING → SHUTDOWN) — useful for waiting until a user reaches RUNNING_UNLOCKED before launching activities under it. A user that isn't currently started reports started=false, not an error.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`user_id`	`int`	The Android user id to inspect (see list_users).	required

Returns:

Type	Description
`UserRunState`	The serial, user_id, started (false when the user isn't running), and state — the raw lifecycle token when started, otherwise null.

Error handling

A negative user_id raises INVALID_ARGUMENT before anything runs. An unknown serial or unresponsive adb binary raises DEVICE_NOT_FOUND/ADB_UNAVAILABLE. Empty output raises BACKEND_ERROR; the "User is not started" message is a normal started=false result, not a failure.

Example

Called with serial="emulator-5554", user_id=10. A typical response:

{
  "status": "success",
  "message": "User 10 on emulator-5554: RUNNING_UNLOCKED.",
  "data": {
    "serial": "emulator-5554",
    "user_id": 10,
    "started": true,
    "state": "RUNNING_UNLOCKED"
  },
  "error": null
}

`is_user_stopped` ¶

Check whether an Android user is stopped: adb shell am is-user-stopped.

A quick boolean gate before user-scoped automation — if a user is stopped, start_user it first. This does not distinguish "stopped" from "no such user"; both report stopped=true.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`user_id`	`int`	The Android user id to check (see list_users).	required

Returns:

Type	Description
`UserStoppedState`	The serial, user_id, and stopped (true when the user is in the stopped state or does not exist).

Error handling

A negative user_id raises INVALID_ARGUMENT before anything runs. An unknown serial or unresponsive adb binary raises DEVICE_NOT_FOUND/ADB_UNAVAILABLE. Output that is neither "true" nor "false" raises BACKEND_ERROR.

Example

Called with serial="emulator-5554", user_id=10. A typical response:

{
  "status": "success",
  "message": "User 10 on emulator-5554 is not stopped.",
  "data": {
    "serial": "emulator-5554",
    "user_id": 10,
    "stopped": false
  },
  "error": null
}

`list_users` ¶

List every Android user on a device: adb shell cmd user list -v.

Structured, one entry per user (id, name, type, flags, and states like "running"/"current"/"visible") — the fastest way to see what user IDs actually exist before calling user_info or switch_user with one.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required

Returns:

Type	Description
`UserList`	The device's serial and every user currently defined on it.

Error handling

Propagates the same way most tools do (unlike check_adb_available): if the adb binary itself can't be found or is unresponsive, or the serial doesn't match a connected device, that surfaces as an actual tool error.

Example

Called with serial="emulator-5554". A typical response:

{
  "status": "success",
  "message": "2 users on emulator-5554.",
  "data": {
    "serial": "emulator-5554",
    "users": [
      {
        "user_id": 0,
        "name": "System User",
        "type": "system.HEADLESS",
        "flags": ["INITIALIZED", "PRIMARY", "SYSTEM"],
        "states": ["running"]
      },
      {
        "user_id": 10,
        "name": "Driver",
        "type": "full.SECONDARY",
        "flags": ["ADMIN", "FULL", "INITIALIZED"],
        "states": ["running", "current", "visible"]
      }
    ]
  },
  "error": null
}

`remove_user` ¶

Delete an Android user/profile from a device: adb shell pm remove-user ID.

Irreversibly deletes the user and all of its data — destructive, and denied by policy unless the server is explicitly configured with ADB_AUTOMATION_ALLOW_DESTRUCTIVE=1. Verified live that this also fails (not just for a nonexistent user) if user_id is the device's current/foreground user — switch_user away from it first.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`user_id`	`int`	The Android user ID to remove (see list_users).	required

Returns:

Type	Description
`RemoveUserResult`	The serial and user_id removed.

Error handling

Propagates the same way most tools do (unlike check_adb_available): if the adb binary itself can't be found or is unresponsive, or the serial doesn't match a connected device, that surfaces as an actual tool error. Verified live that removal failure — whether user_id doesn't exist or is currently active — always reads "Error: couldn't remove user id ", exit code 1; adb doesn't distinguish the two reasons in the message, so neither does this tool.

Example

Called with serial="emulator-5554", user_id=12. A typical response:

{
  "status": "success",
  "message": "Removed user 12 on emulator-5554.",
  "data": {"serial": "emulator-5554", "user_id": 12},
  "error": null
}

`start_user` ¶

Start a stopped Android user in the background: adb shell am start-user.

Brings a stopped secondary user (a work profile, guest, or Automotive passenger user) to the RUNNING state without switching the foreground to it — use switch_user for a foreground switch. Starting an already-running user is a harmless success. To bring one to the foreground on a specific screen, pass display_id (only meaningful on builds that support visible background users, typically automotive).

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`user_id`	`int`	The Android user id to start (see list_users).	required
`wait`	`bool`	When true, pass `-w` so the call blocks until the user is fully started and unlocked before returning.	`False`
`display_id`	`int \| None`	Make the user visible on this logical display so it can launch activities there (`--display`). Omit for a plain background start. Unsupported on most non-automotive builds.	`None`

Returns:

Type	Description
`StartUserResult`	The serial, user_id, the wait and display_id that were requested, started (always true when this returns without error), and the raw `am` message ("Success: user started").

Error handling

A negative user_id or display_id raises INVALID_ARGUMENT before anything runs. An unknown serial or unresponsive adb binary raises DEVICE_NOT_FOUND/ADB_UNAVAILABLE. am start-user exits 0 even when it fails, so a non-"Success" message ("Error: could not start user", or a build rejecting --display) raises BACKEND_ERROR carrying that message.

Example

Called with serial="emulator-5554", user_id=10, wait=true. A typical response:

{
  "status": "success",
  "message": "Started user 10 on emulator-5554.",
  "data": {
    "serial": "emulator-5554",
    "user_id": 10,
    "wait": true,
    "display_id": null,
    "started": true,
    "output": "Success: user started"
  },
  "error": null
}

`switch_user` ¶

Switch the active Android user on a device: adb shell am switch-user ID.

Changes what's actually running in the foreground on the device — not a read, and not safely re-invocable without consequence (it interrupts whatever the current user was doing). Use list_users first to find a valid target user ID.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`user_id`	`int`	The Android user ID to switch to (see list_users).	required

Returns:

Type	Description
`SwitchUserResult`	The serial and user_id switched to. Only returned on success — see Error handling below.

Error handling

Unlike connect_device, am switch-user's exit code was verified live to be reliable, so failure is a real tool error, not success:false data: an invalid user_id fails with "Error: Failed to switch to user ", exit code 1 — same as an unreachable serial or an unresponsive adb binary.

Example

Called with serial="emulator-5554", user_id=0. A typical response:

{
  "status": "success",
  "message": "Switched to user 0 on emulator-5554.",
  "data": {"serial": "emulator-5554", "user_id": 0},
  "error": null
}

`user_info` ¶

Get detailed info for one Android user: adb shell dumpsys user --user ID.

Unlike dump_user's plain dumpsys user (which always dumps every user and ignores any ID you give it), --user genuinely filters — verified live that --user 0 and --user 10 return different, single-user blocks. Use this when you want just one user's detail; use dump_user for every user at once.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`user_id`	`int`	The Android user ID to look up (see list_users to find valid IDs on this device).	required

Returns:

Type	Description
`UserInfo`	The requested user's raw dumpsys block, plus the serial and user_id requested.

Error handling

Propagates the same way most tools do (unlike check_adb_available): if the adb binary itself can't be found or is unresponsive, or the serial doesn't match a connected device, that surfaces as an actual tool error. A user_id that doesn't exist on an otherwise-reachable device is also an error (not success:false data) — verified live that adb reports this as ordinary stdout ("User not found") with exit code 0, so this tool detects that text and raises rather than returning it as if it were real user data.

Example

Called with serial="emulator-5554", user_id=10. A typical response:

{
  "status": "success",
  "message": "User 10 info on emulator-5554 (850 chars).",
  "data": {
    "serial": "emulator-5554",
    "user_id": 10,
    "output": "UserInfo{10:Driver:412} serialNo=10 isPrimary=false\n..."
  },
  "error": null
}

Users¶

create_user ¶

dump_user ¶

get_current_user ¶

get_user_capabilities ¶

get_user_state ¶

is_user_stopped ¶

list_users ¶

remove_user ¶

start_user ¶

switch_user ¶

user_info ¶

`create_user` ¶

`dump_user` ¶

`get_current_user` ¶

`get_user_capabilities` ¶

`get_user_state` ¶

`is_user_stopped` ¶

`list_users` ¶

`remove_user` ¶

`start_user` ¶

`switch_user` ¶

`user_info` ¶