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

Docker must be installed and running on your system before using the Spice Labs SurveyorCLI. The CLI uses Docker containers internally to perform software analysis.

• Install Docker: Install Docker for your platform
• Verify Docker is running: docker --version should return version information

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

These installers will navigate you to success:

• Download the latest surveyor tools
• Deploy to your system PATH for instant access
• Establish the spice command as your navigation instrument
• Verify your installation is ready

What the Installer Does

The installer script:

1. Detects your operating system and architecture
2. Downloads the appropriate CLI package
3. Installs it to a standard location:
   • Linux/macOS: /usr/local/bin/spice
   • Windows: C:\Users\{username}\.spice-labs\bin\spice.exe
4. Adds the installation directory to your PATH
5. Runs a verification test

Advanced Installation Methods

Docker Usage

You can run the CLI directly with Docker without installing anything:

docker run --rm \
  -e SPICE_PASS=your-token \
  -v "$PWD:/mnt/input" \
  -v "$PWD/output:/mnt/output" \
  spicelabs/spice-labs-cli \
  --command run \
  --input /mnt/input \
  --output /mnt/output \
  --tag "docker-scan"

Java/Maven Installation

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

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="--tag="my-sample" --command=run --input=./my-dir --output=./out-dir"

Or run the JAR directly:

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

Environment Configuration

Required Environment Variables

SPICE_PASS (Required for uploads) Your authentication token from the Spice Labs 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 tuning flags	--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

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 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

Version Management

You can install specific versions by setting the version before running the installer:

export SPICE_VERSION=v1.2.0
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 images:

docker rmi spicelabs/spice-labs-cli

Troubleshooting

Common Issues

“Command not found: spice”

• Restart your terminal after installation
• Check if /usr/local/bin is in your PATH
• For Windows, verify the installation directory is in your PATH

“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 use JVM mode: export SPICE_LABS_CLI_USE_JVM=1

“Java not found” (JVM mode)

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

System Requirements

Minimum:

• 512MB RAM
• 100MB disk space
• Internet connection for downloads and uploads

Recommended:

• 2GB RAM (for large scans)
• 1GB disk space (for caching)
• Docker or Java 21+

Platform Support

Platform	Architecture	Status
Linux	x64, ARM64	✅ Fully supported
macOS	x64, ARM64 (Apple Silicon)	✅ Fully supported
Windows	x64	✅ Fully supported
Windows	ARM64	⚠️ Docker mode only

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

---