Spice Labs Surveyor CLI

The Spice Labs Surveyor CLI surveys software artifacts, generates encrypted Artifact Dependency Graphs (ADGs), and securely uploads them to the Spice Labs platform. It can run locally via JVM or in a containerized environment via Docker.

Prerequisites

• Docker must be installed and running. Get Docker
• A Spice Pass set as the SPICE_PASS environment variable. Download it from your Spice Labs project dashboard.

Installation

macOS / 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.

Commands

Command	Description
run	Survey and upload in one step (default).
survey-artifacts	Generate ADGs locally but do not upload.
upload-adgs	Upload previously generated ADGs.
decode-spice-pass	Decode a Spice Pass file or string for verification.

CLI Options

General

Option	Description	Default
--input=<path>	Input path.	Current directory
--output=<path>	Output path.	None
--tag=<tag>	Tag all top-level artifacts with the current date and the given text. Required for run.	None
--tag-json=<json>	Add JSON to any tags.	None
--threads=<n>	Number of threads to use.	Half of available CPU cores
--max-records=<n>	Max records to process per batch.	5000
--log-level=<level>	Logging verbosity: all, trace, debug, info, warn, error, fatal, off.	info
--log-file=<path>	Append log output to this file (in addition to console). ANSI codes are stripped.	None
--ci	CI mode.	false
--use-static-metadata	Augment Goat Rodeo information with other static metadata.	false

Advanced Builder Options

Option	Description
--ginger-args=<args>	Extra flags to Ginger uploader (comma-separated). Example: --ginger-args="--skip-key,--encrypt-only".
--goat-rodeo-args=<args>	Key=value args to Goat Rodeo surveyor. Example: --goat-rodeo-args="blockList=ignored,tempDir=/tmp".

Example Commands

Full Survey and Upload

spice --input=./target --tag=my-service

Survey Only

spice --command=survey-artifacts --input=./src --output=./adg-out

Upload Existing ADGs

spice --command=upload-adgs --input=./adg-out

CI Mode

spice --ci --input=./target --tag=ci-build

Add Metadata

spice --tag=my-service --tag-json='{"commit":"abc123","branch":"main"}'

Log to File

spice --log-level=debug --log-file=spice.log --tag=debug-test

Docker Usage

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=my-service

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

Note: The wrapper script automatically remaps --input and --output host paths to /mnt/input and /mnt/output inside the container.

Environment Variables

Variable	Description	Default
SPICE_PASS	Required for upload-* commands. JWT token for Spice Labs auth.	None
SPICE_LABS_CLI_USE_JVM	Use the local JVM instead of Docker (1 = enable).	0
SPICE_LABS_CLI_JAR	Path to the 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

GitHub Actions Integration

jobs:
  spice-survey:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Spice Labs Surveyor
        uses: spice-labs-inc/action-spice-labs-surveyor@v5

See the Spice Labs Surveyor GitHub Action for full configuration options.

Troubleshooting

Common Errors

Issue	Cause	Solution
OCI runtime create failed	Mounted a .tar.gz instead of a .tar.	Save Docker image as .tar only.
SPICE_PASS not set	Missing authentication variable.	Set SPICE_PASS before running.
Input directory not found	Incorrect --input path.	Verify mount path or local path.
Permission denied	Docker volume not writable.	Use absolute paths and correct permissions.
Upload failed	Network or token issue.	Re-authenticate and retry with a valid SPICE_PASS.

Debugging

• Increase verbosity with --log-level=debug.
• Write logs using --log-file=spice.log.
• In CI, include --ci for deterministic exits.

Build Locally

Requirements: JDK 21+, Maven 3.6+

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

Output:

target/spice-labs-cli-<version>-fat.jar

Run manually:

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

License

Apache License 2.0. See LICENSE.

---