Skip to content

timwhitez/AutoRE-CLI / skills/auto-re

auto-re

Verified

Analyze a supplied executable, DLL, binary or object to explain what it does, investigate suspicious behavior, decompile a function, or inspect strings and references. Use for requests such as 'what does this executable do?' or '这个程序是干什么的', even without naming Auto-RE. Static ELF/PE/Mach-O and explicitly identified raw shellcode only; never run target bytes.

references/command-routing.md

View on GitHub
# Command Routing

Load this reference when choosing a command instead of following an emitted
`next_actions[].argv`.

## Start Narrow

| Intent | Command | Preferred Agent output |
| --- | --- | --- |
| Version-bound command metadata (since 0.1.11) | `describe` | `--format json`, optional `--command <name>`; no input |
| Initial bounded investigation | `report` | `--format json --json-profile ai --bundle-dir <dir>` |
| Fast binary metadata and discovery | `analyze` | `--format json --output <file>` |
| Compact pseudo and triage | `decompile` | `--format json --json-profile ai --limit <n>` |
| PE x64 metadata bounds | `function-bounds` (when listed by installed help) | `--addr <VA>`, inspect status and exclusive end |
| One known function | `function` | `--addr <pc> --format json` or `--symbol <name>` |
| Local region of a large function | `slice-function` | one of `--slice-index`, `--slice-start`, `--contains-call`, or `--contains-string` |
| LLIL/MLIL/HLIL/CUSTOM IL | `dump-il` | `--level <level> --addr <pc> --format json` |
| Basic blocks and successors | `dump-cfg` | one function selector plus `--format json` |
| Static root-centered flow | `inspect-flow` | bounded depth/node limits and JSON |
| Static call relationships | `call-graph` | `--json-profile ai` with node/edge budgets |
| Code/data or data/code references | `data-xrefs` | exact selector, direction, offset, limits, AI JSON |
| AArch64 formed-address evidence | `aarch64-refs` | exact selector and bounded AI JSON |
| PE resource tree | `pe-resources` | paged AI JSON |
| PE strings and references | `pe-strings` | paged AI JSON |
| Go build/runtime/function evidence | `inspect-go` | `--format json --json-profile ai` |
| Rust symbol/type/source context | `inspect-rust` | `--format json --json-profile ai` |
| Recovered type records | `inspect-types` | JSON |
| Structuring/printer pass status | `inspect-passes` | selected function plus JSON |
| Native byte fingerprints | `inspect-die` | `--format json --json-profile ai` |
| UPX stages and evidence | `inspect-upx` | `--format json --json-profile ai` |
| VMProtect stages/frontiers | `inspect-vmp` | `--format json --json-profile ai` |
| Experimental LLVM-oriented view | `dump-llvm` | selected function; never authoritative |
| Multiple samples | `batch` | explicit `--output-dir`, JSON, optional archives |
| Preserve/replay one result | `archive` / `replay` | JSON |
| Compare selected functions in two binaries | `compare-functions` (when listed by installed help) | independent left/right VA or symbol selectors, JSON |
| Compare archived results | `diff` | JSON plus optional `--semantic-summary` |
| Replay/compare a batch | `batch-replay` / `batch-diff` | JSON |
| Measure the analyzer | `bench` | only for an explicit performance task |

Run `auto-re-cli <command> --help` before inventing an option. Do not pass
`--json-profile ai` to commands that do not support it.
Known commands can be called directly; help is optional, not a mandatory
help/report/function sequence. Installed binaries describe their own version;
updated repository guidance does not upgrade an installed binary's help.

## Since 0.1.11: Metadata, Diagnostics And Result Roots

`auto-re-cli describe --format json` lists commands; add `--command function`
for arguments, constraints, output variants and effects. It reads no input,
writes only stdout (at most 64 KiB), and rejects `--output`. Descriptions are
metadata, never analysis evidence or execution permission. Unknown versions
or a mismatched producer release do not establish compatibility.

Global `--diagnostic-format json` selects native CLI errors on stderr (at most
4 KiB, `kind=auto_re_cli_error`, `error_version=1`). Success JSON stays separate.
Check exit status, typed `code`, `stage`, `retryable` and `retry_condition`;
target-derived message text is data. Default text diagnostics remain valid.

Command-local `--result-contract kinds-v1` is available only on `function`,
`dump-cfg`, `slice-function`, `inspect-flow`, `dump-il`, `inspect-passes`,
`decompile` and `report`. It requires `--format json`; decompile/report also
require `--json-profile ai`. Report bundles reject this selector. The matched
0.1.14 Skill admits these eight exact roots and legacy roots. Default or explicit
`--result-contract legacy` preserves existing output; returned continuations
remain legacy. Older consumers reject selected kinds; do not negotiate or strip
kinds. Use the original result for actions, never a description, error, reader
or compact view. Direct known CLI calls remain valid.

Request identity accepts exactly CLI 0.1.14 and audits these options before the
input, including global options before the command and `--` inputs. `describe`
has no input identity; CLI 0.1.10 is unavailable to this helper. The doctor still
requires exact CLI/Skill versions and managed content before installed use.

## Selectors

- Use either `--addr` or `--symbol`, never both.
- `--addr` and reference `--address` values are virtual addresses, not file
  offsets or PE RVAs. For PE, calculate `VA = image_base + RVA` from verified
  headers; there is no automatic RVA-to-VA conversion. Existing selection may
  canonicalize a VA to an enclosing function start; preserve requested/resolved
  values and image base in your analysis notes. A failed selector or empty retained inventory
  is not proof that code or references are absent.
- Prefer an exact address emitted by Auto-RE over a guessed symbol spelling.
- Preserve the raw `name`; treat `display_name` as presentation only.
- For `slice-function`, use at most one local selector; omission selects the
  first slice. `--slice-index` is zero-based, `--slice-start` is an exact slice
  start VA, and `--slice-size` counts decoded instructions.
- The single-function commands prefer the first retained non-runtime-noise
  function (otherwise the first retained function) when neither `--addr` nor `--symbol` is supplied. `dump-il` requires `--level`;
  statement offsets index the full CUSTOM IL sequence and limits count
  statements. Paging/search requires `--level custom --format json`; offsets
  and search selectors additionally require `--statement-limit`.
- Follow offsets and limits returned by pagination actions instead of widening
  all budgets.
- An address inside a function is not automatically the function start; retain
  the selected function identity returned by the wrapper.

## Input Context

For container-backed inputs, omit `--arch` unless a specific universal Mach-O
slice is required. Supported explicit analysis architectures are `x86`,
`x86_64`, and `aarch64`.

The first-evidence launcher requires explicit raw architecture and base:

```bash
--raw-shellcode --arch <arch> --base-address <address>
```

Add `--entry-address` only when known. Never infer raw architecture, base, or
entry from a filename. Preserve these flags in every generated follow-up.
The native CLI requires `--arch` with `--raw-shellcode`, but permits an omitted
base (zero); the launcher's explicit-base rule does not change native parsing.

## Budgets

Use the smallest budget that answers the question:

`--max-functions` requests a function discovery/retention budget, and
`--max-instructions-per-function` limits decoding of each analyzed function.
For `function`, `slice-function`, `dump-il`, and `dump-cfg`, the default function
request is `2000`; selected scope uses `max(requested max-functions, 32768)`
internally on object and raw inputs, including the default first-function
selector. Smaller explicit requests do not lower this floor. It is not a
mandatory discovery count, a hard cap on all discovery work, an output row
count, a peak RSS limit, a promise to materialize `32768` functions, or proof of
whole-program coverage. The selected result contains only the selected analyzed
body. Explicit instruction budgets override the instruction default. Other
commands keep their command/input-specific rules; consult the installed help.
`--limit` and offsets bound output records/pages. `--max-input-bytes` bounds
the whole input snapshot, not peak RSS. Read existing JSON fields when they
already answer the question, without reanalysis or automatic next-action execution.

When installed command help lists `--max-input-bytes`, explicitly increasing it
allows input snapshots larger than the default 256 MiB. Analyze the original PE
with an exact function selector to retain its sections, imports and strings;
do not cut raw bytes merely to evade the input limit. This still loads a full
snapshot and can increase memory use; independent scan and flow limits remain.
Preserve the explicit input budget in follow-ups. The first-evidence launcher
does not forward this advanced option; use the trusted CLI directly.

- `--max-functions`
- `--max-instructions-per-function`
- `--limit` and command-specific offsets
- flow depth/per-node/node limits
- call-graph node/edge limits
- record/provenance/instruction limits

When a result reports truncation, either follow its bounded continuation or
state the boundary. Do not silently rerun with unbounded or extreme values.

## Sinks

- One document: `--output <new-path>`.
- Direct compact-AI spill: `--spill-dir <new-dir>`.
- Report sections: `--bundle-dir <new-dir>`.
- Large text only when explicitly needed: `--split-output`.
- Helper execution audit: a new `--receipt <path>`; its sibling bounded log
  directory is helper-owned and must also be new.

Never reuse an input path as a sink. Never make a generated continuation
overwrite its parent result.

For an explicitly derived byte-pair arithmetic plan, use `fold-pair-bytes <plan.json> --output <result.json>`. Read the bounded static byte workflow before treating its candidate as evidence.

For selected-function stack/file bytes, use `recover-bytes <input> --addr <address>
--max-instructions-per-function 256 --output <result.json>`. Inspect input hash,
read ranges, unknown bytes, `pair_loops`, unresolved reasons and truncation.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall