Reference

CLI reference

Kelvar has two command-line tools. The scanner is a standalone Python module that checks a folder and needs no model. The runtime starts and stops the Kelvar system that the app talks to.

Note Both tools keep the vigil name. The scanner is run as python3 -m vigil.cli, and the runtime binary is vigil.

#Scanner

Run the scanner with PYTHONPATH set to the folder that contains the vigil package. It uses only the Python standard library.

PYTHONPATH=/path/to/kelvar/python python3 -m vigil.cli <command> [path] [options]

path defaults to the current directory.

#scan

Scan a folder once, print a JSON report and exit.

python3 -m vigil.cli scan [path] [--agent NAME]... [--diff]

Option	Meaning
`--agent NAME`	Run a built-in agent. Repeat the flag to run several. Defaults to `codebase-guardian`.
`--diff`	Scan only files with uncommitted changes, taken from `git status`. Outside a git repository, it scans everything.

Exit status is 1 when an agent set to block found a high or critical finding, and 0 otherwise.

#watch

Re-scan when files change. It polls the folder about every two seconds, then scans the changed files and prints a report.

python3 -m vigil.cli watch [path] [--agent NAME]...

Press Ctrl-C to stop.

#serve

Run continuously with connectors, policy, a journal and an optional local API.

python3 -m vigil.cli serve [path] [--agent NAME]... [--connectors DIR] \
  [--interval N] [--api-host HOST] [--api-port N] [--once]

See Run as a service for every option.

#summary

Print a 24-hour roll-up of the journal in .vigil/journal.jsonl.

python3 -m vigil.cli summary [path]

#Runtime

The runtime binary manages the Kelvar system.

Command	Meaning
`vigil up`	Start the system and keep it running in the foreground. Setup in the app prepares this command for you.
`vigil down`	Stop the system.
`vigil restart`	Stop the system and start it again.
`vigil doctor`	Check the installation and report problems.

#Environment

Variable	Meaning
`VIGIL_HOME`	The Home directory that holds the registry, runs, ledger and state. Defaults to `~/.vigil`.

On macOS, a path under /tmp resolves to /private/tmp. Kelvar resolves this for you, so either form works.

#Scanner exit codes

Code	Meaning
`0`	The command finished and nothing blocked.
`1`	A block. `scan` found a blocking finding, or `serve --once` blocked.
other	Python raised an error, such as an unknown agent name or an invalid agent file. The message is printed to stderr.