Platform Command Line Interface

HeadSpin CLI

The HeadSpin CLI (hs) is the official command line interface for the HeadSpin platform API. It can be installed from the Settings and Downloads page.

Continuous integration and other automated workflows

The HeadSpin CLI can be used in continuous integration or other automated workflows. The usage of the CLI is the same in both manual and automated scenarios. For example, the same <code class="dcode">hs connect</code> command retrieved from the remote-control view of a device may also be used in automated workflows. However, automated workflows may require programmatic installation of the CLI, which is covered below.

NOTE: Please make sure to update your workflows every now and then to keep your CLI version up to date.

Programmatic installation on macOS

The HeadSpin CLI for macOS is distributed in a signed disk image file (.dmg) which requires a few additional steps to install. Below is a set of commands you may use as part of your workflow.

curl https://api-dev.headspin.io/v0/releases/dl/cli/202307.95.0/macos/HeadSpin-CLI-v202307.95.0.dmg -o HeadSpin-CLI-v202307.95.0.dmg
hdiutil attach HeadSpin-CLI-v202307.95.0.dmg
sudo installer -pkg "/Volumes/HeadSpin CLI/HeadSpin-CLI-v202307.95.0.pkg" -target /
hdiutil detach "/Volumes/HeadSpin CLI"

You should now have the <code class="dcode">hs</code> command available under <code class="dcode">/usr/local/bin</code>. Please ensure that <code class="dcode">/usr/local/bin</code> is included in your <code class="dcode">PATH</code> when using the command.

Programmatic installation on Linux

The installation method on Linux may vary depending on the distribution. Below is an example that uses<code class="dcode">curl</code> and <code class="dcode">sudo</code>.

curl https://api-dev.headspin.io/v0/releases/dl/cli/202307.95.0/linux/HeadSpin-CLI-v202307.95.0-x64.tar.gz -o HeadSpin-CLI-v202307.95.0-x64.tar.gz
tar -xzvf HeadSpin-CLI-v202307.95.0-x64.tar.gz hs
sudo mv hs /usr/local/bin

You should now have the <code class="dcode">hs</code> command available under <code class="dcode">/usr/local/bin</code>. Please ensure that <code class="dcode">/usr/local/bin</code> is included in your <code class="dcode">PATH</code> when using the command.

NOTE: You may place the CLI elsewhere if you prefer; there is no strict requirement for its location.

Programmatic installation on Windows

There is a myriad of ways to run command line software on Windows. Some common methods are covered below.

PowerShell

Sample installation process is provided below.

# Optional: disable progress reporting to significantly increase download speed
$ProgressPreference = 'SilentlyContinue'

# Download the HeadSpin CLI
Invoke-RestMethod -Uri "https://api-dev.headspin.io/v0/releases/dl/cli/202307.95.0/windows/HeadSpin-CLI-v202307.95.0-x64.zip" -OutFile "HeadSpin-CLI-v202307.95.0-x64.zip"

# Extract the downloaded ZIP archive
Expand-Archive -Path "HeadSpin-CLI-v202307.95.0-x64.zip" -DestinationPath "C:\HeadSpin\CLI"

# Add the installation directory to the search path for the current shell
$env:Path += ";C:\HeadSpin\CLI"

You should now be able to call <code class="dcode">hs</code>(or <code class="dcode">hs.exe</code> if you prefer) from any directory within the current shell's context.

NOTE: You may place the CLI elsewhere if you prefer; there is no strict requirement for its location.

Windows Subsystem for Linux

Please use the Linux installation instructions.

cmd.exe

Installation using <code class="dcode">cmd.exe</code> is only advisable on Windows 10 or greater, as third party tools may otherwise be required to facilitate the download and installation. Windows 10 and later include <code class="dcode">curl</code> and <code class="dcode">tar</code> by default which makes the process much easier.

curl https://api-dev.headspin.io/v0/releases/dl/cli/202307.95.0/windows/HeadSpin-CLI-v202307.95.0-x64.zip -o HeadSpin-CLI-v202307.95.0-x64.zip
tar -xvf HeadSpin-CLI-v202307.95.0-x64.zip hs.exe

You should now be able to call <code class="dcode">hs</code> (or <code class="dcode">hs.exe</code> if you prefer) in the current working directory. Additional steps are required if you wish to make the CLI available globally.

Windows, iTunes & iOS Testing

A note for users testing iOS on Windows machines: In order to properly support iOS device testing on a Windows machine, you will need to install iTunes for Windows. However, iTunes MUST NOT be installed from the Microsoft Store; this version of the program will not have the necessary support components. Please only install iTunes from Apple’s support page using one of the links under “If you can’t access the Microsoft Store”. By default, Apple will offer the current version of iTunes for download; we recommend installing this, rather than looking for a legacy version of iTunes. (If you are using an older version of iTunes, we also recommend updating to the most up-to-date version compatible with your Windows OS.) After this is done, iOS devices can be attached to Windows. They will not be visible in iTunes itself, but they will be connected as network devices and can be seen following the proper steps with the HeadSpin CLI tool.

Note Regarding iOS 17

Currently HeadSpin only has limited support for the use of our proprietary CLI with devices running iOS 17. Particular commands, including <code class="dcode">hs connect</code> and <code class="dcode">hs provide</code> are not yet enabled for iOS 17. When this functionality is enabled, this section will be updated. For more information on what is and is not supported on iOS 17 devices, please see our iOS 17 support documentation.

‍

Usage

A snapshot of the available functionality is included below. You may run <code class="dcode">hs help</code> at any time to display the same for the version you have installed.

The HeadSpin CLI is often used with remote debugging which is documented separately.

--