Documentation

FlintCLI

A powerful command-line interface for managing remote devices, running tests, and streamlining your mobile development workflow.

Secure

Token-based authentication with 24-hour sessions

Flexible

Manage devices remotely from anywhere

Cross-Platform

Works on Windows, macOS, Linux, and VMs

Auto-Update

Built-in version detection and upgrades

Prerequisites

Ensure your system meets these requirements before installation.

Windows

Requirements for Windows systems

Python 3.10.0+
With pip and pipx installed
Node.js 16.20.2
Recommended version
ADB Platform Tools
Latest release

macOS

Requirements for macOS systems

Python 3.8.10+
Via Homebrew (recommended) with pip and pipx installed
Node.js 16.20.2
Recommended version
ADB Platform Tools
Latest release

Linux

Requirements for Linux systems

Python 3.8.10+
With pip and pipx
Node.js 16.20.2
Recommended version
ADB Platform Tools
Latest release
sudo access
For sandbox setup

No Admin Rights Required

FlintCLI can be installed with standard user permissions. Administrative access is only required on Linux for specific sandbox configurations.

Installation

Get FlintCLI up and running on your system in minutes.

Download FlintCLI

Get the latest stable release

This download is required for both new installations and upgrades.

Note: For optimal performance, use Google Chrome when downloading. Certain browsers (e.g., Safari) may automatically extract .zip files, potentially disrupting the setup process.

Choose Your Installation Path

Select the appropriate method based on your current FlintCLI version:

New Installation

Version ≤ 3.1.2

Perfect for first-time users or if you're upgrading from an older version. Includes platform-specific setup instructions.

Manual installation required

Platform-specific steps provided

Jump to installation guide

Automatic Upgrade

Version > 3.1.2

Seamless one-command upgrade for existing users. The CLI automatically detects and installs the latest version.

Fully automated process

Single command upgrade

Jump to upgrade guide

Installation Methods

Clean Installation Recommended

If you have a previous version of FlintCLI installed (version 3.1.2 or earlier), we recommend uninstalling it before proceeding with a new installation.

Why uninstall first?

Prevents version conflicts between old and new installations
Ensures cache files don't interfere with the new version
Provides a clean environment for optimal performance

To uninstall FlintCLI:

pipx uninstall flintcli

Before You Begin

The installation commands below require pipx to be installed on your system.

To verify pipx is installed:

pipx --version

If this command returns a version number, you're ready to proceed with the installation below.

If you don't have pipx installed yet, please follow theofficial pipx installation guidefor your platform before continuing.

New Installation

VERSION ≤ 3.1.2

Complete installation guide for first-time users or those upgrading from older versions. Select your platform below to get started.

Extract the package

powershell

Expand-Archive -Path .\flintcli.zip -DestinationPath .\flintcli
cd .\flintcli

Install using pipx

powershell

pipx install .\dist\flintcli-3.1.2-py3-none-any.whl

Automatic Upgrade

VERSION > 3.1.2

Seamless one-command upgrade process for existing FlintCLI users. No manual installation required.

Automatic Upgrade Process

For FlintCLI versions 3.1.2 and above, upgrading is automatic and seamless:

Step 1: Place the downloaded ZIP file

Place the newly downloaded FlintCLI ZIP file in your download directory.

Step 2: Run the version command

bash

flintcli version

Step 3: Follow the upgrade prompt

If a newer version is detected, you'll see:

Would you like to upgrade? (yes/no)

• Select yes to upgrade automatically
• Select no to keep your current version

Authentication

Secure your FlintCLI session with Nexus Access Tokens (NAT).

Authenticate Your Session

Run this command with your NAT token:

bash

flintcli auth --nat <your-token-here>

Session Expiry

NAT tokens are valid for 24 hours. Re-authenticate after expiration.

Generating a NAT Token

Navigate to https://gcp.flintlab.io

Go to Profile → Settings → Security

Click "Generate NAT"

Copy the token immediately—it's shown only once

Secure Token Storage

Never store tokens in plain text. Use a secrets manager:

macOS / Windows Credential Manager

OS Keychain

Linux

gnome-keyring, pass

Cloud

AWS Secrets Manager, Azure Key Vault, HashiCorp Vault

Core Commands

Essential commands for working with FlintCLI.

flintcli auth

Authenticate your session using a Nexus Access Token.

bash

flintcli auth --nat <your-token>

Required before using any other commands.

flintcli --help

Display all available commands and usage examples.

bash

flintcli --help

flintcli status

Check your current authentication status and view allocated devices. Optionally filter by type.

bash

flintcli status      # check the status of all allocated devices 
flintcli status r    # real devices only
flintcli status e    # emulators only

flintcli list

List available real devices and emulator recipes. Optionally filter by resource type.

bash

flintcli list        # list both real devices and emulators
flintcli list r      # real devices only
flintcli list e      # emulator recipes only

Use 'r' or 'real' for physical devices, 'e' or 'emulator' for emulators.

flintcli bind

Allocate a real device or emulator for exclusive use. Requires a resource type, device ID, and allocation duration.

bash

flintcli bind r -i <device_id> --time 60
flintcli bind e -i <recipe_id> --time 30

Duration must be between 3 and 720 minutes. Must bind before streaming.

flintcli stream

Open a live stream for a bound real device or emulator instance.

bash

flintcli stream r -i <device_id>
flintcli stream e -i <instance_id>

Use the same ID from your bind command. Must bind before streaming.

flintcli deallocate

Release a real device or emulator back to the available pool.

bash

flintcli deallocate r -i <device_id>
flintcli deallocate e -i <instance_id>

Always deallocate when finished to free resources for other users.

flintcli logout

Terminate your session and clear stored authentication.

bash

flintcli logout

flintcli version

Check the current version. Automatically detects newer .whl files in your Downloads folder. Supports manual upgrade or downgrade.

bash

flintcli version
flintcli version --upgrade ./path/to/flintcli-x.x.x-py3-none-any.whl
flintcli version --downgrade ./path/to/flintcli-x.x.x-py3-none-any.whl

Example Workflows

Common patterns for working with FlintCLI.

Complete Session Workflow (Real Device)

Full lifecycle from authentication to cleanup:

bash

# Authenticate
flintcli auth --nat <your-token>

# Verify session
flintcli status

# Find available real devices
flintcli list r

# Bind to device for 60 minutes
flintcli bind r -i "a1b2c3d4-5678-90ef" --time 60

# Stream from device
flintcli stream r -i "a1b2c3d4-5678-90ef"

# Release device
flintcli deallocate r -i "a1b2c3d4-5678-90ef"

# End session
flintcli logout

Quick Device Test

Rapid testing workflow:

bash

flintcli auth --nat <token>
flintcli list r
flintcli bind r -i "<device_id>" --time 30
flintcli stream r -i "<device_id>"
flintcli deallocate r -i "<device_id>"

Emulator Session Workflow

Using an emulator recipe end-to-end:

bash

# Authenticate
flintcli auth --nat <your-token>

# List available emulator recipes
flintcli list e

# Allocate an emulator from a recipe for 30 minutes
flintcli bind e -i "<recipe_id>" --time 30

# Stream the emulator instance
flintcli stream e -i "<instance_id>"

# Release the emulator
flintcli deallocate e -i "<instance_id>"

# End session
flintcli logout

Multi-Device Testing

Sequential real device testing:

bash

# Authenticate once
flintcli auth --nat <token>

# List devices
flintcli list r

# First device
flintcli bind r -i "device-id-1" --time 60
flintcli stream r -i "device-id-1"
flintcli deallocate r -i "device-id-1"

# Second device
flintcli bind r -i "device-id-2" --time 60
flintcli stream r -i "device-id-2"
flintcli deallocate r -i "device-id-2"

# Cleanup
flintcli logout

Frequently Asked Questions

Quick answers to common questions.

How do I check my FlintCLI version?

Run the version command:

bash

flintcli version

This also automatically checks your Downloads folder for newer .whl files and offers to upgrade if a newer version is found.

What if I lose my NAT token?

Log into the Flint dashboard, navigate to Security settings, revoke the existing token, and generate a new one. Store it securely in a password manager immediately.

Can I have multiple NAT tokens active?

No. Only one NAT token can be active per account at any time. You must revoke the existing token before generating a new one.

How do I reinstall a specific version?

Use the --force flag with pipx:

bash

pipx install --force ./dist/flintcli-3.1.2-py3-none-any.whl

To downgrade to a specific version, use the built-in downgrade option:

bash

flintcli version --downgrade ./path/to/flintcli-x.x.x-py3-none-any.whl

Commands fail with '404 - Not Found' after authentication. How do I fix this?

If you successfully authenticate but commands like flintcli list fail with:

bash

Error: 404 - {"detail":"Not Found"}

This indicates a configuration mismatch. Reinstall FlintCLI using the --force flag:

bash

pipx install dist/flintcli-3.1.2-py3-none-any.whl --force

This forces a clean reinstallation and resolves endpoint configuration issues that can occur after authentication.

Why must I bind before streaming?

Binding allocates the device exclusively to you, preventing conflicts with other users. Attempting to stream without binding will result in an error.

What is the --time flag and what values are allowed?

The --time (or -t) flag specifies the allocation duration in minutes when binding a device or emulator. It is required.

Minimum: 3 minutes
Maximum: 720 minutes (12 hours)

bash

flintcli bind r -i <device_id> --time 60

What is the difference between 'r' and 'e' resource types?

Use 'r' (or 'real') for physical Android devices, and 'e' (or 'emulator') for cloud-based emulator instances created from a recipe. Both support the same bind, stream, and deallocate commands.

FlintCLI Documentation · Last Updated April 2026