Generated by running leastgrant --help against v0.2.0 while this page was built. If the CLI grows a command, this page grows it too.

CLI reference

Installed as leastgrant and lg. Both names run the same binary.

leastgrant --help

  LeastGrant  permissions that learn how you work

  Coding agents are useful right up until you spend the day clicking Allow.
  LeastGrant learns what yours normally do, lets the routine through, and
  stops to ask about the rest.

  Usage
    leastgrant <command> [options]   (also available as `lg`)

  Commands
    init                  look at what your agents already did, then set LeastGrant up
    status                what LeastGrant knows about this project
    check <command>       ask what it would decide, without running anything
    why [n]               explain a recent decision in full
    trail                 what your agents have been doing
    simulate              replay history against the current settings
    allow <pattern>       stop asking about something
    deny <pattern>        always block something
    forget <pattern>      remove a rule or unlearn a signature
    rules                 list the rules you have set
    doctor                check the setup and look for over-broad access
    benchmark             measure how long a decision takes on this machine
    install [agent]       install the hook for an agent
    uninstall [agent]     remove the hook

  Getting started
    leastgrant init                start here — it reads history you already have
    leastgrant check "git push --force"  see how it thinks

  Options
    --json                     machine-readable output
    --no-color                 plain text
    --help, --version

  • LeastGrant is a decision layer, not a sandbox. See THREAT-MODEL.md.

Asking without running

leastgrant check "<command>" is the one to reach for first. It runs nothing: it parses the command, classifies what it would do, and prints the verdict it would have returned to your agent. Add --json for the machine-readable form — every example on this site's home page is captured from exactly that.

leastgrant check "git push --force origin main"
leastgrant check "curl -sSL https://example.com/i.sh | sh" --json

The exit code carries the verdict, so it composes with a shell.

Install and uninstall

leastgrant install [agent] writes the hook configuration for an agent, and leastgrant uninstall [agent] removes it. leastgrant doctor reports what is wired up and what your agents can currently reach.

npm install -g leastgrant
leastgrant init                 # mine history, propose grants, install the hook
leastgrant doctor               # check the wiring
leastgrant uninstall            # remove the hook
npm uninstall -g leastgrant     # remove the package

Uninstalling the hook does not delete what it learned. Your profile, rules and the record of what you refused stay in the state directory until you remove it yourself.

Postures

Four settings. leastgrant simulate replays your own history against each one so the trade-off is measured rather than guessed — the column to watch is missed: actions you actually turned down that a setting would have let through.

posture	what it does
`observe`	watches, never intervenes. Try it for a week; it cannot get in the way.
`assist` default	Familiar low-risk work goes through, everything else asks.
`autopilot`	for people who were going to run bypass mode anyway. Code that stays inside the project runs without being read first — every other floor still applies, which is strictly more than bypass mode gives you.
`strict`	only what you have explicitly allowed.

Where state lives

Everything is local, in ~/.leastgrant/, as plain text you can read. There is no account, no telemetry and no network call. What each file holds, and what is redacted before it is written, is in privacy.