/ 
Cavil-CLI-0.03
/ README.md

Cavil CLI

CI

Get a legal review for the project you are working on. Cavil CLI uploads your working tree to Cavil, runs its standard legal review (unpack, index, analyze), and reports the licensing risk, for a developer's laptop or a CI gate. The uploaded tree includes the vendored dependencies actually on disk (node_modules and the like), which a full review must cover.

Usage

# Save the server and token once (prompts for the token without echoing it)
cavil-cli config --url https://legaldb.suse.de

# Confirm it works (and time the round trip)
cavil-cli whoami

# Upload the current directory for a legal review and print the verdict
cavil-cli check

# Check another directory, and also download the SBOM
cavil-cli check ./project --sbom

Credentials come from the saved config in ~/.config/cavil-cli, or from CAVIL_URL and CAVIL_API_KEY in CI

A check prints a headline tied to the CI gate, a one-line tally, then the licenses found, highest risk first:

$ cavil-cli check ./project
✗ project - risk 6 (restrictive obligations) ≥ threshold 5
  4 licenses · 0 unresolved · review state: new

  ✗  SSPL-1.0                       risk 6 (restrictive obligations)
  •  GPL-3.0-only                   risk 4 (strong copyleft)
  ✓  Apache-2.0                     risk 2 (permissive)
  ✓  MIT                            risk 2 (permissive)

  Report: https://legaldb.suse.de/reviews/details/1234

✓ is obligation-free (permissive or public domain), • carries obligations but is below the gate, ✗ is at or above the gate. The web report link has the full detail.

Access

Submitting a package runs Cavil's full review and enters its legal backlog, so check needs a read-write API key whose user has admin access, the same bar as Cavil's web upload form. Generate a key from the "API Keys" menu after logging in. (A lighter, backlog-free path for ordinary users is planned.)

Commands

cavil-cli <command> [DIR] [options]

| Command | Purpose | | --- | --- | | check [DIR] | Upload a project for a legal review and report its licensing risk (default DIR: .) | | whoami | Verify the configured URL and token | | config | Save the URL and token |

check [DIR]

cavil-cli check              # the current directory
cavil-cli check ./project    # another directory

| Option | Description | | --- | --- | | --name <name> | Package name to review under (default: the directory name) | | --priority <n> | Review priority 1-8 (default 5) | | --fail-on-risk <n> | Exit non-zero at this risk or above (default: the instance's acceptable risk + 1) | | --sbom [<file>] | Download the SPDX SBOM (default file: <name>.spdx.json) | | --notice [<file>] | Download the NOTICE attribution file (default file: <name>.NOTICE.txt) | | --respect-gitignore | Also drop .gitignore'd paths from the archive (off by default, to keep vendored code) | | --exclude-path <p> | Drop this path from the archive (a tar pattern). Repeatable; also CAVIL_EXCLUDE_PATHS | | --external-link <s> | Source label for traceability (default: the git remote and commit, if any) | | --timeout <n> | Seconds to wait for the review before giving up (default 900) | | --format text\|json | Output format; json for CI to police or store | | --no-color | Never colour the output (also honours NO_COLOR) | | --quiet | No progress output | | -h, --help | Show usage |

The archive is the working tree as it sits on disk, minus .git and anything in a .cavilignore file (one tar pattern per line) or given with --exclude-path. Vendored dependencies are kept on purpose; use --respect-gitignore for the leaner case.

To catch an accidental large file (a build artifact, a data dump), check refuses before uploading if the archive exceeds the server's upload limit (250 MiB by default), telling you to trim it. Set CAVIL_MAX_UPLOAD_MB to match an instance configured to accept more.

The default gate is one above the instance's own acceptable risk, so a project the instance would accept passes without any configuration. Raise --fail-on-risk if you already ship higher-risk code, lower it to be stricter.

whoami

cavil-cli whoami

Shows who the token belongs to, its roles and write access, and the round-trip time to the instance.

config

cavil-cli config --url https://legaldb.suse.de   # prompts for the token
cavil-cli config --show

| Option | Description | | --- | --- | | --url <url> | Server to save | | --show | Print the saved settings, with the token masked |

Settings are stored in ~/.config/cavil-cli. The token is read from a hidden prompt (or stdin when piped), never from the command line, where it would linger in shell history and process listings.

Exit codes

| Code | Meaning | | --- | --- | | 0 | Within the risk gate | | 1 | The risk gate failed | | 2 | Usage or configuration problem | | 3 | Server or connection error |

Documentation

See the docs directory, starting with the architecture guide for how it works and why it is built this way.