Deploy Your Surveyor Tools

Ready to navigate complexity into clarity on any platform? The Spice Labs Surveyor CLI is your navigation instrument across Windows, macOS, and Linux environments. This guide covers every path from simple one-line deployment to advanced configuration options.

Prerequisites

Before using the Spice Labs Surveyor CLI, you need two things:

• Docker must be installed and running on your system. The CLI uses Docker containers internally to perform software analysis. Install Docker for your platform.
• A Spice Pass set as the SPICE_PASS environment variable. Download it from your Spice Labs project dashboard.

Deploy in Minutes (Recommended)

Chart the fastest course to deployment with our official installer scripts:

macOS and Linux

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

Windows PowerShell

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

After installation, add spice to your PATH as instructed by the installer.

Advanced Installation Methods

Docker Usage

You can run the CLI directly with Docker without installing the wrapper script. The CLI image is available on Docker Hub.

Survey and upload:

docker run --rm \
  --user $(id -u):$(id -g) \
  --network host \
  -e SPICE_PASS=... \
  -v "$PWD/input:/mnt/input" \
  -v "$PWD/output:/mnt/output" \
  spicelabs/spice-labs-cli \
  --input=/mnt/input \
  --output=/mnt/output \
  --tag=<tag>

Upload only:

docker run --rm \
  --user $(id -u):$(id -g) \
  --network host \
  -e SPICE_PASS=... \
  -v "$PWD/output:/mnt/input" \
  spicelabs/spice-labs-cli \
  --command=upload-adgs \
  --input=/mnt/input

When using the wrapper script, it automatically remaps --input and --output host paths to /mnt/input and /mnt/output inside the container.

Java/Maven Installation

If you have Java 21+ and Maven 3.6+ installed, you can build and run directly from source:

1. Clone the repository:

git clone https://github.com/spice-labs-inc/spice-labs-cli.git
cd spice-labs-cli

2. Build the project:

mvn clean install

3. Run with Maven:

mvn exec:java -Dexec.mainClass="io.spicelabs.cli.SpiceLabsCLI" \
  -Dexec.args="--command=run --input=./my-dir --output=./out-dir --log-level=all"

Or run the JAR directly:

java -jar target/spice-labs-cli-*-fat.jar --version

Environment Configuration

Required Environment Variables

SPICE_PASS (Required for upload-* commands)

Your JWT authentication token from the Spice Labs project dashboard:

export SPICE_PASS="your-jwt-token-here"

Optional Environment Variables

Variable	Description	Default
SPICE_LABS_CLI_USE_JVM	Use local JVM instead of Docker (1 = enable)	0
SPICE_LABS_CLI_JAR	Path to CLI JAR when using JVM mode	/opt/spice-labs-cli/spice-labs-cli.jar
SPICE_LABS_JVM_ARGS	Custom JVM flags (e.g. -Xmx512m -XX:+UseG1GC)	-XX:MaxRAMPercentage=75
SPICE_IMAGE	Docker image to use	spicelabs/spice-labs-cli
SPICE_IMAGE_TAG	Docker image tag	latest
SPICE_LABS_CLI_SKIP_PULL	Skip docker pull before run (1 = skip)	0
SPICE_DOCKER_FLAGS	Additional flags passed to docker run	(none)

JVM Mode Configuration

For better performance or air-gapped environments, you can use JVM mode:

# Enable JVM mode
export SPICE_LABS_CLI_USE_JVM=1

# Optional: custom JVM settings
export SPICE_LABS_JVM_ARGS="-Xmx2g -XX:+UseG1GC"

# Run normally
spice --command=run --input=./project --output=./results

Verification

After installation, verify everything works:

# Check version
spice --version

# Test basic functionality (requires SPICE_PASS)
spice --command=survey-artifacts --input=. --output=./test-output

Updates

Automatic Updates

The CLI checks for updates on startup and will notify you when a new version is available.

Manual Updates

Re-run the installer script to get the latest version:

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

Uninstallation

Standard Uninstall

Remove the CLI binary:

Linux/macOS:

sudo rm /usr/local/bin/spice

Windows: Remove the installation directory and update your PATH variable.

Docker Cleanup

If you used Docker, clean up the image:

docker rmi spicelabs/spice-labs-cli

Troubleshooting

Common Issues

“Command not found: spice”

• Restart your terminal after installation
• Verify that the installation directory is in your PATH (the installer will tell you which directory to add)

“Permission denied”

• On Linux/macOS, you may need sudo for installation
• Ensure you have write permissions to the installation directory

“Docker daemon not found”

• Install Docker, or switch to JVM mode: export SPICE_LABS_CLI_USE_JVM=1

“Java not found” (JVM mode)

• Install Java 21+ or use Docker mode (default)

Chart Your Next Course

With your surveyor tools deployed, navigate to:

• Quick Start Guide - Survey your first software landscape
• GitHub Actions Integration - Automate surveys in your CI/CD pipeline

---