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.

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.

Related pages

• Authenticating — the login gate this reference assumes throughout

• Skills Reference — which skills call which of these commands

• Troubleshooting