/ 
Cavil-CLI-0.02
/ Cavil::CLI

NAME

Cavil::CLI - Check code against known open source and commercial code indexed by Cavil

SYNOPSIS

Usage: cavil-cli <command> [DIR] [OPTIONS]

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

  # Confirm the URL and token are set up right (and time the round trip)
  cavil-cli whoami

  # With no path, check the current git change set
  cavil-cli check

  # With a path, scan that whole tree
  cavil-cli check ./project

  # Machine-readable output for CI (URL and token from the environment)
  CAVIL_URL=https://legaldb.suse.de CAVIL_API_KEY=1234 cavil-cli check --format json

  # Accept the matches this project already has, so later checks only report new ones
  cavil-cli baseline ./project

Commands:
  check [DIR]              Check a change set or tree for known code (the default workflow)
  baseline [DIR]           Record the tree's current matches as accepted, in .cavil-baseline.json
  whoami                   Show the user the token belongs to, to verify login
  config                   Save the URL and token to ~/.config/cavil-cli (--show to display, token masked)

Credentials come from the saved config ("cavil-cli config"), or CAVIL_URL/CAVIL_API_KEY in CI, always as a
pair from one source. There is no --token (an argument is world-readable in ps and stays in shell history),
and --url is only accepted by "config", since aiming elsewhere would send it a token saved for this server.

Options:
      --url <url>          Cavil server URL, when saving settings ("config" only)
      --all                Whole-tree scan of the current directory (a path already scans the whole tree)
      --since <ref>        Check the diff against this ref instead of the default branch
      --staged             Check staged changes only
      --fail-on-risk <n>   Exit non-zero at risk n or above (default 4, strong copyleft: the point where a
                           copy makes your work a derivative. 1-2 is obligation-free, 3 is file-level
                           copyleft, 5 and up escalate)
      --fail-on-unknown    Exit non-zero if any code has no known provenance
      --baseline <file>    Use this baseline instead of DIR/.cavil-baseline.json
      --no-baseline        Report every match, ignoring an existing baseline
      --exclude-package <name>
                           Ignore matches carried only by this package, so a working copy of an
                           open source project does not match its own indexed package. Repeatable;
                           also read from CAVIL_EXCLUDE_PACKAGES (comma or space separated)
      --exclude-path <glob>
                           Skip files under this path entirely (e.g. test-fixture directories). A bare
                           path excludes it and everything under it; otherwise a shell glob (as Cavil's
                           ignore globs: * matches across /, so *.pattern matches anywhere). Repeatable;
                           also read from CAVIL_EXCLUDE_PATHS
      --format <format>    Output format, "text" (default) or "json"
      --hidden             Also scan hidden files (dotfiles and dot-directories); skipped by default
      --no-color           Disable coloured output
      --quiet              Do not show the progress line while working
  -h, --help               Show this summary of available options

DESCRIPTION

A command-line client that checks whether the code in a git change set or a directory already exists in the open source Cavil has indexed, reporting its license and risk. It is meant for a developer's laptop and for CI; see docs/Architecture.md for the design.