Surveyor

Install the Surveyor CLI

The Surveyor CLI is the spice command. It surveys software on your own machines and uploads the encrypted results to your Topographer project. The installer puts a small wrapper script on your machine, and the wrapper runs the CLI in Docker.

This page covers the free, open source Surveyor CLI. The other editions are described on Editions and licenses.

Before you start

• Docker, installed and running. Get Docker. If you cannot use Docker, see Run without Docker.
• Linux containers. The CLI runs in a Linux container. On Windows, Docker Desktop runs Linux containers by default; if it was switched to Windows containers, switch it back (right-click the Docker icon, Switch to Linux containers). Windows Server’s Docker Engine runs only Windows containers.
• A Spice Pass, to upload surveys to your project. Generate one in the dashboard. A survey run with --no-upload does not need one.

The installer writes only to your home folder, so it needs no administrator rights.

Run the installer

curl -sSfL https://install.spicelabs.io | bash

irm -UseBasicParsing -Uri https://install.spicelabs.io | iex

If Docker is missing or the image cannot be pulled, the installer skips tab completion and prints the command that generates it later.

Set your PATH and Spice Pass

Add the install folder to your PATH and set SPICE_PASS to the Spice Pass you copied from the dashboard.

export PATH="$PATH:$HOME/.local/bin"
export SPICE_PASS="<your-spice-pass>"

$env:Path += ';' + (Join-Path $HOME '.spice\bin')
$env:SPICE_PASS = '<your-spice-pass>'

set "PATH=%PATH%;%USERPROFILE%\.spice\bin"
set "SPICE_PASS=<your-spice-pass>"

$add = Join-Path $HOME '.spice\bin'
$path = [Environment]::GetEnvironmentVariable('Path', 'User')
if (($path -split ';') -notcontains $add) {
  [Environment]::SetEnvironmentVariable('Path', (($path, $add) -join ';').Trim(';'), 'User')
}
[Environment]::SetEnvironmentVariable('SPICE_PASS', '<your-spice-pass>', 'User')

Check the installation

On Windows the first two lines are Powershell Script hash and the hash. Then check your Spice Pass:

spice pass decode

It prints a table of the pass’s claims, such as Project ID, Expires At and Upload Server, and ends with a Status line such as Valid (expires in ...). If the table includes Artifact Cutoff (only trial and demo passes have one), see Artifact cutoff.

Keep it up to date

There are two parts to keep current:

• The CLI image. Before each run, the wrapper pulls the latest image for its tag (latest unless you choose a version). If the pull fails and you have a local copy, the run continues with it and prints Using local copy.
• The wrapper script. After the pull, the wrapper compares itself with the latest release. When yours is older, it prints A newer version of this script is available. Run: followed by the install command. Run the installer again to update it.

To pin a CLI version instead of following latest, or to skip the pull, see Pin the CLI version.

Run without Docker

JVM mode runs the CLI with Java on your machine instead of in Docker. Set SPICE_LABS_CLI_USE_JVM=1 and point SPICE_LABS_CLI_JAR at the CLI jar. JVM mode needs Java 21 or later and a few tools the Docker image otherwise provides: see JVM mode. To build the jar yourself, see the spice-labs-cli repository.

Uninstall

rm ~/.local/bin/spice
rm -rf ~/.local/share/spice ~/.cache/spice
docker rmi spicelabs/spice-labs-cli

Remove-Item -Recurse -Force (Join-Path $HOME '.spice')
Remove-Item -Recurse -Force (Join-Path $env:LOCALAPPDATA 'spice') -ErrorAction SilentlyContinue
docker rmi spicelabs/spice-labs-cli

Uninstalling leaves your survey results alone: results you wrote with --output stay where you put them, and recordings kept with --keep-recording stay under ~/.spicelabs/runtime-survey or the --output folder you chose.

Next steps