---
title: "Cli"
description: Inspect the cache and ledger from the command line.
sidebar:
  order: 6
---

```package-install
npm i -g @runic-labs/cli
```

There's no `runic invoke`, no `runic install` — v1 doesn't execute or install anything. The CLI only reads the same file-backed state your agent process already writes to via `@runic-labs/sdk`.

## `runic cache status`

Lists cached signatures, hit counts, and last-used times.

```bash
$ runic cache status
a1b2c3d4e5f6  hits=3  tokensSpent=323  lastUsed=2026-08-21T22:40:11.203Z
9f8e7d6c5b4a  hits=0  tokensSpent=210  lastUsed=2026-08-21T22:39:58.771Z [stale]
```

If nothing has been cached yet, it prints `No cached decisions yet.` instead of an empty table.

## `runic ledger status`

Shows total tokens spent vs. saved, plus a per-signature hit breakdown.

```bash
$ runic ledger status
Total spent: 2582
Total saved: 12910
Cache hits:  40

Hits by signature:
  a1b2c3d4e5f6  5
  9f8e7d6c5b4a  3
```

## Pointing at a specific agent's state

The CLI reads from the same location `@runic-labs/sdk` writes to by default — `.runic/` in the current working directory, or `$RUNIC_HOME` if set. Run it from the same directory your agent runs from, or set `RUNIC_HOME` to match:

```bash
RUNIC_HOME=/var/lib/my-agent/runic runic ledger status
```

## Next

- [Ledger](/ledger) — what `summary()` actually computes under the hood
- [Benchmarks](/benchmarks) — reproduce a full spent/saved run yourself