hero attest
Shows and checks the record Ekamyth Agent OS keeps on your machine of what your agents did. The record is a hash-chained list of decisions, and it holds no prompt or response text.
What hero attest does
It answers one question: is the record of what my agents did intact, and what does it hold? Agent OS adds an entry to the record for each decision it records, such as a model call through the model gateway or a tool call at the hook. Each entry carries a hash that covers the entry before it, so an entry changed after it was written breaks the chain at that point, and hero attest verify reports it.
- Use it when you want to check that the record wasn't changed, see how many decisions it holds and how many were refusals, count each of your rules' receipts in the record, or export the decisions to a CSV or JSON file.
- Use something else when you want what one session did step by step (
hero trace), whether each job finished and was checked (hero verdict), what was refused or held and why (hero govern), or what left your machine (hero privacy). - Alias: none.
reportis a retained name forstatus. - Reads or changes:
status,list,verify,rulesanddescriberead only.export --out <path>writes the file you name. Data reads can send a content-free usage beacon; see Files and environment.
Limit: the record is not anchored to an independent witness. The product says so on every passing check: Proof level: local chain, not anchored. No witness holds its roots, so a rewrite of the whole chain and its head record cannot be detected on this machine. See Limits.
Synopsis for hero attest
hero attest [status] [--json | --details] [--only <value>] [--since <time>] [--all]
hero attest list [--json | --details] [--only <value>] [--since <time>] [--all]
hero attest verify
hero attest rules [--json]
hero attest export [--format csv | json] [--out <path>] [--since <date>]
hero attest describe [--json]
hero attest help | --help
Run with no subcommand, it behaves as status. hero attest report is the same as status. hero help attest prints the same help page.
Subcommands of hero attest
| Subcommand | What it does | Reads or changes |
|---|---|---|
status | The record's verdict, how many entries it holds and how many were refusals, how strong its proof is, and recent jobs. This is the default. | Reads |
list | The record's entries as readable rows. The help page describes it as chain segments, one per line. Each row shows how long ago the entry was made (such as 14m ago), a label for the entry, its status, local only, a dash, and the entry's number in the record (such as #89). It shows the newest 20 rows, then a line such as 70 older · use --since or --all. With no record, it prints (no objects in window). | Reads |
verify | Checks the full record: the live chain and every archived segment, one line each, then one verdict for the whole record and its proof level. | Reads |
rules | For each of your rules, how many receipts it has, with references into the record. It also shows whether rule enforcement is switched on, and prints this even when the record is empty. | Reads |
export | Writes the decisions in the record as CSV or JSON, with no content. It writes nothing unless the record passes the same check verify runs, and it refuses the whole export if any entry holds a private field, such as prompt text or a credential. | Writes the file you name, or prints to the terminal |
describe | The command's own descriptor. Reads none of your data and sends no beacon. | Reads |
help | This command's help. Same as --help and hero help attest. | Reads |
Arguments for hero attest
Arguments for status and list
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
--json | Flag | No | Off | None | Machine-readable output with data and envelope. |
--details | Flag | No | Off | None | Shows every shared number as numerator/denominator, with the reasons a figure is partial. |
--only <value> | Text | No | Off | violations, blocked, failed, or a model name | Filters the rows. Text view only. |
--since <value> | Time | No | Everything the record holds | A UTC instant, <n>h, <n>d or today, up to 30 days ago | Shows rows from that time on. Text view only. |
--all | Flag | No | Off, newest 20 | None | Shows every row, not just the newest 20. Text view only. |
Arguments for export
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
--format <format> | Choice | No | csv | csv, json | The file format. --format=json also works. |
--out <path> | File path | No | None: the export prints to the terminal | Any path you can write | Writes the export to this file and prints how many decisions it wrote. --out=<path> also works. |
--since <date> | Date or time | No | Every decision | YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS, "YYYY-MM-DD HH:MM:SS", or Unix seconds | Exports decisions from that time on. A decision with no timestamp is always kept, so it is never dropped from an export. |
Arguments for rules
| Argument | Type | Required | Default | Allowed values | What it does |
|---|---|---|---|---|---|
--json | Flag | No | Off | None | Prints the per-rule counts and the enforcement state as JSON. |
Arguments for verify
None.
How hero attest gets its answer
Agent OS writes the record on your machine as your agents work. Each entry holds metadata only, such as the tool name, the hook event and the decision for a tool call, or the provider, model, status and cost for a model call. It never holds prompts, responses, tool inputs or tool outputs. Entries come from model calls through the model gateway, tool calls at the hook, approvals, policy changes, verdict records and other decisions.
Each entry's hash covers the entry before it. When the record grows, older entries move to archived segments, and verify checks every segment as well as the live chain. status and export run the same check before they report or write anything.
What leaves your machine: nothing from the record, by default. hero privacy lists a flow named attest-anchor, which would send a batch's hash and counts to a witness; it is off on this build. Data reads can send the usage beacon, which holds no content.
If writing an entry fails, for example because another writer holds the record for too long, the entry is skipped, counted, and reported on the terminal's error output. The tool call or model call still goes ahead. See Limits.
Get started with hero attest
Before you start: Agent OS is installed, hero setup has run, and your agent has made at least one model call or tool call since. These commands work the same on Mac and Linux.
See the record's state.
hero attestYou should see the record's verdict, its entry count and its proof level. Before any decision is recorded, it says there is no record and names one step:
Run: hero run <agent>.Check the whole record.
hero attest verifyYou should see one line per segment marked
✓, thenlineage VERIFIED ✓with the count of live entries and archived segments, then the proof level. It exits0. With no record, it printsno attest chain yetand the path where decisions are recorded, and exits0.Export the decisions to a file.
This command will:
- write
attest-export.csvin the current folder, or replace it if it exists; - change nothing in the record.
hero attest export --format csv --out attest-export.csvYou should see
exported <n> decision(s) → attest-export.csv (csv, content-free). To undo, delete the file:rm attest-export.csv.- write
Example output of hero attest
Output from version 0.1.36rc13 on a demo home; the numbers are examples. Trimmed where you see …
Attest · all retained
…
Proof level: local chain, not anchored. No witness holds its roots, so a
rewrite of the whole chain and its head record cannot be detected on this
machine.
results: hero verdict · replay a job: hero trace show <job> · prove it: hero
attest verify · audit file: hero attest export
How to read hero attest output
The status screen
| Line | What it means | What to do |
|---|---|---|
| Title | Attest and the window it covers. With no --since, it covers everything the record holds. | Use --since for a shorter window. |
| Headline | Starts Proof intact ✓ when every byte of the record checks, with the number of records. Otherwise it starts Proof followed by the verdict, such as BROKEN ✗. See Verdicts. | If it isn't intact, run hero attest verify, which the screen names. |
| Proof level | How strong a passing check is. On this build it reads Proof level: local chain, not anchored, with the limit. | See Limits. |
| Recent jobs | The newest 20 jobs in the record, or every job with --all, filtered by --only and --since. The screen also shows how many records aren't linked to a job, only when other records in the window are linked to jobs. A record with no job id is still in the record; it just can't be shown as a named job, and nothing needs doing about that. A failed check is a separate matter: see Verdicts. | Replay one with hero trace show <job>. |
| Footer | The next commands: results: hero verdict, replay a job: hero trace show <job>, prove it: hero attest verify and audit file: hero attest export. | Run the one you need. |
Verdicts from verify and status
| Verdict | What it means | Exit code | What to do |
|---|---|---|---|
VERIFIED ✓ | Every segment checks, and new entries are being accepted. | 0 | Nothing. |
AT RISK | Every byte checks, but the record has stopped accepting new entries, so decisions are not being recorded. | 1 | Email support at the address in your welcome email. |
BROKEN ✗ | An entry was changed after it was written. The line says whether the change is in an archived segment or in the live chain. | 1 | Read the verdict line: it says whether the change is in an archived segment or in the live chain. Keep the affected record and the files beside it as they are, run hero attest verify, and don't treat the changed history as verified. |
MISSING ✗ | The record's file was deleted, while the files beside it show it existed. A deleted record never reads as a fresh install. | 1 | Restore the file from a backup, then run hero attest verify. The verdict line says so. |
UNREADABLE ✗ | A segment couldn't be read, for example because of its permissions. This is not evidence of a change. | 1 | Fix the file's permissions, then run hero attest verify again. |
CORRUPT ✗ | A segment is damaged and couldn't be parsed, for example after a crash mid-write. This is not evidence of a change. | 1 | Email support at the address in your welcome email. |
In verify, each segment line shows ✓ or ✗, the segment's file name and its entry count. A ✗ line names the problem, and says when the segment is an archived one.
Columns of an export
| Column | What it holds |
|---|---|
seq | The entry's position in the record. |
ts | When the decision was made, in Unix seconds. Empty when the entry has none. |
surface | Where the decision came from, such as model_proxy for a model call through the model gateway, tool_hook for a tool call at the hook, approval, policy or verdict_record. |
provider, model | For a model call, the provider and the model. Empty otherwise. |
action | What was decided on, such as the rule, the decision or the event. Empty when the entry has none. |
allowed | false for a refusal, true otherwise. The same test gives the refusal count on the status screen. |
status, cost, latency_ms | The call's status, its cost and how long it took, where the entry records them. |
crit | How much the decision matters: 1 is routine, and 3 or above flags a high-impact decision. An entry with no value exports as 1. |
leaf, chain | The entry's own hash, and the hash that links it to the entry before. |
prev | The chain hash of the entry before, so the export can be checked away from your machine. |
data_origin | simulated for an entry made from simulated data. Empty otherwise. |
record_json | The entry exactly as it was written to the record, so its hash can be checked again. An export is refused, not shortened, if any entry holds a private field. |
record_redacted | Always false. |
More hero attest examples
Example 1. To see each of your rules' receipts
hero attest rules
This lists each of your rules with how many receipts it has and references into the record, then the enforcement state. A rule with no receipt isn't listed here; hero codify coverage shows those.
Example 2. To export one week of decisions as JSON
hero attest export --format json --out attest-week.json --since 2026-11-01
This writes a JSON list, one object per decision, with the columns above, and prints exported <n> decision(s) since 2026-11-01 → attest-week.json (json, content-free).
Example 3. To pipe the export into another tool
hero attest export --format csv | head -5
With no --out, the export prints to the terminal, header line first.
Example 4. To use the record's state in a script
hero attest --json
Its data holds chain_present, chain_verdict, entries, denials, segments (each with file, entries and ok), proof, receipts, jobs, records_without_job, headline and next_step.
Exit codes and errors for hero attest
| Code | Meaning for this command | Cause | What to do |
|---|---|---|---|
0 | A positive verdict, or output that asserts none | The record verifies, there is no record, or an export was written. | Nothing. |
1 | A truthful negative result | Any verdict other than VERIFIED. Also returned by export for a bad argument and for a refused export. | Read the verdict line, or the error below. |
2 | Refused | An unknown flag or subcommand, a missing argument, or an unavailable source. | Run hero attest --help. |
3 | A source it needs is unavailable while it runs | A source it reads wasn't available. | Email support at the address in your welcome email. |
| Error | Cause | Fix |
|---|---|---|
hero attest export: unknown argument '<arg>' | export was given something other than --format, --out or --since. Exit 1. | Check the synopsis. |
hero attest export: --format must be csv or json (got '<value>') | Another format was named. Exit 1. | Use csv or json. |
hero attest export: --since must be YYYY-MM-DD, an ISO datetime, or a unix timestamp (got '<value>') | --since isn't a form export reads. Exit 1. | Use one of the forms in Arguments for export. |
hero attest export: refused — lineage <verdict>, then nothing was exported; an audit export is only written from a chain that verifies — run: hero attest verify | The record doesn't pass verify, including AT RISK. Nothing is written. | Run hero attest verify and act on its verdict. |
hero attest export: refused — sealed record contains private content; no verifiable redacted export is available | An entry in the record holds a private field, such as prompt text or a credential. An export can't leave it out and still be checked, so nothing is written. Exit 1. | Check the record on this machine with hero attest verify. |
Files and environment for hero attest
| Name | Kind | Purpose |
|---|---|---|
The file you name with --out | File, written by export | The export. It holds decision metadata only. |
HERO_HOME | Environment variable | Root of Agent OS's files on your machine, where the record is kept. Default ~/.hero. |
HERO_BEACON=off | Environment variable | Data reads can send the usage beacon. Usage reporting is on by default. It sends metadata only — never content, prompts or responses — at most once a day. Turn it off with HERO_BEACON=off. |
Limits of hero attest
| Limit | Behaviour | Can you change it? | What to do |
|---|---|---|---|
| No independent witness | The record is checked on your machine only. A rewrite of the whole record together with its head record passes every local check, so it can't be detected here. The proof level line says this on every passing check. | No | Keep a separate, access-controlled copy of the record, its archived segments and the files beside it, using your own backup tooling. An export is a report of chosen fields, not a replacement for them. The attest-anchor flow, which would send a batch's hash and counts to a witness, is off on this build. |
| Export where Codex has run | hero attest export can refuse on a machine where Codex has run. | No | hero attest verify still checks the record. |
| An entry can be skipped | If an entry can't be written in time, it is skipped and counted, and the terminal's error output says hero attest: chain append skipped. The call goes ahead. A failed write never stops your agent. | No | Look for hero attest: chain append skipped in the terminal's error output. |
| Block counts elsewhere | Governance block counts can read differently on Monitor, the Portal and other commands. | No | Trust hero attest rules. |
| Export needs a passing record | Any verdict other than VERIFIED refuses the export, and nothing is written. So does an entry that holds a private field. | No | Run hero attest verify first. |
| Filters | --only, --since and --all work on the text view only. --since goes back 30 days at most. | No | For older decisions, use hero attest export --since <date>. |
| Repair steps | For AT RISK and for a damaged record, the verdict line names an internal module, not a hero command. | No | Email support at the address in your welcome email. |
Commands related to hero attest
Checked against Agent OS 0.1.36rc14 (build 599c5e120c18) on 17 Nov 2026.