> For the complete documentation index, see [llms.txt](https://docs.loci-dev.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.loci-dev.net/loci-plugin-for-ai-coding-assistants/loci-claude-plugin/cli-reference-for-loci-claude-plugin.md). # CLI Reference for LOCI Claude Plugin This is the `loci` command — the analysis engine the plugin's skills call (PyPI package `loci-tools`). **This is not the same tool as the site's general "CLI" section** (that documents `loci_api`, a separate, older manual-upload tool with commands like `list-projects` and `upload`). If you're using the Claude Code plugin, this page is the one that applies. ### Installation Installed automatically by the plugin at session start. To install or verify manually: ``` uv tool install loci-tools loci --version loci doctor ``` ### Global behavior Every `loci` command prints one self-describing JSON document to stdout: `{"ok": true, "data": {...}}` on success, `{"ok": false, "error": {"message": "...", "code": "..."}}` on failure. Diagnostic/progress logs go to stderr, never stdout. The `-f`/`--format` flag controls the envelope's serialization: `json` (default), `yaml`, `csv`, `tsv`, `md`, or `toon`. **Login gate:** every command below requires a signed-in session *except* `login`, `logout`, `auth status`, and `doctor`. Two stable error codes to branch on: `auth_required` (exit 3 — not signed in / token expired) and `quota_exceeded` (exit 4 — plan limit reached). ### auth | Command | Flags | Notes | | ------------------ | ----------------------------------------------------------------------- | ------------------------------------------------ | | `loci login` | `--auth-server URL`, `--scope SCOPE`, `--timeout SECONDS` (default 120) | Browser PKCE sign-in. Public (works signed out). | | `loci logout` | — | Removes stored credential. Public. | | `loci auth status` | — | Shows `signed_in`/expiry. Public. | ### elf — local binary analysis (no model call) All subcommands take `--arch` except `memmap`, which auto-detects from the ELF. `--arch` accepts the 4 canonical targets (`aarch64`, `armv7e-m`, `armv6-m`, `tc399`) plus common aliases (e.g. `cortex-m4`, `cortex-m0+`, `arm64`, `armv8-a`). | Command | Key flags | What it returns | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `loci elf asm` | `--elf` (required), `--arch`, `--functions f1,f2`, `--out-dir`, `--blocks` | Assembly, control-flow graph, and timing CSV for named functions (or all, if omitted). Bulky output goes to files; envelope carries paths. | | `loci elf cfg` | `--elf` (required), `--arch`, `--functions` | Annotated control-flow graph, written to `control-flow.txt`. | | `loci elf symbols` | `--elf` (required), `--arch`, `--inline-threshold N` (default 200), `--payload-format` | Symbol table — inline in the response when ≤ N symbols, else spilled to a file. | | `loci elf diff` | `--elf`, `--comparing-elf` (both required), `--arch` | Which functions were added/modified/removed between two binaries. | | `loci elf stack` | `--elf` or `--asm` (one required), `--arch`, `--entry-functions`, `--stack-budget BYTES`, `--threshold PCT` (default 50), `--max-recursion-depth` (default 1), `--unknown-callee-size` (default 64) | Worst-case stack depth via call-graph traversal; pass/fail verdict when `--stack-budget` is given. | | `loci elf memmap` | `--elf` (required, **no `--arch`**), `--comparing-elf`, `--map-file`, `--top-n` (default 10), `--with-heap`, `--allocators-file` | ROM/RAM section breakdown, top consumers, optional region budgets and heap-allocation analysis. | | `loci elf slice` | `--elf` (required), `--arch`, `--output-types` (default `asm,symbols`), `--filter-functions` | Lower-level extraction primitive underlying `asm`/`symbols` — asm, symbols, blocks, segments, callgraph, or elfinfo. | ### build - compile sources and track how they were built | Command | Key flags | What it does | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `loci build compile` | `--source` (required), `--loci-target` (required; one of the 4 targets), `--context`, `--compiler-path`, `--project-root`, `--output`, `--meta-prev`, `--phase preflight\|post-edit`, `--verbose` | Compiles a C/C++/Rust source, auto-discovering compiler + flags (from `compile_commands.json`, a Makefile dry-run, DWARF in nearby objects, or defaults). Writes a `.o` + `.meta.json` sidecar. | | `loci build diff` | `--prev`, `--curr` (both required), `--verbose` | Compares two `.meta.json` records — informational only; a mismatch is a finding (`data.match: false`), never an error. | | `loci build print` | `--meta` (required), `--verbose` | Shows the build settings recorded for a compiled source. | | `loci build snapshot` | `--source` (required), `--project-root` | Freezes a source's `.o` + `.meta.json` as `.o.prev` before an edit, so `post-edit` can diff against it. | ### contract - author and inspect the Contract Envelope | Command | Key flags | What it does | | --------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `loci contract show` | — | Prints the current contract: entries, indices, enabled/disabled counts. Public. | | `loci contract lint` | `--draft` | Validates the (draft) contract for structural problems. Public. | | `loci contract draft add` | reads entry JSON from stdin | Stages one or more new entries as a draft. Public. | | `loci contract draft show` / `clear` | — | Views or discards the pending draft. Public. | | `loci contract draft edit / disable / enable` | `--index N` | Modifies one drafted entry by index. Public. | | `loci contract accept` | — | Writes the accepted draft to `.loci/contract.yaml`, unstaged. **User-run only** — the plugin's hooks block Claude from calling this itself. | | | | | All `contract` commands work signed out. `accept`, `init`, and a bare `edit`/`disable`/`enable` outside a draft are denied to Claude by a hook - authorship of a requirement belongs to the repo owner, not the agent. ### timing | Command | Key flags | Notes | | ------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `loci timing` | `--csv-text` or `--csv-file` (one required), `--architecture` (required) | Sends a per-block timing CSV (produced by `loci elf asm`) to the LOCI backend; returns predicted `execution_time_ns`, `std_dev_ns`, `energy_ws` per block. Requires sign-in. | ### usage | Command | What it does | | ------------ | --------------------------------------------------------------------- | | `loci usage` | Your plan, daily/weekly quota, and usage dashboard. Requires sign-in. | ### stats / trends | Command | Key flags | What it does | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `loci trends` | `--context-file`, `--function NAME` | Alias for `loci stats trend`. Measurement history for one or all tracked functions on the current branch. | | `loci stats trend-line` | `--function f1,f2` (required), `--context-file` | Compact recent-values line per function. | | `loci stats summary` | `--context-file` | One-line summary of this branch's recorded activity. | | `loci stats global-summary` | — | Summary across all your projects since first use. | | `loci stats record` | `--skill` (required), `--functions N`, `--mcp-calls N`, `--co-reasoning N`, `--verdict TEXT`, `--gates JSON`, `--commit SHA`, `--context-file` | Records a completed skill run (called by the skills themselves, not typically by hand). | | `loci stats measure` | `--skill` (required), `--function` or `--stdin`, `--worst-ns`, `--happy-ns`, `--energy-uws`, `--stack-bytes`, `--rom-bytes`, `--heap-sites`, `--heap-static-b`, `--commit`, `--source` | Records per-function measurements (called by the skills themselves). | ### doctor | Command | What it does | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `loci doctor` | Read-only environment diagnostics — Python version, analysis-stack imports, `c++filt`, credential store, sign-in state, state-directory writability. Public (works signed out); mutates nothing. | ### cockpit - live local dashboard `loci cockpit` is a live terminal view of this machine's LOCI data - no browser, no sign-in required. It reads the same measurement store the skills write to, so what it shows is what your sessions have actually reported. | Flag | Effect | | ------------------------ | --------------------------------------------------------------------- | | *(none)* | Opens the live TUI | | `--once` | Emits one snapshot as a JSON envelope instead of the interactive view | | `--altitude contract` | Opens directly on the contract panel | | `--catches-only` | Filters the event feed to non-OK verdicts only | | `--project` / `--branch` | Select what to look at; both default to the most recent | | View | Shows | | ------------ | --------------------------------------------------------------------------------- | | `hotspots` | Functions costing the most time, energy, and stack on this branch | | `prevented` | Regressions caught before they merged | | `time-saved` | Analysis time LOCI spent vs. the runtime measurement it replaced | | `contract` | Every bound in `.loci/contract.yaml` and the latest measurement judged against it | Public - works fully signed out, same as `doctor`. ### Related pages * [Authenticating](/loci-plugin-for-ai-coding-assistants/loci-claude-plugin/authenticating-loci-claude-plugin.md) — the login gate this reference assumes throughout * [Skills Reference](/loci-plugin-for-ai-coding-assistants/loci-claude-plugin/skills-reference-for-loci-claude-plugin.md) — which skills call which of these commands * [Troubleshooting](/loci-plugin-for-ai-coding-assistants/loci-claude-plugin/troubleshooting.md)