Start using Kobiton Command Line Interface

Control and operate your devices using the Kobiton Command Line Interface.

Before you begin

  • Set up Kobiton CLI.

  • Ensure devices are available in the Kobiton Portal. CLI sessions are supported on devices from the Private & Local Devices and Public Cloud Devices tabs.

Create a CLI session

Open a terminal program on the computer.

Find a private device that is available (not in use or retained by other users):

kobiton device list --booked false --reserved false --private

Record the UDID of the device to use.

To run a session on a public cloud device, filter the device list with --cloud instead of --private.

Create a session on the device:

Example
kobiton session create -u <UDID>
Output
Session <SESSION_ID> created for device <UDID>.
Session token <SESSION_TOKEN>

Record the <SESSION_ID> for later use.

Export the <SESSION_TOKEN> to the KOBITON_SESSION_TOKEN environment variable for later use.

  • macOS and Linux

  • Windows - PowerShell

  • Windows - Command Prompt

export KOBITON_SESSION_TOKEN=<SESSION_TOKEN>
$env:KOBITON_SESSION_TOKEN="<SESSION_TOKEN>"
set KOBITON_SESSION_TOKEN=<SESSION_TOKEN>

Use session context consistently

After creating a CLI session, you receive both a <SESSION_ID> and a <SESSION_TOKEN>.

The session ID identifies the session record. The session token authorizes and scopes CLI commands to that session.

Many commands that operate on an active CLI session require session context. Provide session context using one of the following methods:

  • Pass the session token explicitly: --session-token <SESSION_TOKEN> (or -a <SESSION_TOKEN>)

  • Set the KOBITON_SESSION_TOKEN environment variable

The session token ensures each command is applied to the intended active session.

If you are running multiple sessions concurrently, always provide the session context explicitly. This prevents commands from being applied to the wrong session when more than one session is active.

For interactive use, set KOBITON_SESSION_TOKEN once per terminal session.

For scripts or isolated commands, pass --session-token explicitly with each command.

Known limitations

  • Session Explorer is not available when using Kobiton CLI.

  • Session video and logs are not available in Session Overview.

  • Kobiton CLI does not support mixing manual and CLI testing sessions.

  • By default, CLI sessions time out after 10 minutes. You can configure the timeout up to 2 hours using the kobiton session ping command.

Troubleshooting

If you encounter an error while running the CLI commands, try the following steps:

  • Double-check the command syntax and usage. You can bring up the manual for each command by adding -h or --help. Examples:

    • kobiton --help or kobiton -h

    • kobiton device --help or kobiton session -h

    • kobiton device list -h or kobiton session create -h

  • If the error is not resolved, look up the error messages and their resolutions in the following table:

    Message Solution

    environment variable not found

    Export the environment variables for authentication.

    The credential you entered was not authorized. Please double-check and try again.

    Double-check the Kobiton account’s username and API Key.

    error sending request for url (/https://api.kobiton.com/v2/sessions): client error (Connect): dns error: failed to lookup address information: nodename nor servname provided, or not known

    504 Gateway Time-out

    Ensure the local machine can access the Cloud or Standalone Kobiton Portal.

    This command requires a session ID (-s).

    Create a CLI session to get a <SESSION_ID>, then add -s <SESSION_ID> to the command.

    This command requires a --session-token or KOBITON_SESSION_TOKEN env. See session create.

    Create a CLI session to get a <SESSION_TOKEN>, then add -a <SESSION_TOKEN> to the command or export the KOBITON_SESSION_TOKEN environment variable.

    Session not found or already ended

    The CLI session is not found or already completed. Create a new CLI session before running the command.

    Device --udid is required.

    Provide the UDID of the device using -u <UDID>.