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.

Installation

macOS/Linux

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

Windows PowerShell

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

After installation, add the CLI to your PATH and export your Spice Pass:

export SPICE_PASS=<your_spice_pass>

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>`	Path to input directory.	Current directory
`--output=<path>`	Directory for output ADGs.	None
`--tag=<tag>`	Required tag used to group scans.	None
`--tag-json=<json>`	Attach JSON metadata to tag.	None
`--threads=<n>`	Threads to use (parallelism).	Half of available cores
`--max-records=<n>`	Max records per batch.	5000
`--log-level=<level>`	Logging verbosity: `all`, `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `off`.	`info`
`--log-file=<path>`	Write logs to file.	None
`--ci`	CI mode (non-interactive).	Off
`--use-static-metadata`	Add static metadata to survey.	Off

Advanced Builder Options

Option	Description
`--ginger-args=<args>`	Extra flags to Ginger uploader (comma-separated). Example: `--ginger-args="--encrypt-only,--skip-key"`.
`--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 --tag=my-service

Upload Existing ADGs

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

CI Mode

spice --ci --command=run --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

docker run --rm   -e SPICE_PASS=...   -v "$PWD/input:/mnt/input"   -v "$PWD/output:/mnt/output"   spicelabs/spice-labs-cli   --command=run   --input=/mnt/input   --output=/mnt/output   --tag=my-service

Upload only:

docker run --rm   -e SPICE_PASS=...   -v "$PWD/output:/mnt/input"   spicelabs/spice-labs-cli   --command=upload-adgs   --input=/mnt/input

Environment Variables

Variable	Description	Default
`SPICE_PASS`	JWT token for authentication (required).	None
`SPICE_LABS_CLI_USE_JVM`	Use JVM instead of Docker (`1` = enable).	`0`
`SPICE_LABS_CLI_JAR`	Path to local JAR when in JVM mode.	`/opt/spice-labs-cli/spice-labs-cli.jar`
`SPICE_LABS_JVM_ARGS`	JVM runtime flags.	`--XX:MaxRAMPercentage=75`
`SPICE_IMAGE`	Docker image name.	`spicelabs/spice-labs-cli`
`SPICE_IMAGE_TAG`	Docker image tag.	`latest`
`SPICE_LABS_CLI_SKIP_PULL`	Skip docker pull (`1` = skip).	`0`

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@v2
        with:
          tag: my-service

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.	Export `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 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

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.jar --version

License

Apache License 2.0. See LICENSE.