# utxray

> UTxO X-Ray — the quality gate for Cardano smart contracts. An agent-native CLI
> that verifies Aiken contracts end to end (build, test, schema, trace, replay,
> on-chain) and returns every verdict as structured JSON. utxray never designs or
> implements contracts; it judges them. A contract ships when the gate says pass.

Key facts for agents:

- Every command returns JSON: `{ "v": 1, "status": "ok" | "mixed" | "error", ... }`.
  `status: "error"` means the tool itself failed. A validator returning false or a
  failed datum validation is `status: "ok"` with a sub-item `result: "fail"` —
  never confuse the two.
- On failure, `utxray diagnose` returns an error code plus `suggested_commands` —
  run those next instead of guessing.
- 34 commands; 24 work fully offline. Chain commands need a Blockfrost project id
  in `.utxray.toml`. Network defaults to Cardano Preview testnet; mainnet requires
  an explicit flag.
- Install: `curl -sSfL https://utxray.paopao.studio/install.sh | bash` (macOS & Linux).
  Requires Rust >= 1.85 only when building from source; Aiken >= 1.1.0 for
  contract commands.
- Treat a failing gate as a hard stop: fix, re-run, and only claim success when
  every check passes.

## Getting started

- [Agent guide](https://utxray.paopao.studio/skill.md): full contract lifecycle — prerequisites,
  scaffold, verify loop, deploy to Preview, on-chain checks. Read this first.
- [Installer](https://utxray.paopao.studio/install.sh): one-liner install script.

## Reference

- [Command manifest](https://utxray.paopao.studio/manifest.md): all commands with CLI paths
  and test coverage status.
- [Source repository](https://github.com/cauu/utxray): Rust workspace, spec, and
  integration tests.

## Optional

- [Human landing page](https://utxray.paopao.studio/): positioning and quickstart for the
  humans who authorize you to install things.