Kobiton Command Line Interface commands Commands that operate on an active CLI session require session context. The CLI determines the session context using one of the following methods: Use the session token stored in ~/.token/.session (default). This file is automatically created or updated when you run kobiton session create, and commands will use the token for the most recently created session. Pass the session token with the command: --session-token <SESSION_TOKEN> (or -a <SESSION_TOKEN>) Set the KOBITON_SESSION_TOKEN environment variable The <SESSION_TOKEN> value is returned when you create a CLI session. For details, see Start using Kobiton CLI. Relying on the default ~/.token/.session file is convenient for single-user workflows but is not recommended for environments with concurrent or parallel executions, because it is overwritten each time a new CLI session is created. Synopsis kobiton [OPTIONS] <COMMAND> [SUBCOMMAND] [ARGS]... kobiton is a command-line client for the Kobiton mobile device cloud. It lets you create and manage device sessions, drive devices over WebDriver, transfer files, install and run applications, inspect device state, and launch built-in test runs. Most commands operate against a single device session. A device is identified by its UDID (-u, --udid) and, once a session exists, by its session ID (-s, --session-id) and session token (-a, --session-token). A typical workflow is: Find a device — kobiton device list Open a session on it — kobiton session create -u <UDID> Operate on the device — kobiton app install, kobiton file push, kobiton webdriver post, and so on Close the session — kobiton session end -s <SESSION_ID> Global options These options are accepted by every command and subcommand. Option Argument Description -a, --session-token <SESSION_TOKEN> Authorization token returned by session create. -u, --udid <UDID> UDID of the device to use. -p, --portal <PORTAL> Portal base address (Kobiton API/portal endpoint). -s, --session-id <SESSION_ID> Kobiton session ID returned by session create. -l, --log-level <LOG_LEVEL> Log verbosity: error, warn, info, debug, trace. Default: info. -h, --help Print help for the command or subcommand. -V, --version Print version (top-level command only). app Manage apps: run, install, uninstall, upload, and inspect application versions in the Kobiton App Repo. app run Run an application on the device. Syntax kobiton app run [OPTIONS] <APP_IDENTIFIER> [ARGS]... Arguments Argument Description <APP_IDENTIFIER> Bundle ID or package name to run. [ARGS]… Arguments to pass to the app (before or after --). Options Option Argument Description -e, --env <KEY> <VALUE> Environment variable pair. Repeatable: --env KEY VALUE. Plus all global options. Requires: -a <SESSION_TOKEN> or KOBITON_SESSION_TOKEN environment variable <APP_IDENTIFIER> Example kobiton app run com.example.app Output PID 32124 app kill Terminate an application, or send it a signal. Syntax kobiton app kill [OPTIONS] <IDENTITY> Arguments Argument Description <IDENTITY> PID, package name, or bundle ID of the process to signal. Options Option Argument Description -n, --signal <SIGNAL> Signal to send. Default: SIGTERM. Plus all global options. Requires: -a <SESSION_TOKEN> or KOBITON_SESSION_TOKEN environment variable <IDENTITY> Example kobiton app kill com.example.app app install Install an application. Requires either an app identifier (--name), or both --app-id and --app-version-id. Syntax kobiton app install [OPTIONS] Options Option Argument Description -n, --name <NAME> The app to install. Can be an app name, package name, bundle ID, app ID, or app version ID. --app-id <APP_ID> The Kobiton application ID. --app-version-id <APP_VERSION_ID> The Kobiton application version ID. --search-pages <SEARCH_PAGES> Max pages to scan when resolving an app version via deviceConnect install. Default: 10. Plus all global options. Requires: -s <SESSION_ID>, and -a <SESSION_TOKEN> or the KOBITON_SESSION_TOKEN environment variable One of: -n <NAME>, or both --app-id <APP_ID> and --app-version-id <APP_VERSION_ID> Example # Install on session 123 the latest version of a specific app ID kobiton app install -s 123 -n 651911 # Install on session 123 the app with a specific package name or bundle ID kobiton app install -s 123 -n com.example.app # Install on session 123 the app with specific app ID and app version ID kobiton app install -s 123 --app-id 651911 --app-version-id 739431 Output Install app successfully app uninstall Uninstall an application. Syntax kobiton app uninstall [OPTIONS] <APP_IDENTIFIER> Arguments Argument Description <APP_IDENTIFIER> Bundle ID or package name to uninstall. Accepts all global options. Requires: -u <UDID> <APP_IDENTIFIER> Example kobiton app uninstall -u 3e4e7fe7 com.example.app Output The application is uninstalled successfully app upload Upload an application to the Kobiton App Repo. Syntax kobiton app upload [OPTIONS] <PATH> [APP_ID] Arguments Argument Description <PATH> Local path to an app package that belongs to a supported filetype and size. [APP_ID] Kobiton application ID, if uploading a new version of an existing app. Accepts all global options. Requires: <PATH> Example kobiton app upload ./sample.apk Output Application uploaded. Parsing status OK. App ID: 651911 Version ID: 739431 app find Find an app in the Kobiton App Repo using a keyword. Syntax kobiton app find [OPTIONS] <KEYWORD> Arguments Argument Description <KEYWORD> Keyword to find the app. Can be text contained in the app name, text contained in the package name or bundle ID, an app ID (for example 651911), or an app version ID prefixed with v (for example v739431). Put <KEYWORD> between double quotes for spaces or special characters. Accepts all global options. Requires: <KEYWORD> Example kobiton app find "example app" Output Name: Example App Version: 4.1.1 App ID: 651911 Version ID: 739431 app get-version Get information about a specific application version. Syntax kobiton app get-version [OPTIONS] --app-id <APP_ID> --app-version-id <APP_VERSION_ID> Options Option Argument Description --app-id <APP_ID> The Kobiton application ID. --app-version-id <APP_VERSION_ID> The Kobiton application version ID. Plus all global options. Requires: --app-id <APP_ID> --app-version-id <APP_VERSION_ID> Example kobiton app get-version --app-id 651911 --app-version-id 739431 app sign Get the signed download URL for a specific application version on a device. Syntax kobiton app sign [OPTIONS] --app-id <APP_ID> --app-version-id <APP_VERSION_ID> Options Option Argument Description --app-id <APP_ID> The Kobiton application ID. --app-version-id <APP_VERSION_ID> The Kobiton application version ID. Plus all global options. Requires: --app-id <APP_ID> --app-version-id <APP_VERSION_ID> Example kobiton app sign --app-id 651911 --app-version-id 739431 app list-versions List the versions of an application. Syntax kobiton app list-versions [OPTIONS] --app-id <APP_ID> Options Option Argument Description --app-id <APP_ID> The Kobiton application ID. --page <PAGE> Page to retrieve. --size <SIZE> Max number of items to return. Plus all global options. Requires: --app-id <APP_ID> Example kobiton app list-versions --app-id 651911 file Manage files on the device: list, push, and pull. Path syntax: Android: absolute device paths, for example /data/local/tmp. iOS: the base filesystem is accessible via normal paths such as Downloads or DCIM/100APPLE. To access files under an app container, use @<bundle_id>:<container_name>/, for example @com.sample.app:Documents/. For how iOS app containers and file sharing work — including the UIFileSharingEnabled requirement and per-app examples — see Access app files on iOS devices. file list List files at a path on the device. Syntax kobiton file list [OPTIONS] [PATH] Arguments Argument Description [PATH] Path to list. If empty, the home location is used. Accepts all global options. Requires: -a <SESSION_TOKEN> or KOBITON_SESSION_TOKEN environment variable Example (Android) kobiton file list /data/local/tmp Example (iOS) kobiton file list @com.sample.app:Documents/ Output sampleFolder sampleFile1.tmp file push Push a local file to a remote path on the device. Syntax kobiton file push [OPTIONS] <LOCAL_PATH> <REMOTE_PATH> Arguments Argument Description <LOCAL_PATH> Local source path. <REMOTE_PATH> Destination path on the device. If empty, the home location is used. Accepts all global options. Requires: -a <SESSION_TOKEN> or KOBITON_SESSION_TOKEN environment variable <LOCAL_PATH> Example (Android) kobiton file push foo.dat /data/local/tmp/foo.dat Example (iOS) kobiton file push foo.dat @com.company.app:Documents/foo.dat Output Pushed 505031 bytes to /data/local/tmp/foo.dat file pull Pull a file or directory from the device to a local path. Syntax kobiton file pull [OPTIONS] <REMOTE_PATH> [LOCAL_PATH] Arguments Argument Description <REMOTE_PATH> Source path on the device. [LOCAL_PATH] Local destination path. If empty, the current location is used. Options Option Argument Description -r, --recursive Recursively pull a directory and all its contents. -j, --concurrency <CONCURRENCY> Maximum simultaneous transfers (recursive pulls only). Default: 5. Plus all global options. Requires: -a <SESSION_TOKEN> or KOBITON_SESSION_TOKEN environment variable <REMOTE_PATH> Example (Android) kobiton file pull /data/local/tmp/foo.dat foo.dat Example (Android, recursive) kobiton file pull -r /data/local/tmp/mydir Example (iOS) kobiton file pull @com.company.app:Documents/foo.dat Output Pulled 505031 bytes to foo.dat device Device operations: discovery, shell access, port forwarding, logs, and screenshots. device list List devices, with optional filters. Syntax kobiton device list [OPTIONS] Options Option Argument Description --udid <UDID> Filter devices with this UDID. --model <MODEL> Filter devices by model. --name <NAME> Filter devices by name. Supports wildcards, for example iPad* or Note. --platform <PLATFORM> Filter devices by platform. --version <VERSION> Filter devices by platform version. --reserved <true|false> Filter by whether the device is reserved (retained). --booked <true|false> Filter by whether the device is being used. --online <true|false> Filter by whether the device is online. Default: true. --team <TEAM> Filter devices assigned to the team with this ID. --private Filter for private devices. --cloud Filter for cloud devices. --network <true|false> Filter for device network reachability. Plus all global options. device list uses --udid as a filter flag and does not accept the short -u alias here. Highly recommended to use --private --booked false --reserved false to filter to private devices that are free to use. Example kobiton device list --private --booked false --reserved false Output Display Name, UDID, Platform, List, Status, Host iPhone 12, 79de3c497b9f1****19040aeb44, iOS 18.1, Private, ACTIVATED, 192.168.50.86 device adb-shell Run adb shell commands on an Android device. Syntax kobiton device adb-shell [OPTIONS] [ARGS]... Arguments Argument Description [ARGS]… Arguments to pass (before or after --). If not provided, launches an interactive adb shell. Accepts all global options. Requires: -a <SESSION_TOKEN> or KOBITON_SESSION_TOKEN environment variable Example # Run a simple adb shell command kobiton device adb-shell ls # Run an adb shell command with extra arguments (pass after --) kobiton device adb-shell -- ls --color=auto # Quote characters that the local shell would interpret, such as a pipe kobiton device adb-shell "dumpsys window displays | grep -E 'mCurrentFocus|mFocusedApp'" Output mCurrentFocus=Window{272f9b1 u0 com.example.app/MainActivity} mFocusedApp=ActivityRecord{3d12396 u0 com.example.app/.MainActivity t2823} device forward Forward a local port to a service on the device. Address format is tcp:<port>. Transient network connection failures are retried for up to 5 minutes. Syntax kobiton device forward [OPTIONS] <LOCAL_ADDRESS> <REMOTE_ADDRESS> Arguments Argument Description <LOCAL_ADDRESS> Address on localhost, for example tcp:8080. <REMOTE_ADDRESS> Address on the device, for example tcp:80. Options Option Argument Description --mode <MODE> How accepted connections map onto gRPC channels. mux (default): multiplexed over a single shared channel. demux: each connection gets its own dedicated channel (1:1, not shared). Plus all global options. Requires: -a <SESSION_TOKEN> or KOBITON_SESSION_TOKEN environment variable <LOCAL_ADDRESS> and <REMOTE_ADDRESS> in tcp:<port> format The port forward remains active until the CLI session or the forward process ends. The local port stays occupied while the forward process is running — stop the forward process to release it. Example kobiton device forward tcp:8080 tcp:80 Output Listening on 127.0.0.1:8080. device restart Restart the device. Syntax kobiton device restart [OPTIONS] Accepts all global options. Requires: -u <UDID> Example kobiton device restart -u 3e4e7fe7 device ps List processes running on the device. Syntax kobiton device ps [OPTIONS] Accepts all global options. Requires: -a <SESSION_TOKEN> or KOBITON_SESSION_TOKEN environment variable Example kobiton device ps Output PID NAME 1 init 2 [kthreadd] 3 [rcu_gp] 5 [kworker/0:0H] device log Stream logs from the device. Use Control + C to stop the log stream. Syntax kobiton device log [OPTIONS] Accepts all global options. Requires: -a <SESSION_TOKEN> or KOBITON_SESSION_TOKEN environment variable Example kobiton device log device screen Retrieve the device screen in jpg format. Pipe the output to a .jpg file to save the screenshot. Syntax kobiton device screen [OPTIONS] Options Option Argument Description -q, --quality <QUALITY> JPEG quality as a percentage, 0–100. Plus all global options. Requires: -a <SESSION_TOKEN> or KOBITON_SESSION_TOKEN environment variable Example kobiton device screen -q 80 > screen.jpg reservation Reservation operations: list and terminate device reservations. reservation list List device reservations (retainments). Syntax kobiton reservation list [OPTIONS] Options Option Argument Description --page <PAGE> Page to retrieve. Default: 1. --size <SIZE> Max number of items to return. Default: 20. Plus all global options. Example kobiton reservation list Output ID, Status, Creator, UDIDs 7, RESERVED, johndoe@example.com, 00008030-00057190****802E Page 1 (20 items), 1 total reservation terminate Terminate a reservation by its ID. Only users with the soft_book.terminate_other_soft_book permission can terminate reservations that are not their own. Syntax kobiton reservation terminate [OPTIONS] <RESERVATION_ID> Arguments Argument Description <RESERVATION_ID> Reservation ID to terminate. Use kobiton reservation list to retrieve the ID. Accepts all global options. Requires: <RESERVATION_ID> Example kobiton reservation terminate 7 Output OK session Session creation, termination, and keepalive. session create Create a session. Syntax kobiton session create [OPTIONS] Options Option Argument Description -t, --timeout <TIMEOUT> Inactivity timeout for this session, in minutes. Default/minimum is 10, maximum is 120. Can be refreshed with session ping. Plus all global options. Requires: -u <UDID> Example kobiton session create -u 3e4e7fe7 Output Session 8155111 created for device 3e4e7fe7. Session token eyJhbGciOiJ... session end Complete a session, setting its status to ended. Syntax kobiton session end [OPTIONS] Accepts all global options. Requires: -s <SESSION_ID> Example kobiton session end -s 8155111 Output Session 8155111 ended. session terminate Complete a non-responsive session, setting its status to terminated. Syntax kobiton session terminate [OPTIONS] Accepts all global options. Requires: -s <SESSION_ID> Example kobiton session terminate -s 8155111 Output Session 8155111 terminated. session delete Delete a completed session from history (removes it from the Session list). Syntax kobiton session delete [OPTIONS] Accepts all global options. Requires: -s <SESSION_ID> Example kobiton session delete -s 8155111 Output OK session ping Reset the timeout period for this session (keepalive). Syntax kobiton session ping [OPTIONS] Accepts all global options. Requires: both -s <SESSION_ID> and KOBITON_SESSION_TOKEN environment variable (or -a <SESSION_TOKEN>) Example export KOBITON_SESSION_TOKEN=<SESSION_TOKEN> # Skip if already imported kobiton session ping -s 8155111 Output Session 8155111 pinged. session list-active Display a list of all active sessions. Syntax kobiton session list-active [OPTIONS] Accepts all global options. Example kobiton session list-active Output Session 8155111, device 3e4e7fe7, status RUNNING, created 2025-10-09T03:38:03Z, ended active session show Show information about a session. Syntax kobiton session show [OPTIONS] Accepts all global options. Requires: -s <SESSION_ID> Example kobiton session show -s 8155111 Output Session 8155111: Session created at 10/09/2025 04:13 AM Created: 2025-10-09T03:13:55.698Z Ended: 2025-10-09T03:31:26.973Z Device 3e4e7fe7: Android 11 Status: COMPLETE test Test runs and management. test run Run a native framework automation session (XCUITest, UIAutomator, or Espresso). GameDriver is not supported. Syntax kobiton test run [OPTIONS] --app <APP> --runner <TEST_RUNNER> <FRAMEWORK> Arguments Argument Description <FRAMEWORK> Framework to test with. Must be either uiautomator2 or xcuitest. Options Option Argument Description --app <APP> Application to test. A URL or a kobiton-store ID. (required) --runner <TEST_RUNNER> Test runner to use. A URL or a kobiton-store ID. (required) --session-name <SESSION_NAME> Name of this session. --description <SESSION_DESCRIPTION> Longer description of this session. -d, --device-name <DEVICE_NAME> Friendly device name to use. This or UDID is required. Supports wildcards. -v, --platform-version <PLATFORM_VERSION> Platform version to match. Supports wildcards. -g, --device-group <DEVICE_GROUP> Group of devices to match within. --plan <TEST_PLAN> Test plan to use. A URL or a path to a file. Required for XCUITest, unless tests are specified. -t, --test <TESTS> Tests to execute. Repeatable. Required for XCUITest, unless a test plan is specified. -o, --session-timeout <SESSION_TIMEOUT> Terminate the session if not completed before this timeout, in seconds. Default: 1800 (30 minutes). --reset <RESET> Reset options. Valid types: full, data, none. --follow Follow a session until it is completed, then print a plain-text test report. --stream Stream test logs as they are emitted. Session test reports are not available with this option. --run-command <RUN_COMMAND> Run command for TurboTest execution. -e, --env <KEY> <VALUE> Environment variable pair. Repeatable: --env KEY VALUE. Plus all global options. Requires: --app <APP> and --runner <TEST_RUNNER>, each a Kobiton App Repo ID (kobiton-store:<APP_ID> or kobiton-store:v<APP_VERSION_ID>) or a direct URL. Local path is not supported. Either -u <UDID> or -d <DEVICE_NAME> for any framework. Either -t <TESTS> or --plan <TEST_PLAN> for XCUITest. <TEST_PLAN> must be a direct URL. <FRAMEWORK> Example (UIAutomator or Espresso) kobiton test run --app kobiton-store:662537 --runner kobiton-store:v762538 -u 3e4e7fe7 uiautomator Example (XCUITest) kobiton test run --app kobiton-store:662538 --runner kobiton-store:v762548 --plan https://example.com/test-plans/sample.xctestplan -u 00008120-000E44D***28C01E --follow xcuitest Output #UIAutomator/Espresso UIAUTOMATOR Session 8155157 started. #XCUITest XCUITEST Session 8155161 started. #XCUITest with --follow Session 8155172: XCUITEST test session Created: 2025-10-09T04:25:41.896Z Device 00008120-000E44D***28C01E: iOS 16.1 Status: START Session 8155172: XCUITEST test session Created: 2025-10-09T04:25:43.769Z Ended: 2025-10-09T04:26:26.261Z Device 00008120-000E44D***28C01E: iOS 16.1 Status: COMPLETE Test Suite: Tests: 2 Failures: 0 Errors: 0 Skipped: 0 Duration: 1.000 Start Time: 2025-10-09T11:24:58 End Time: 2025-10-09T11:24:59 XCUITestSampleUITests#testABC [0.402] PASSED out: Start Test at 2025-10-09 11:24:58.275 out: Set Up out: Tear Down XCUITestSampleUITests#testXYZ [0.324] PASSED out: Start Test at 2025-10-09 11:24:58.684 out: Set Up out: Tear Down webdriver Send generic WebDriver commands to the session. The session path prefix (/session/<id>) is supplied automatically — provide only the path suffix. webdriver post Send a generic WebDriver POST command. Syntax kobiton webdriver post [OPTIONS] <PATH> [ARGS] Arguments Argument Description <PATH> Path suffix to POST, excluding /session/id. For example, element for find element. [ARGS] Request body as a single JSON string. Accepts all global options. Requires: -a <SESSION_TOKEN> or KOBITON_SESSION_TOKEN environment variable <PATH> Example kobiton webdriver post element '{"using":"id","value":"login"}' webdriver get Send a generic WebDriver GET command. Syntax kobiton webdriver get [OPTIONS] <PATH> Arguments Argument Description <PATH> Path suffix to GET, excluding /session/id. For example, source for page source. Accepts all global options. Requires: -a <SESSION_TOKEN> or KOBITON_SESSION_TOKEN environment variable <PATH> Example kobiton webdriver get source