Command reference#

Every command a Lockpin user runs, with its flags and an example. New to Lockpin? Start with the Quickstart.

lockpin with no command runs the proxy. lockpin -h lists the commands and the proxy’s flags. lockpin COMMAND -h prints one command’s own flags and usage. A flag takes one dash (-day); --day works too.

Where the ledger is#

The ledger is the file that keeps spend across restarts. The installed service writes it as lockpin-ledger.jsonl in the data folder:

System	Data folder
Windows	`%LOCALAPPDATA%\Lockpin`
macOS	`~/Library/Application Support/Lockpin`
Linux	`$XDG_DATA_HOME/lockpin`, else `~/.local/share/lockpin`

LOCKPIN_DATA_DIR changes it. projects, suggest, gaps, pause, resume, stop and quit look in the data folder on their own. The other commands that read the ledger default to lockpin-ledger.jsonl in the current folder: run them from the data folder, or pass -ledger FILE.

Command groups#

Group	Commands
Everyday	`lockpin` (the proxy), `init`, `doctor`, `connect`, `disconnect`, `run`, `pause`, `resume`, `stop`, `quit`, `approve`, `deny`, `receipt`, `projects`, `suggest`, `digest`, `alerts`, `phone`, `drift`, `goal`, `show`, `restore`
Keys and teams	`keys`, `teams`, `workspace`, `invites`, `enroll`, `report`
Team node and remote admin	`node`, `admin`, `capabilities`, `delegate`, `revoke`, `policy`
Prices and providers	`providers` (with `update` and `missing`)
Reports and import	`import`, `reconcile`, `waste-scan`, `plan`, `ledger`
Service and install	`service`, `hooks`, `upgrade`, `uninstall`, `version`
Advanced	`ab`, `replay`, `shapes`, `gaps`, `learn`

Everyday#

`lockpin` (run the proxy)#

Runs the proxy that caps each call. It listens on http://127.0.0.1:8787/v1 and serves the meter at http://127.0.0.1:8787/lockpin/. The installer already runs it as a background service; run it by hand to try flags or to run it in a terminal.

lockpin [flags]

Every flag can also be set under "flags" in lockpin.json and read with -config. A flag given on the command line wins over the file. These are the flags most people use. lockpin -h lists all of them, and Configuration lists every key.

Flag	Default	What it does
`-listen`	`127.0.0.1:8787`	Address to listen on. Keep it on localhost unless `-keys` is on.
`-config`	none	File written by `lockpin init`: default values for any flag not given here.
`-ledger`	`lockpin-ledger.jsonl`	File that keeps spend across restarts.
`-default-budget`	`1`	Budget in USD for tasks that set none. `0` means meter only, no cap.
`-day-limit`	`20`	The most every task on this machine may spend together per UTC day, in USD (solo mode). `0`: no ceiling.
`-ask-at-cap`	`3m0s`	Hold a call that would pass its task’s budget this long and ask in the meter or VS Code. With nobody watching, or no answer in time, it is refused. `0` never asks.
`-ask-headless`	off	Hold calls at the cap even when no screen reads the meter. For a server, container or CI node whose operator answers with `lockpin approve`.
`-alert-at`	`80`	Alert when spend reaches this percent of a key, team, tag or project limit (and of a task budget when `-task-warn-at` is empty). `0`: only when the cap blocks a call.
`-task-warn-at`	`75,95`	Warn when a task has spent these percents of its budget, once each: an alert, and the `X-Lockpin-Task-Warning` header on the task’s calls. Empty: one alert at `-alert-at`.
`-keys`	none	Team mode: require a Lockpin key from this file on every call (see `lockpin keys`).
`-prices`	none	Catalog file(s), comma-separated, with extra or changed providers and model prices.
`-on-fault`	`block`	When Lockpin’s own ledger or keys file fails: `block` (refuse the call with a 503) or `allow`.
`-report`	`off`	Optional reporting to the dashboard: `off` or `on`.
`-open`	off	Open the meter in your browser once Lockpin is running. If Lockpin already runs on `-listen`, just open it.
`-v`	off	Log every request.

lockpin -default-budget 5 -open
lockpin -config lockpin.json

In team mode every call with a key that has an end carries X-Lockpin-Key-Expires (RFC 3339), so a client or an agent harness can show it.

`lockpin init`#

Writes lockpin.json (and, for a team server, a keys file with a first key), then prints what to set and what to give your agent. It asks about anything you did not pass as a flag. It never asks for, reads or prints a provider key. lockpin init -schema prints every key lockpin.json may set.

lockpin init [flags]
lockpin init -schema

Flag	Default	What it does
`-mode`	`local`	`local`: one person, own keys pass through. `team`: every call needs a Lockpin key with limits.
`-providers`	the ones whose key variable is set, else `meta`	Comma-separated, for example `meta,openai,anthropic`.
`-listen`	`127.0.0.1:8787`	Address to listen on.
`-default-budget`	`1.00`	Budget in USD for tasks that set none.
`-key-name`	`me`	Team mode: the first key’s name.
`-key-day`	`20`	Team mode: that key’s daily limit in USD (`0` for none).
`-key-month`	none	Team mode: that key’s monthly limit in USD.
`-dir`	this folder	Where to write the files.
`-prices`	none	Extra catalog file, as for `lockpin -prices`.
`-force`	off	Overwrite an existing `lockpin.json`.
`-yes`	off	Do not ask; use flags and defaults.

lockpin init -yes -providers anthropic,openai
lockpin init -dir team -mode team -key-name alice -yes -providers openai

`lockpin doctor`#

Checks the whole chain and prints a pass/fail list with a fix for each failure: the price catalog and its age, the port, whether a Lockpin answers there, the background service, the ledger, each provider’s key variable, which agents on this machine send their calls through Lockpin and which hooks they have, and where a test call to each provider would go. It makes no model calls and never prints a key.

lockpin doctor [-config FILE] [-providers LIST] [-network] [flags]

Flag	Default	What it does
`-config`	none	The file `lockpin init` wrote (providers and flags come from it).
`-providers`	the config’s, else the ones whose key is set	Providers to check.
`-network`	off	Also send one HEAD request, with no credentials, to each provider’s host.
`-listen`, `-admin-listen`, `-keys`, `-capabilities`, `-ledger`, `-prices`	as for the proxy	As for `lockpin` itself. A flag wins over the config.
`-ca-file`	`LOCKPIN_CA_FILE`	Extra root certificates (PEM) to trust.
`-policy-dir`	this system’s	The machine’s signed policy folder.

lockpin doctor
lockpin doctor -config lockpin.json -network

`lockpin connect` and `lockpin disconnect`#

connect points an agent at Lockpin by changing its own settings, after showing the change and asking. The old file is kept as a backup. disconnect takes out what connect added. A company can set the same for everyone in the agents’ managed settings, which connect does not change (see Connect an agent).

lockpin connect claude|codex|cursor [-project] [-default] [-listen ADDR] [-dry-run] [-yes] [-force]
lockpin disconnect claude|codex [-project] [-listen ADDR] [-dry-run] [-yes]

Agent	What `connect` does
`claude`	Sets `ANTHROPIC_BASE_URL` in `~/.claude/settings.json`, for every session on this machine.
`codex`	Adds a Lockpin provider to `~/.codex/config.toml` and a `lockpin` profile. Run `codex --profile lockpin`.
`cursor`	Prints the steps. Cursor’s own servers make its calls, so they cannot reach a Lockpin on this machine.

Flag	Default	What it does
`-project`	off	Claude Code: write `.claude/settings.local.json` in this folder instead (never the shared `.claude/settings.json`).
`-dir`	`.`	The project folder, with `-project`.
`-default`	off	Codex: make Lockpin the default provider.
`-listen`	`127.0.0.1:8787`	The address Lockpin listens on.
`-dry-run`	off	Show the change, write nothing.
`-yes`	off	Write without asking.
`-force`	off	Connect even when no Lockpin answers on `-listen`.

lockpin connect claude
lockpin connect codex
lockpin disconnect claude

`lockpin run`#

Runs an agent with its calls charged to one task, so the task’s budget caps it even when the agent cannot send X-Lockpin-Task. The task is -task, else the git branch of this folder, else the folder’s name. The agent’s base URLs (ANTHROPIC_BASE_URL, OPENAI_BASE_URL, GOOGLE_GEMINI_BASE_URL) point at Lockpin with the task and project in the path. An agent whose own settings name a base URL (lockpin connect writes Claude Code’s) uses those instead.

lockpin run [-task NAME] [-project NAME] [-listen ADDR] -- COMMAND [ARGS...]

Flag	Default	What it does
`-task`	the git branch, else the folder’s name	The task to charge.
`-project`	the one Lockpin finds for this folder	The project to charge.
`-listen`	`127.0.0.1:8787`	The address Lockpin listens on.

lockpin run -- claude
lockpin run -task nightly-refactor -- codex exec "fix the tests"

`lockpin pause`, `resume`, `stop` and `quit`#

These four talk to the Lockpin running on -listen. They use its control token, kept beside its ledger.

lockpin pause 15m|1h|8h [-listen ADDR] [-ledger FILE]
lockpin resume [-listen ADDR] [-ledger FILE]
lockpin stop [-listen ADDR] [-ledger FILE]
lockpin quit [-listen ADDR] [-admin-listen ADDR] [-ledger FILE] [-yes]

Command	What it does
`pause`	Calls pass through without a cap until then (1m to 8h, 8h a day), each one still counted. The pause ends by itself, or at `resume`. A person confirms it at a terminal: it cannot be scripted.
`resume`	Cap calls again now.
`stop`	Stop Lockpin. Agents still pointed at it then fail until it is started again, so to end Lockpin use `quit`.
`quit`	First disconnect Claude Code and Codex (and this folder’s `.claude/settings.local.json`), so new agent sessions go to the provider directly, then stop Lockpin. It stops nothing while an agent still points at it. A session already open keeps Lockpin’s address until it is restarted.

Flag	Default	What it does
`-listen`	`127.0.0.1:8787`	The address Lockpin listens on.
`-admin-listen`	none	The address Lockpin serves its meter on, when not `-listen`.
`-ledger`	the data folder’s	Lockpin’s ledger file; its control token is beside it.
`-yes`	off	`quit`: disconnect without asking.

lockpin pause 15m
lockpin resume

`lockpin approve` and `lockpin deny`#

Answer a call that a Lockpin on this machine holds at a task’s budget, or in a loop, without the meter. Use them on a server, in a container (kubectl exec) or over SSH. Lockpin holds a call only while someone can answer it: on a machine no screen watches, run it with -ask-headless (see Approvals at the cap). A headless Lockpin takes an answer only with its control token, which it keeps beside its ledger for its own account.

lockpin approve list [-json] [-listen ADDR] [-admin-listen ADDR] [-ledger FILE]
lockpin approve ID [-budget | -raise USD] [-listen ADDR] [-admin-listen ADDR] [-ledger FILE]
lockpin deny ID [-listen ADDR] [-admin-listen ADDR] [-ledger FILE]

Flag	Default	What it does
`-json`	off	`list`: print JSON.
`-budget`	off	`approve`: raise the budget by one more budget instead.
`-raise`	none	`approve`: raise the budget by this many USD, at least what the call needs.
`-listen`	`127.0.0.1:8787`, then a node’s `127.0.0.1:8790`	The address Lockpin listens on.
`-admin-listen`	none	The address Lockpin serves its meter on, when not `-listen`.
`-ledger`	the running Lockpin’s	Its ledger; the control token is beside it.

approve ID lets the held call go: the task’s budget rises by what the call needs beyond what is left (in a loop: the call goes on). deny ID refuses it: the held call gets its 402 now. The ledger records each answer.

lockpin approve list
lockpin approve ID -raise 2
lockpin deny ID

`lockpin receipt`#

Prints the receipts of the last N calls, newest first: what each would have cost without Lockpin, what it cost, the lines that explain the difference, and the refusals. It reads the ledger file, so it works with Lockpin stopped.

lockpin receipt [-ledger FILE] [-n N] [-json] [TASK]

Flag	Default	What it does
`-ledger`	`lockpin-ledger.jsonl`	The ledger file Lockpin writes.
`-n`	`10`	How many calls to print.
`-json`	off	Print JSON.
`TASK`	all tasks	Limit the receipts to one task.

lockpin receipt -n 5

`lockpin projects`#

Shows each project’s spend today, this week, this month and in total, against the limits under "projects" in the config file, and what is left on the tightest. A call’s project is the repository its agent works in. Project names stay on this machine.

lockpin projects [-ledger FILE] [-config lockpin.json] [-json]

Flag	Default	What it does
`-ledger`	the service’s ledger	The ledger file.
`-config`	`lockpin.json` here or in the data folder	The config file with the project limits.
`-json`	off	Print JSON.

lockpin projects

`lockpin suggest`#

Says when a task would have cost less on its model’s cheaper step in the catalog, priced from its own calls with the same tokens, and how sure that is. With no TASK, it shows the five tasks that would have saved most. Advice only: Lockpin never switches models. It is off unless "suggest-cheaper" is on in the config file or a team admin turned it on in the dashboard.

lockpin suggest [-ledger FILE] [-config lockpin.json] [TASK]

Flag	Default	What it does
`-ledger`	the service’s ledger	The ledger file.
`-config`	`lockpin.json` here or in the data folder	The config file.
`TASK`	the top five	One task to look at.

lockpin suggest

`lockpin digest`#

Prints the last 7 days from the ledger: what was spent (against the week before), what Lockpin saved, the calls it blocked, the loops it caught and the tasks that spent most. A running Lockpin posts it to the alert destinations itself every week (-digest-at, default mon 09:00).

lockpin digest [-ledger FILE] [-send] [-alert-slack URL] [-alert-teams URL]
               [-alert-ntfy URL] [-alert-webhook URL]

Flag	Default	What it does
`-ledger`	`lockpin-ledger.jsonl`	The ledger file.
`-send`	off	Also post it to the alert destinations.
`-alert-slack`	`$LOCKPIN_ALERT_SLACK`	Slack incoming webhook URL.
`-alert-teams`	`$LOCKPIN_ALERT_TEAMS`	Microsoft Teams Workflows webhook URL.
`-alert-ntfy`	`$LOCKPIN_ALERT_NTFY`	ntfy topic URL.
`-alert-webhook`	`$LOCKPIN_ALERT_WEBHOOK`	URL that gets every alert as JSON.
`-listen`	`127.0.0.1:8787`	The address Lockpin listens on, for the meter’s link.

lockpin digest

`lockpin alerts`#

Sends one test alert to each destination, so you can check the setup without spending anything.

lockpin alerts test [-alert-slack URL] [-alert-teams URL] [-alert-ntfy URL] [-alert-webhook URL] [-ledger FILE]

The destination flags are the same as for lockpin digest.

Tip

Keep webhook URLs out of shared shell history: set them in the LOCKPIN_ALERT_* environment variables instead of passing them as flags.

lockpin alerts test -alert-slack URL

`lockpin phone`#

Pairs a phone for Lockpin’s alerts, its weekly digest and, with -ask-remote, its questions about held calls, as end-to-end encrypted notifications. There is no app store: the page installs to the home screen. See Alerts and phone approvals.

lockpin phone pair [-ledger FILE] [-relay URL] [-wait 15m]
lockpin phone list [-ledger FILE]
lockpin phone forget [-ledger FILE]

Flag	Default	What it does
`-ledger`	`lockpin-ledger.jsonl`	The ledger file Lockpin writes; the phones are kept next to it.
`-relay`	`https://app.lockpin.dev`	The relay that serves the phone page.
`-wait`	`15m`	`pair`: how long to wait for the phone.

pair shows a link and a QR code. list shows the paired phones. forget unpairs them all.

lockpin phone list

`lockpin drift`, `goal`, `show` and `restore`#

Drift tracking catches work an agent redoes, undoes or loses. Start Lockpin with -drift FOLDER on the project to turn it on. These commands read its history. drift lists the findings (drift tree shows them against the goal). goal shows or sets the project’s goal. show prints a file as it was at a drift step, and restore puts it back. See Loop checks and drift.

lockpin drift [tree] [-repo DIR] [-all] [-goal FILE] [-store DIR]
lockpin goal [show] [-repo DIR] [-goal FILE]
lockpin goal set [-repo DIR] "what the work is for"
lockpin show [-repo DIR] -step N PATH
lockpin restore [-repo DIR] -step N PATH

Flag	Default	What it does
`-repo`	`.`	The project folder that was tracked with `-drift`.
`-all`	off	List every finding, not just the latest 20.
`-step`	none	Step number (from `lockpin drift` or the meter).
`-goal`	`GOAL.md` or `REQUIREMENTS.md` if present	The goal file in the project.
`-store`	none	The `-drift-store` used, if any.

lockpin drift
lockpin goal set "Fix the login bug without changing the API"

Keys and teams#

`lockpin keys`#

Makes and manages Lockpin keys (lp_...) for team mode. A key gives a person or an agent their own daily, weekly and monthly limits, so nobody holds the provider key. Start the proxy with -keys FILE to require them. A running lockpin -keys picks up changes within a second. Periods are UTC calendar days, weeks (from Monday) and months. See Person and service keys.

lockpin keys create NAME [-day USD] [-week USD] [-month USD] [-total USD] [-user-day USD] [-tag NAME=VALUE ...]
                   [-providers LIST] [-models LIST] [-team TEAM] [-role ROLE] [-expires WHEN]
                   [-service] [-task USD] [-task-cap ask|hard]
lockpin keys list
lockpin keys set NAME [limits] [-expires WHEN] [-task USD] [-task-cap ask|hard]
lockpin keys disable NAME
lockpin keys enable NAME
lockpin keys rotate NAME [-expires WHEN]
lockpin keys lifetime [-max-days N] [-person-days N] [-service-days N] [-force]
lockpin keys seal PROVIDER [-sealed FILE]

Command	What it does
`create NAME`	Add a key and print it, with the date it expires. The secret is shown only this once. A person’s key lives 180 days, a service key 90, unless `-expires` or `lifetime` says otherwise.
`list`	Keys, their kind (`person` or `service`), when each expires (`in 9 days`, `expired`, `never`), their limits and spend so far. A limit marked `*` is the team’s member default. A closing line names the keys that expire within 14 days and the command that renews them.
`set NAME`	Change a key’s limits (only the ones given; `0` removes one), tags (`-tag team=backend` sets one, `-tag team=` removes it), end (`-expires`) and task budget (`-task`, `-task-cap`).
`disable NAME`	Stop a key at once.
`enable NAME`	Let a disabled key work again.
`rotate NAME`	Renew a key: a new secret and a fresh lifetime as long as before, with the same name, limits, team, role and spend history. The old secret stops working. An expired key comes back this way.
`lifetime`	Show or set how long keys live. `-max-days N` ends every key at most N days after its secret was made; keys made before it count from the day it is set. A maximum that would end keys at once is refused unless `-force`, which gives them 14 days, with the warnings. It never ends the key `lockpin init` or `lockpin node install` made. `-person-days` and `-service-days` set new keys’ lifetimes (`0`: no end of their own).
`seal PROVIDER`	Team node: read a provider’s API key from stdin (one line; `meta` for `MODEL_API_KEY`’s) and keep it in the node’s sealed store.

Flag	Default	What it does
`-day`, `-week`, `-month`, `-total`	none	Limit in USD per day, per week, per month, or in total.
`-user-day`	none	USD per day for each user of the key, named by `X-Lockpin-User`.
`-tag`	none	`NAME=VALUE` added to every call made with the key. Repeat it for more.
`-providers`	all	Comma-separated providers the key may use. An empty value allows all again.
`-models`	all	Comma-separated model patterns the key may use, `` for any run of characters, such as `'gpt--mini,claude-haiku-*'`.
`-team`	none	The team the key belongs to (see `lockpin teams`). A key cannot allow more than its team.
`-role`	none	`owner`, `admin`, `lead` (of its team) or `member`.
`-expires`	the kind’s lifetime	When the key stops working: `Nd` (days from now), a date `YYYY-MM-DD` (UTC) or `never` (the maximum still applies). At most ten years away.
`-service`	off	`create`: a service key for an automated job (a CI job, a cron agent). See the note below.
`-task`	`-default-budget`	USD each new task of the key starts with. A task’s `X-Lockpin-Budget-Usd` can still only lower it, and a signed policy’s lower default still binds.
`-task-cap`	`ask` for people	At a task’s budget: `ask` holds the call and asks whoever watches the meter (nobody: `402`); `hard` refuses at once, asking no one. Service keys are always `hard`. Key, team and day limits refuse in both modes.
`-file`	`lockpin-keys.json`	The keys file.
`-ledger`	`lockpin-ledger.jsonl`	The spend log, read by `list`.
`-sealed`	`lockpin-node.sealed`	`seal`: the node’s sealed store.

Note

A service key’s name is svc.TEAM.JOB or svc.TEAM.JOB.ENV, and -team is required. It is always a member, never administers or answers held calls, and every call must name its run in X-Lockpin-Task (else 400 task_required). A run that would pass its task budget is refused with no one asked.

lockpin keys create alice -team eng -day 40
lockpin keys create bob -expires 30d
lockpin keys create svc.eng.ci-review.prod -service -team eng -day 50 -task 8
lockpin keys list
lockpin keys set alice -day 60
lockpin keys rotate alice
lockpin keys lifetime -max-days 365

A key’s holder sees its own spend and limits at /lockpin/me on the server’s -listen address, and in VS Code (extension 0.1.5 and later) with Lockpin: Set my Lockpin key, which keeps the key in VS Code’s secret storage and shows it under Me in the Overview; Lockpin: Forget my Lockpin key removes it.

Lockpin warns 14 and 3 days before a key expires, and when it has (alerts key_expiring and key_expired, in the meter, the member page, VS Code and the alert destinations). An expired key’s calls are refused with 401 key_expired, naming the command that renews it.

`lockpin teams`, `workspace` and `invites`#

Teams group keys under a shared budget. The workspace is the whole organisation on this server. An invite is a link that makes one key when someone opens it. See Set up a team.

lockpin teams list
lockpin teams create NAME [limits] [-providers LIST] [-models LIST]
lockpin teams set NAME [limits] [-providers LIST] [-models LIST] [-member-day USD] [-member-week USD]
                  [-member-month USD] [-member-total USD]
lockpin teams delete NAME
lockpin workspace show
lockpin workspace set [-name NAME] [-kind business|personal] [limits] [-providers LIST] [-models LIST] [-owner KEY]
lockpin invites list
lockpin invites create -url ADDRESS [-team TEAM] [-role member|lead] [-days N]
lockpin invites revoke ID

Flag	Default	What it does
`-day`, `-week`, `-month`, `-total`	none	Limits in USD (`0` removes one). A team’s budget is shared by its keys; the workspace’s by every key.
`-providers`	all	Providers the team or workspace allows. A team cannot allow one the workspace does not.
`-models`	all	Model patterns it allows.
`-member-day`, `-member-week`, `-member-month`, `-member-total`	none	`teams set`: the team’s member default. Each person’s key in the team is held to the lower of this and its own limit (`0` removes one). It cannot be above the team’s own limit for the same period. Service keys keep their own. `teams list` shows it.
`-name`	none	`workspace set`: the workspace’s name.
`-kind`	none	`workspace set`: `business` or `personal`.
`-owner`	none	`workspace set`: the key that owns the workspace.
`-url`	none	`invites create`: how members reach this server, such as `http://10.0.0.5:8787`.
`-team`	none	`invites create`: the team the new key joins.
`-role`	none	`invites create`: `member` or `lead`.
`-days`	`7`	`invites create`: how long the invite lasts (at most 30).
`-file`	`lockpin-keys.json`	The keys file. Every change goes into its audit list.

An invite is single-use. Only its hash is kept, so the link is shown once. A key made from an invite lives 180 days, like one made with lockpin keys create. Put an existing key in a team with lockpin keys set NAME -team TEAM -role member.

lockpin teams create backend -day 100
lockpin teams set backend -member-day 20
lockpin invites create -url http://10.0.0.5:8787 -team backend

`lockpin enroll`#

Joins this machine to your team with the code your admin gave you. Joining shares a short status report with your team’s admins; it never includes prompts, replies, code, file names, task names, screens or keystrokes. It does not turn on the usage upload. lockpin enroll status shows exactly what your admin sees.

lockpin enroll CODE [-url ORIGIN] [-ledger PATH] [-yes]
lockpin enroll status [-ledger PATH]
lockpin enroll trust sk_... [-ledger PATH]
lockpin enroll leave [-ledger PATH] [-yes]

Command	What it does
`enroll CODE`	Join a team with the code your admin gave you.
`enroll status`	Show exactly what your admin sees.
`enroll trust sk_...`	Accept a status key your admin reset.
`enroll leave`	Leave the team.

Flag	Default	What it does
`-url`	`https://ingest.lockpin.dev`	Ingest base URL.
`-ledger`	`lockpin-ledger.jsonl`	Local ledger file.
`-yes`	off	Do not ask first.

lockpin enroll status

`lockpin report`#

Optional reporting to the hosted dashboard. Reporting runs off the call path and never changes a decision. preview prints what would be uploaded, so you can see it before you turn reporting on. status prints the reporter’s state. Turn reporting on with -report on and -report-token (see Configuration and Hosted dashboard and reporting).

lockpin report preview|status [-ledger PATH] [-state PATH]

Flag	Default	What it does
`-ledger`	`lockpin-ledger.jsonl`	Local ledger file.
`-state`	`LEDGER.report-state.json`	Report state file.
`-detail`	`tags`	`preview`: local maximum detail: `totals`, `tags` or `tasks`.

lockpin report preview

Team node and remote admin#

A team node is one Lockpin on a shared machine that holds the team’s provider keys, runs as its own account, and hands out lp_... keys or short-lived lpc_... spend capabilities instead. These commands are for the people who set one up. See Run a team node and Remote admin.

`lockpin node`#

Makes this machine a team node. Run install elevated: from an administrator’s prompt on Windows, with sudo on macOS and Linux.

lockpin node install|uninstall|status|start|stop|restart [-args "FLAGS"] [-key-file FILE] [-reseal] [-yes]
             [-dry-run] [-no-start] [-pause] [-policy-trust FILE.pub] [-policy-required]
lockpin node run [-data DIR] [-key-file FILE] [-listen ADDR] [-admin-listen ADDR] [-- PROXY FLAGS]
lockpin node health [-listen ADDR]
lockpin node admin-key [-data DIR] [-keep]

Command	What it does
`install`	Make the node’s account and folder, copy `lockpin` where only an administrator can change it, seal the provider keys (read from stdin, one per line as `provider=key`, an empty line ends them), write a keys file with one team key named `admin`, register the node and start it. Run it again after upgrading or to change `-args`.
`uninstall`	Stop it and remove the definition and the program’s copy. The folder (sealed store, keys file, ledger) and the account stay.
`status`, `start`, `stop`, `restart`	Installed or not, running or not, its pid and the log; start, stop or restart it.
`run`	Run a node in the foreground, as the current account: for a container, a Kubernetes pod or a service manager you set up yourself. SIGTERM stops it cleanly.
`health`	Exit 0 when the node on `-listen` answers `/lockpin/healthz` with 200, else 1. For a container’s `HEALTHCHECK`.
`admin-key`	Print the admin key `node run` wrote at its first start, then delete its file.

Flag	Default	What it does
`-args "FLAGS"`	none	More proxy flags (split on spaces), after the node’s own.
`-key-file FILE`	`$LOCKPIN_KEY_FILE` for `run`	Read the provider keys from FILE (`provider=key` per line, `#` comments) instead of stdin. With a sealed store already there, `install` uses it only with `-reseal`.
`-reseal`	off	`install`: ask for the provider keys again and replace them. The node key and the root secrets stay.
`-yes`	off	Go ahead without asking.
`-dry-run`	off	Print every file and command, and change nothing.
`-no-start`	off	`install`: register it, but do not start it now.
`-pause`	off	`install`: then wait for Enter, so the window stays until the admin key is copied.
`-policy-trust FILE.pub`	none	`install`: pin the signed policy’s public key (`lockpin policy keygen`) in the machine’s policy folder.
`-policy-required`	off	`install`: the node refuses every call while no signed policy is in force.
`-data DIR`	`/var/lib/lockpin` or `$LOCKPIN_NODE_DATA` for `run`	The node’s folder.
`-listen ADDR`	`127.0.0.1:8787`	`run`, `health`: the address to listen on. In a container give `0.0.0.0:8787`.
`-admin-listen ADDR`	`127.0.0.1:8790`	`run`: where the meter and `lockpin approve` talk. It stays on loopback.
`-keep`	off	`admin-key`: leave the key’s file in place.

sudo lockpin node install
lockpin node status

`lockpin admin`#

The remote admin channel of a team node: how an admin on another computer changes the node’s keys, teams and limits over TLS with pinned keys and a signed grant per change.

lockpin admin keygen -name NAME [-sealed FILE]
lockpin admin node-id [-data DIR]
lockpin admin enroll "LINE" -role owner|admin [-team TEAM] [-data DIR]
lockpin admin call -node https://HOST:PORT -node-fp sha256:HEX [-sealed FILE] METHOD PATH [BODY]

Command	Where	What it does
`keygen`	the admin’s computer	Make the admin’s keys, keep them in a sealed store, and print one line of public keys to give the node.
`node-id`	the node, as an administrator	Make the node’s channel identity once and print the fingerprint every admin pins. Run it again to print it again.
`enroll`	the node, as an administrator	Add an admin’s line to the node’s admin list as `owner` (the whole workspace) or `admin` (`-team`: one team; none: the whole workspace). Delete a line in `lockpin-admins.txt` to revoke an admin.
`call`	the admin’s computer	Send one request to the node over the channel, with a fresh grant for a change, and print the answer. `BODY` of `-` reads it from stdin.

Flag	Default	What it does
`-name`	none	`keygen`: your name on the node’s admin list: letters, digits, `.`, `_`, `-`.
`-sealed`	`Lockpin/lockpin-admin.sealed` in your config folder	The sealed store that keeps your keys.
`-data`	this system’s node folder	The node’s folder, as for `lockpin node`.
`-role`	none	`enroll`: `owner` or `admin`.
`-team`	none	`enroll`, admin only: the one team it acts on.
`-node`	none	`call`: the node’s admin listener, `https://HOST:PORT`.
`-node-fp`	none	`call`: the node’s fingerprint, `sha256:...`, as `node-id` printed it.

lockpin admin keygen -name alice
lockpin admin call -node https://10.0.0.5:8790 -node-fp sha256:HEX GET /lockpin/api/teams
lockpin admin call -node https://10.0.0.5:8790 -node-fp sha256:HEX POST /lockpin/api/teams '{"name":"ops"}'

Note

The channel does not let a remote admin raise a task’s budget or a team’s limits. Those need the meter page on the node’s own machine.

`lockpin capabilities`, `delegate` and `revoke`#

A spend capability (lpc_...) is a short-lived token that says which task, how many dollars, which models and tools, and until when. A client sends it where it sends a team key: Authorization: Bearer lpc_... or x-api-key.

lockpin capabilities mint -issuer NAME -usd USD [-expires 24h] [-task TASK] [-models LIST] [-tools LIST] [-sealed FILE]
lockpin capabilities show
lockpin capabilities rotate [-grace 10m] [-sealed FILE]
lockpin delegate -usd USD [-expires DUR] [-task SEGMENT] [-models LIST] [-tools LIST] [-fresh SECONDS]
lockpin revoke -root ID | -issuer NAME [-sealed FILE]

Command	What it does
`capabilities mint`	Mint a root capability on this node and print it (the node’s admin).
`capabilities show`	Print what a capability allows, read from `LOCKPIN_CAPABILITY` or stdin.
`capabilities rotate`	Start a new root secret. Tokens under the old one work until the grace ends.
`delegate`	Read a capability from `LOCKPIN_CAPABILITY`, or stdin, and print a child that can do no more than its parent. No node and no network.
`revoke`	Add a root capability (`-root ID`) or every root of an issuer (`-issuer NAME`) to the revocation list in the node’s next heartbeat. Run it on the issuer node.

Flag	Default	What it does
`-issuer`	none	`mint`: the issuer’s name. `revoke`: revoke every root of this issuer.
`-usd`	none	The budget in USD. For `delegate`, at most the parent’s.
`-expires`	`24h` for `mint`; the shorter of the parent’s end and `2h` for `delegate`	When it ends.
`-task`	random segment for `delegate`	The task. `delegate` adds one segment to the parent’s task.
`-models`, `-tools`	all of the parent’s	Comma-separated lists. `delegate` takes a subset of the parent’s.
`-fresh`	none	`delegate`: a shorter heartbeat age, in seconds.
`-grace`	`10m`	`rotate`: how long tokens under the old secret keep working.
`-root`	none	`revoke`: the id `capabilities mint` printed.
`-sealed`	`lockpin-node.sealed`	The node’s sealed store.

lockpin capabilities mint -issuer ci -usd 5 -expires 24h
lockpin delegate -usd 0.50

`lockpin policy`#

The signed policy file IT pushes to every machine. It sets floors that other settings can only tighten. See Signed policy.

lockpin policy keygen -out DIR [-name NAME]
lockpin policy sign -key NAME.key [-out FILE] POLICY.json
lockpin policy verify [-pub NAME.pub | -policy-dir DIR] FILE
lockpin policy trust [-policy-dir DIR] [-note TEXT] NAME.pub|BASE64
lockpin policy trust -list | -remove KEY_ID [-policy-dir DIR]
lockpin policy show [proxy flags]

Command	What it does
`keygen`	Make a signing key pair: `NAME.key` (keep it with IT, never on a managed machine) and `NAME.pub` (the key machines pin).
`sign`	Check a policy and sign it (in place without `-out`). A file the machines would refuse is not signed.
`verify`	Check a signed policy as this machine would, against its pinned keys.
`trust`	Pin a public key on this machine (as an administrator). `-list` shows pinned keys and `-remove KEY_ID` removes one.
`show`	The settings in force and where each one comes from.

Flag	Default	What it does
`-out`	none	`keygen`: the folder for the key pair. `sign`: the file to write.
`-name`	none	`keygen`: the key pair’s name.
`-key`	none	`sign`: the private key file.
`-pub`	none	`verify`: the public key to check against.
`-policy-dir`	`%ProgramData%\Lockpin\policy`, `/Library/Application Support/Lockpin/policy` or `/etc/lockpin`	The machine’s policy folder (Windows, macOS, Linux).
`-note`	none	`trust`: a note kept with the pinned key.
`-list`	off	`trust`: list the pinned keys.
`-remove`	none	`trust`: remove a pinned key by its id.

lockpin policy keygen -out . -name it
lockpin policy sign -key it.key policy.json
lockpin policy show

Prices and providers#

`lockpin providers`#

Lists each provider, the base URL to give its SDK, whether its key is set, and its models with a price. lockpin prices is the same command. A model without a price is refused, so the catalog matters. See Prices and the price feed.

lockpin providers [-models] [-listen ADDR] [-prices FILE]
lockpin providers update [flags]
lockpin providers missing -provider NAME [-base URL] [-prices FILE]

Flag	Default	What it does
`-models`	off	List every model with its price.
`-listen`	`127.0.0.1:8787`	The address Lockpin listens on.
`-prices`	none	Extra catalog file, as for `lockpin -prices`. For `update`: the file to store the catalog in (default `lockpin-prices.json`).

providers update fetches the signed price feed and checks it. It refuses a catalog that lowers a price a lot or changes where calls go, unless you say so. Run lockpin with -prices on the file to use it.

Flag	Default	What it does
`-dry-run`	off	Check and show what would change; write nothing.
`-feed`	the machine policy’s feed, else the built-in one	HTTPS URL of a signed price feed (its signature is the URL with `.sig` added).
`-url`	none	HTTPS URL of an unsigned catalog JSON to fetch instead of the signed feed.
`-from`	none	Read the catalog from this file instead of a URL, with the same checks.
`-sig`	none	With `-from`: the feed’s `.sig` file, so the file is checked as a signed feed.
`-max-drop`	`50`	Refuse a catalog that lowers a model’s price by more than this percent, unless `-force`.
`-force`	off	Accept price drops above `-max-drop`.
`-allow-providers`	off	Accept a catalog that adds a provider or changes where calls go. A key follows them: review it first.
`-max-age`	`720h`	Refuse a signed feed issued longer ago than this.
`-timeout`	`20s`	Give up fetching after this long.

providers missing lists a company’s own models with the provider’s key and prints the text models the price list cannot price. Listing models is free.

Flag	Default	What it does
`-provider`	required	The provider to check, as `lockpin providers` names it (`openai`, `anthropic`, `meta`, …).
`-base`	the catalog’s	The provider’s API base URL.

lockpin providers -models
lockpin providers update -dry-run
lockpin providers missing -provider openai

Reports and import#

`lockpin import`#

Reads what Anthropic, OpenAI and Cursor billed, from their admin APIs, and shows it by key or person and model, with outliers. Admin keys are read from ANTHROPIC_ADMIN_KEY, OPENAI_ADMIN_KEY and CURSOR_ADMIN_KEY. They are never written down, and nothing is sent anywhere. No agent has to go through Lockpin for this.

lockpin import [flags]

Flag	Default	What it does
`-all`	off	List every key or person and model, not the top 10 per provider.
`-days`	`30`	How many days back to read, 1 to 30.
`-emails`	off	Show people’s emails in full (they are masked by default).
`-json`	off	Print the report as JSON.
`-providers`	every provider whose admin key is set	Comma-separated: `anthropic`, `openai`, `cursor`.
`-tz`	`Local`	Time zone for the overnight rule, such as `America/New_York`.

lockpin import -days 7
lockpin import -providers anthropic -json

`lockpin reconcile`#

Compares a provider’s own usage export (CSV) with what Lockpin charged for the same days and models.

lockpin reconcile EXPORT.csv [flags]

Flag	Default	What it does
`-export`	none	The provider’s usage or cost CSV (or give it as the first argument).
`-format`	`auto`	Export layout: `auto` (detect from the header), `anthropic`, `openai` or `generic` (`date,model,input_tokens,output_tokens,cost_usd`).
`-columns`	none	Name the export’s columns yourself, such as `date=Date,model=Model,input=Input tokens,output=Output tokens,cost=Cost (USD)`. Add `,cents` when cost is in cents. Overrides `-format`.
`-from`, `-to`	the export’s first and last day	First and last day to compare, `YYYY-MM-DD`.
`-days`	none	Compare the last N days ending today instead of `-from` and `-to`.
`-provider`	the detected vendor, or all for a generic export	Compare only ledger charges for this provider.
`-tolerance`	`1`	Percent difference in the period total that still counts as agreement.
`-ledger`	`lockpin-ledger.jsonl`	Local ledger file.
`-json`	off	Print the report as JSON.

lockpin reconcile usage.csv -days 7

`lockpin waste-scan`#

Reads the Claude Code session logs on this machine and says what the calls in them cost at API list prices, and what Lockpin’s cache options would have saved. It needs no Lockpin running, makes no network call, and prints totals only, never what the logs say.

lockpin waste-scan [-days 30] [-details] [-dir DIR] [-skip TEXT]

Flag	Default	What it does
`-days`	`30`	Count the last this many days. `0` counts everything.
`-details`	off	Also show repeated and very large tool results, per tool, and the `-handoff` replay.
`-dir`	`~/.claude/projects`	Folder of Claude Code transcripts (`*.jsonl`).
`-skip`	none	Comma-separated text: skip transcripts whose path contains any of it.

lockpin waste-scan -days 7

`lockpin plan`#

Reads the Claude Code and Codex session logs on this machine and says where a subscription’s usage went: calls, tokens, cache share and API-equivalent dollars by window, model and session, and the window percentages Codex records. A proxy cannot cap a subscription; this shows where the usage went. It needs no Lockpin running, makes no network call, and prints totals only.

lockpin plan [-claude-dir DIR] [-codex-dir DIR] [-json]

Flag	Default	What it does
`-claude-dir`	Claude Code’s folder in your home folder	Folder of Claude Code transcripts.
`-codex-dir`	Codex’s folder in your home folder	Folder of Codex rollouts.
`-json`	off	Print JSON.

lockpin plan

`lockpin ledger`#

Checks the ledger and exports it. verify recomputes the chain of each ledger file and checks every signed checkpoint with the node’s public key. export writes the ledger as audit records or, with -format focus, as spend for a finance team’s FinOps tools. No prompt, response, key or alert text is in it. See Receipts, ledger and reports.

lockpin ledger verify [-key HEX] FILE...
lockpin ledger export [-format jsonl|csv] [-since T] [-until T] [-o FILE] FILE...
lockpin ledger export -format focus [-keys FILE] [-since T] [-until T] [-o FILE] FILE...
lockpin ledger export -follow DIR FILE

Flag	Default	What it does
`-key`	none	`verify`: the node’s public key in hex, as `lockpin keys seal` printed it.
`-format`	`jsonl`	`export`: `jsonl`, `csv` or `focus` (CSV in the FOCUS 1.4 Cost and Usage layout). The cost is Lockpin’s measurement at list price, not the provider’s invoice.
`-since`, `-until`	none	`export`: RFC 3339 or a `YYYY-MM-DD` day in UTC. `-until` is exclusive.
`-o`	standard output	`export`: the file to write.
`-keys`	none	`export -format focus`: the keys file, for the team of a key on lines that do not say it.
`-follow DIR`	none	`export`: keep writing the ledger, as it grows, to `DIR/lockpin-<source>.jsonl` for a log agent, until stopped.

verify prints verified N entries, or chain broken at entry N or signature failed at checkpoint N, and exits 1. Give it a copy of a live ledger.

lockpin ledger verify lockpin-ledger.jsonl
lockpin ledger export -format csv -since 2026-11-01 -o spend.csv lockpin-ledger.jsonl

Service and install#

`lockpin service`#

Keeps Lockpin running in the background: started when you sign in, started again when it stops on an error, with its output in one log file. Nothing here needs admin rights or sudo.

lockpin service install|uninstall|status|start|stop|restart [-args "FLAGS"] [-yes] [-dry-run]

System	What `install` writes	Log
Windows	A Scheduled Task named `Lockpin` for your user, run at sign-in and restarted on failure.	`%LOCALAPPDATA%\Lockpin\lockpin.log`
macOS	A LaunchAgent, `~/Library/LaunchAgents/dev.lockpin.plist`, with `RunAtLoad` and `KeepAlive`.	`~/Library/Logs/Lockpin/lockpin.log`
Linux	A systemd user unit, `~/.config/systemd/user/lockpin.service`, with `Restart=on-failure`. On a server over SSH, also run `loginctl enable-linger $USER`.	`journalctl --user -u lockpin`

Command	What it does
`install`	Write the definition, enable it and start it. An existing one is replaced, so run it again to change `-args`.
`uninstall`	Stop it and remove the definition.
`status`	Installed or not, running or not, its pid, and the log path.
`start`, `stop`, `restart`	Start, stop or restart it.

Flag	Default	What it does
`-args "FLAGS"`	the flags the last install saved	Flags for the proxy, stored in the definition, split on spaces. `-args ""` clears them.
`-no-start`	off	`install`: write and enable it, but do not start it now.
`-yes`	off	Write without asking.
`-dry-run`	off	Print what would be written and run, and change nothing.

lockpin service status
lockpin service install -args "-default-budget 5"

`lockpin hooks`#

Adds Lockpin’s checks to each agent’s own hook file, or takes them out. For each agent it prints the change as a diff and writes it only after you answer yes. Other hooks and settings in the file are kept, and the old file is copied to FILE.lockpin-backup-TIME first.

lockpin hooks install [-agent LIST] [-project] [-dir DIR] [-model ID] [-lint] [-guard] [-events] [-yes] [-dry-run]
lockpin hooks uninstall [-agent LIST] [-project] [-dir DIR] [-yes] [-dry-run]

Flag	Default	What it does
`-agent`	each agent whose folder is in your home folder	Comma-separated: `claude-code`, `codex`, `cursor`, `gemini`, `windsurf`.
`-project`	off	Change the project’s files in `-dir`, not your user files.
`-dir`	this folder	The project folder for `-project`.
`-model`	none	Model to price a session’s first prompt with, for example `claude-sonnet-5-5`.
`-lint`	off	Claude Code: also add `lockpin lint` (idle cache, large and repeated messages).
`-guard`	off	Claude Code: also add `lockpin guard`, which refuses a whole read of a huge file before it happens.
`-events`	off	Claude Code: also add `lockpin tool-event`, which tells drift tracking which files the agent wrote.
`-bin`	`lockpin`, or this program’s full path	The `lockpin` the hook runs.
`-yes`	off	Write without asking, for scripts.
`-dry-run`	off	Print the changes and write nothing.

The hooks call four commands, which you can also run yourself. lockpin hooks NAME -h prints each one’s flags:

Command	What it does
`lockpin hooks review -hook AGENT [-model ID] [-block-usd X] [-block-tokens N]`	Prices a prompt before it is sent and blocks one that holds a secret or whose fixes would save at least `-block-usd` (default `0.10`) this turn or `-block-tokens` (default `20000`) tokens. Add `lockpin:ok` to a prompt to send it anyway (a secret always blocks). Without `-hook`, it reads a prompt from `-file` or standard input and prints the review.
`lockpin hooks lint -hook claude [-block] [-large N] [-compact-at N] [-topic]`	Checks a prompt for repeats, size and topic changes. `-large` defaults to `8000` tokens and `-compact-at` to `100000`.
`lockpin hooks guard -hook claude-code [-tokens N] [-warn]`	Refuses a whole read of a file over `-tokens` (default `8000`) estimated tokens before it happens, with a reason the agent sees. `-warn` never refuses: it adds a note instead.
`lockpin hooks event -hook AGENT [-listen ADDR] [-task NAME]`	Tells the running Lockpin which file the agent touched, so drift tracking can tell the agent’s changes from yours.

The older names (lockpin hook install, lockpin review, lockpin lint, lockpin guard and lockpin tool-event) still work, so hooks installed by an earlier version keep running.

lockpin hooks install -dry-run
lockpin hooks install -agent claude-code -guard
lockpin hooks uninstall

`lockpin upgrade`#

Runs the one-line installer, which downloads the latest release (or -version), checks it against the release’s SHA256SUMS and replaces this program. It keeps how Lockpin was installed: the same folder, and whether it starts at login. A running Lockpin is restarted on the new version; a stopped one stays stopped. See Upgrade and uninstall.

lockpin upgrade [-version v0.3.0] [-dry-run]

Flag	Default	What it does
`-version`	the latest release	The release to install, such as `v0.3.0`.
`-dry-run`	off	Print the command it would run.

lockpin upgrade -dry-run
lockpin upgrade -version v0.3.0

`lockpin uninstall`#

Removes what the installer set up: the program, and what starts it at login (the LaunchAgent, the systemd user service, or the Windows shortcuts and PATH entry). Your spend history and settings stay unless you add -purge. It lists what it will do and asks first.

lockpin uninstall [-purge] [-yes] [-dry-run]

Flag	Default	What it does
`-purge`	off	Also delete your spend history and settings.
`-yes`	off	Do not ask first.
`-dry-run`	off	List what it would do and change nothing.

lockpin uninstall -dry-run

`lockpin version`#

Prints the version, commit and build date.

lockpin version

Advanced#

These commands measure what Lockpin’s own savings features do on your calls. They read local files only and send nothing. Most people never need them.

Command	What it does
`lockpin ab [-ledger FILE] [-days N] [-json]`	Reads the ledger of a Lockpin started with `-ab` (for example `-ab 'stabilize,compact=50%'`) and compares, per experiment, the treatment arm with the control arm: tasks, calls, spend, spend per call, cache-read share and tokens trimmed, with a 95% bootstrap interval on the difference in spend per call.
`lockpin replay [DIR] [-arms LIST] [-prices FILE] [-json] [-check FILE \| -update FILE]`	Replays recorded model calls (`lockpin -record DIR`) against local fakes that bill like the providers, with each savings feature on and off, and shows what each one saved or cost, call by call. `-check FILE` is a CI gate; `-update FILE` stores the accepted result.
`lockpin shapes -out DIR [-claude-logs] [-codex-logs] [-days 30]`	Writes one shape file per session of this machine’s Claude Code transcripts or Codex rollouts. A shape keeps the sizes and times of each call and nothing more: no prompt, reply, file or folder name. `lockpin shapes -check DIR` replays them and compares cache reads and writes with the logs.
`lockpin gaps [-check] [-json]`	Shows the gap tables Lockpin keeps from its ledger: how long agents pause before their next call, how many calls a task makes, and how often each provider dropped a cache early. `-check` compares the tables with the old rules; where the tables did at least as well, `-gap-tables auto` (the default) lets them decide, for 30 days.
`lockpin learn [-claude-logs] [-codex-logs] [-days 30]`	Trains two small pause models on this machine’s calls and keeps each only if it beats the gap tables on calls it did not learn from. They can then decide the 1-hour cache choice, where `lockpin gaps -check` also passed.

Run lockpin COMMAND -h for each one’s full flags.

Command reference#

Where the ledger is#

Command groups#

Everyday#

lockpin (run the proxy)#

lockpin init#

lockpin doctor#

lockpin connect and lockpin disconnect#

lockpin run#

lockpin pause, resume, stop and quit#

lockpin approve and lockpin deny#

lockpin receipt#

lockpin projects#

lockpin suggest#

lockpin digest#

lockpin alerts#

lockpin phone#

lockpin drift, goal, show and restore#

Keys and teams#

lockpin keys#

lockpin teams, workspace and invites#

lockpin enroll#

lockpin report#