CLI reference

Every ArkheionX command, grouped by how you use it.

Start at the top of the ladder and work down. Your installed checkout is the source of truth — run arkheionx --help to confirm what is available locally. All commands are local and static: no RPC, no live-chain calls, no exploit automation.

Command ladder

The path from install to review.

Run these in order. review-map is the canonical first command.

arkheionx version          # confirm the install
arkheionx doctor           # check environment + project
arkheionx review-map .     # build the review map
arkheionx value-paths .    # where value moves
arkheionx assumptions .    # what must stay true
arkheionx test-gap-map .   # what is untested (Source: file:line)
arkheionx proof-plan .     # a proof direction to try by hand

arkheionx version

arkheionx version

Purpose

Print the installed version and milestone metadata.

When to use

Run right after install to confirm the wrapper works.

Exit code

arkheionx doctor

arkheionx doctor

Purpose

Check the local environment, Python, Git, and project layout.

When to use

Run before relying on any generated review context.

Exit code

arkheionx review-map .

arkheionx review-map .

Purpose

Build the local review map: contracts, value paths, assumptions, test gaps, proof directions, and source evidence.

When to use

The canonical first command on a repo you are authorized to review.

Exit code

1 when review guidance is present (intentional), 0 when clean

arkheionx value-paths .

arkheionx value-paths .

Purpose

Focused view: where value enters, moves, and exits.

When to use

After review-map, to study the money-moving paths.

Exit code

1 with guidance, 0 clean

arkheionx assumptions .

arkheionx assumptions .

Purpose

Focused view: the trust conditions each value path depends on.

When to use

To decide which assumptions to confirm in code.

Exit code

1 with guidance, 0 clean

arkheionx test-gap-map .

arkheionx test-gap-map .

Purpose

Focused view: value-sensitive functions with missing tests, each with a Source: file:line.

When to use

To turn gaps into targeted local tests.

Exit code

1 with guidance, 0 clean

arkheionx proof-plan .

arkheionx proof-plan .

Purpose

Focused view: local Foundry proof-scaffold directions (planning only, never executed).

When to use

To outline a manual proof for a value-sensitive path.

Exit code

1 with guidance, 0 clean

Advanced / source-tree

Beyond the stable workflow.

These commands exist in the CLI but are not the canonical first run. The legacy scanner commands (scan, test-plan, search) run from a repository checkout and fail gracefully in a non-editable install, pointing you back to arkheionx review-map.

scan — Legacy pre-audit readiness scanner (source-tree checkout only).
test-plan — Generate defensive test plans from scanner JSON (source-tree only).
search — Search the local security-memory metadata (source-tree only).
open / map / flow / hunt — Orient, draw the protocol, build the money-flow graph, rank review surfaces.
prove / trace — Scaffold or summarize a local Foundry proof for a target (you run Foundry).
evidence / report — Assemble a local evidence package and a responsible report draft.
review-package / local-validate — Bundle reviewer-ready artifacts; ingest saved Foundry output (never runs forge).
evidence-status / validate-artifacts / evidence-links — Inspect and validate generated artifacts and their links.
validate-config / demo — Validate a local config; list, show, and copy bundled demo fixtures.

Research memory (v4.1)

AI-assisted review handoff.

These additive, local/static commands build on the review map: a focused agent brief, a hypothesis log (rejected findings are evidence), and a case-study generator. They write to .arkheionx/research/; hypotheses are review prompts, not findings. See research memory.

arkheionx agent-brief — An AI-agent-ready review brief: coverage weakness ranking, value movement, authorization surfaces, periphery/core flows, behavior-mismatch surfaces, and open hypotheses.
arkheionx hypothesis-log — A structured hypothesis log and rejected-finding memory. Every hypothesis starts open; a human records the test, result, and rejection/confirmation.
arkheionx case-study — A sanitized research-session report; --from incorporates a hypothesis log's statuses. No vulnerability claim unless independently confirmed.

Evidence graph (v6)

Classify the evidence; map the interactions.

These additive, local/static commands classify every important surface into an evidence state and map the dangerous interactions that still lack tests. An evidence state is not a vulnerability claim, interaction priority is not severity, and unresolved does not mean vulnerable. See the V6 overview.

arkheionx evidence-graph — Classify every important surface into an evidence state (tested, unresolved, needs-human-review, insufficient-evidence, ...) with an evidence strength and the missing-evidence gaps. An evidence state is not a vulnerability claim.
arkheionx interaction-matrix — Detect meaningful combinations of surfaces that may hide bugs when tested together, scored by a transparent interaction priority. Interaction priority is not severity.
arkheionx unresolved-map — Everything important that local evidence does not yet close: high-impact unresolved surfaces and interactions. Unresolved does not mean vulnerable.
arkheionx complete-review — Assemble the whole V6 review into one local, vendor-agnostic package for a human reviewer or an AI agent. Writes by default.

Scope-aware orchestration (v7)

Scope becomes lanes, tasks, evidence, and filters.

These additive, local/static commands accept an optional --scope-file and turn audit scope into review lanes, scope tasks, evidence requirements, and report filters. A scope task is a planning artifact, not a finding; evidence quality is not vulnerability validity; a report candidate is not final triage. See the V7 overview.

arkheionx scope-map — Parse a contest/audit/program scope note into structured review rules: trusted assumptions, known and accepted issues, invariants, focus areas, and do-not-waste-time filters.
arkheionx scope-lanes — Generate scope-aware review lanes from repository surfaces plus scope rules. Lane priority is review order, not severity.
arkheionx scope-tasks — Turn lanes into precise, bounded, evidence-oriented tasks. A task is a research instruction, not an exploit instruction.
arkheionx scope-pack — Bundle a complete local scope-aware research pack: scope map, lanes, tasks, evidence template and rubric, report-filter checklist, and agent input. Writes by default.
arkheionx evidence-judge — Grade whether local tests prove the intended task on a transparent rubric. Candidate-with-evidence is not a confirmed vulnerability.
arkheionx report-filter — Classify report candidates against scope rules before submission, with a human pre-submission checklist. Not final triage.

Exit codes

What the exit status means.

Success. For review commands, no review guidance was surfaced.

Review guidance is present. For review-map and the focused views this is intentional, not a crash — it means there is something to inspect.

Usage or input error (bad path, bad flags, missing source-tree helper).

—

No traceback is expected on the canonical path; source-tree-only commands print clear guidance when unavailable.

Output formats

Human, JSON, and artifacts.

Human

Default terminal output: ranked "inspect first" list, summary, and next commands.

--json

Structured payload for tooling: contracts, value paths, assumptions, test gaps, proof suggestions.

Artifacts

Written under .arkheionx/out/review-map/ (gitignored): Markdown review map, Test Gap Map, JSON views.

Source evidence

Each test gap prints a Source: <file>:<line> from the parsed source.

Which command should I run?

A short decision guide.

Just installed? arkheionx version then arkheionx doctor.
New repo to review? arkheionx review-map ..
Want to study money flow? arkheionx value-paths ..
Deciding what to test? arkheionx test-gap-map ..
Planning a manual proof? arkheionx proof-plan ..
Trying the bundled demo? arkheionx review-map examples/vault-strategy-oracle-fixture.

Safety

Command output is review context, not a verdict.

ArkheionX does not confirm vulnerabilities, assign final severity, or run exploits. Human review is required before reporting, disclosing, or making a security decision, and only on repositories you are authorized to review. Next: how it works · quickstart.