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.

Usage

Survey and upload (the default flow):

spice survey inventory <subject> <input>

subject — label identifying the system being surveyed (shown on the dashboard)
input — path to artifacts (directory or single file)

Commands

Command	Description
`survey inventory <subject> <input>`	Survey artifacts and upload ADGs (default flow)
`survey inventory <subject> <input> --no-upload`	Survey only, skip upload
`survey inventory <subject> <input> --upload-only`	Upload previously-generated ADGs
`pass decode`	Decode a Spice Pass for verification

CLI Options

Option	Description	Default
`--no-upload`	Survey only, skip upload	`false`
`--upload-only`	Upload previously-generated ADGs (skip survey)	`false`
`--output=<path>`	Output directory for survey results	`~/.spicelabs/surveyor/`
`--tag-json=<json>`	Additional JSON metadata for tags	None
`--threads=<n>`	Number of threads to use	Half of available CPU cores
`--max-records=<n>`	Max records to process per batch	`5000`
`--chunk-size=<n>`	Target chunk size in MB for uploads	`64`
`--log-level=<level>`	Logging verbosity: `debug`, `info`, `warn`, `error`	`info`
`--log-file=<path>`	Append log output to this file (in addition to console). ANSI codes are stripped.	None

Flags can appear anywhere in the command line.

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 survey inventory my-service ./target

Survey Only

spice survey inventory my-service ./src --no-upload --output=./adg-out

Upload Existing ADGs

spice survey inventory my-service ./adg-out --upload-only

Add Metadata

spice survey inventory my-service ./target --tag-json='{"commit":"abc123","branch":"main"}'

Log to File

spice survey inventory debug-test ./target --log-level=debug --log-file=spice.log

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 \
  survey inventory my-service /mnt/input --output=/mnt/output

Upload Only

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

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

Environment Variables

Variable	Description	Default
`SPICE_PASS`	Required for upload. 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
        with:
          subject: my-service
          spice_pass: ${{ secrets.SPICE_PASS }}

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.

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

Run with Docker:

docker build -t spicelabs/spice-labs-cli:local .
SPICE_IMAGE_TAG=local SPICE_LABS_CLI_SKIP_PULL=1 ./spice survey inventory my-app ./path --no-upload

Run with JVM directly:

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

License

Apache License 2.0. See LICENSE.