Start using Kobiton Command Line Interface

Learn how to use Kobiton Command Line Interface to control and operate your private device lab.

Before you begin

  • Set up Kobiton CLI.

  • Ensure private devices are available in the Kobiton Portal. Public devices are not supported.

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

Note down the UDID of the device to use.

Create a session on the device:

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

Note down 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.

  • Mixed sessions between manual testing and CLI testing are not supported.

  • 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 run into an error while running the CLI commands, try the below steps:

  • Double-check the command syntax and usage. It is possible to 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 below 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>