CLI reference

One binary, two modes. lgit mcp starts the MCP server; everything else is the CLI documented here.

Every command prints JSON on stdout, with one exception: lgit fix prints human-readable text by default and JSON only with --json. Errors go to stderr and set a non-zero exit code.

Running gates

lgit check

Run gates against a project root and persist the results.

lgit check <project_root> [gate_id]

project_root is required and positional. Pass a gate_id to run exactly one gate: useful for confirming a fix without re-scanning everything:

lgit check . secrets_scan

Returns the project path, the list of gates that ran, and the findings:

{
  "project": "/Users/you/src/payments-api",
  "gates_run": ["readme_present", "license_present", "..."],
  "findings": [ ]
}

Gates disabled in .l0git.json appear under gates_ignored instead of gates_run.

lgit gates

The registered gate set: id, title, description, severity, tags. This is the authoritative list; the gate reference is generated from it.

lgit gates

Reading findings

lgit list

lgit list [-project=…] [-status=…] [-severity=…] [-gate=…] [-tag=…] \
          [-query=…] [-sort=…] [-limit=…] [-offset=…]

Flag	Values
-project	Absolute project path, as stored by lgit check
-status	open, ignored, resolved, or all
-severity	error, warning, info
-gate	A gate id
-tag	A tag, e.g. security
-query	Substring match across title, message and file path
-sort	updated, created, severity, gate, file
-limit / -offset	Pagination

-project must be the same absolute path check recorded. A relative . will match nothing:

lgit list -project=$PWD -severity=error

Unknown flags and stray positional arguments are rejected with an error rather than ignored.

lgit stats

Aggregate counts: this is what the VS Code dashboard reads.

lgit stats -project=$PWD

Returns total, by_severity, by_status, by_gate, top_files, by_tag and a 7-day trend. Omitting -project aggregates across every project in the store, which is a useful view in its own right but rarely what you meant.

The numbers are only as current as the last check of their project, so stats also says how old that is. With -project: last_checked_at (milliseconds since the epoch; 0 means no check is on record, and it is present) and project_exists (left out when the directory could not be examined). Without it: projects_tracked and projects_missing: the projects with no directory there right now. prune removes those it can tell are gone and lists the ones it kept because they may only be offline. Only a full lgit check counts as a check: running a single gate does not update last_checked_at.

Acting on findings

lgit fix

Print the remediation for one finding. Never executes anything.

lgit fix <finding_id> [--json]

Default output is plain text: what to do, the exact commands, file edits, confidence, a verification step, and a prompt block you can hand to an agent. --json emits the structured form for tooling.

Eight gates carry a deterministic recipe with exact commands. The rest return guided: the finding is real, the fix needs judgement, and the output says so rather than dressing up a restatement of the problem as a solution.

lgit ignore

lgit ignore <finding_id>

Marks the finding ignored so later runs do not resurface it. The row stays in the store.

lgit delete

lgit delete <finding_id>

lgit clear

lgit clear <project_root>

Removes every finding for that project and prints how many rows went.

lgit prune

lgit prune                              # report only: what WOULD be removed
lgit prune -apply                       # remove it
lgit prune -apply -keep-resolved-days=0 # …including every resolved finding

Findings only change when a project is re-checked, so a finding for a project that has been deleted or moved can never be resolved: it stays open for ever and counts in every total. prune removes what can no longer be acted on:

• every finding of a project whose directory is gone.
• resolved findings older than -keep-resolved-days (default 30; 0 removes all of them; at most 36500, a century).

It never removes an open or ignored finding of a project that still exists. Ignored findings are your own decisions and cannot be regenerated by re-running a check.

Gone is not the same as offline, and deleting findings because a drive was unplugged would be data loss, so prune leaves a project alone, and lists it under unreachable_projects: whenever it cannot be sure. A project is treated as gone only when its directory is missing and the nearest directory above it that still exists is populated. It is left alone when: something is at the path but is not a directory (a symlink to a drive that is away); a stat fails for any reason other than "not found", or does not answer; it lives under a mount root (/Volumes, /media, /run/media, ~/Library/CloudStorage, …) and the nearest surviving directory is too shallow to be more than a mount point; the nearest surviving directory is empty (an unmounted volume leaves an empty mount point) or is the filesystem root; or, on Windows, its drive is missing. To remove one of those by hand: lgit clear <project>.

Without -apply nothing is deleted and the output is a report; with it the database is rebuilt afterwards, so the disk space is given back and the removed text is not left behind in the file.

{
  "dry_run": true,
  "vanished_projects": ["/Users/you/old-clone"],
  "vanished_findings": 6055,
  "unreachable_projects": [],
  "resolved_findings": 48889,
  "ignored_kept": 79,
  "bytes_before": 35930112,
  "keep_resolved_days": 30
}

Utilities

lgit path

Print the SQLite store the binary is using.

$ lgit path
/Users/you/.l0-git/findings.db

The store holds every finding of every project you have scanned, so it is private to your user: a database lgit creates, and its WAL files, are 0600, and the default ~/.l0-git directory is 0700. At the default location an older, world-readable store is tightened the first time a newer lgit opens it (bits are only ever removed). A database you choose with LGIT_DB that already exists, and the directory around it, are never touched: it may be shared on purpose. On Windows the store inherits the permissions of its directory.

Finding messages never contain a password: see Connection strings.

lgit version

lgit version

--version and -v are accepted as aliases.

Flag syntax

Flags that take a value accept all four spellings, and they mean the same thing:

lgit list -project=/path/to/repo
lgit list --project=/path/to/repo
lgit list -project /path/to/repo
lgit list --project /path/to/repo

--json on lgit fix is a switch and takes no value.

An unknown flag, a missing value, or a stray positional argument is an error. Nothing is silently ignored: a command that cannot honour what you asked for says so and exits non-zero, rather than answering a different question.

Environment

Variable	Default	Description
LGIT_DB	~/.l0-git/findings.db	Path to the SQLite store. The VS Code setting l0-git.dbPath sets this.