cq - CBOR Query Tool for Cardano

Think "jq for Cardano CBOR" - A fast CLI tool to inspect and query Cardano transactions encoded in CBOR format.

Born from a real pain point in the 2025 Cardano Developer Survey: developers lack good CLI tooling for debugging CBOR transactions. cq fills that gap.

Features

• Parse transactions from file, hex string, or stdin
• Query with dot-notation - cq outputs.0.address tx.cbor
• Wildcard support - cq outputs.*.value tx.cbor
• Filter queries - cq 'outputs[value.coin > 1000000]' tx.cbor
• Plutus data decoding - Datums and redeemers decoded to JSON
• Address decoding - cq addr <bech32> decodes any Cardano address
• CIP metadata standards - CIP-20 messages, CIP-25 NFTs, CIP-68 datum metadata
• Asset name decoding - Token names display as UTF-8 when valid
• Bech32 addresses - Auto-formatted for readability
• Pretty terminal output - Colors, tables, smart truncation
• JSON output - Perfect for piping to jq
• Babbage + Conway eras - Full support including governance
• Blazing fast - Native Rust, no WASM overhead

Installation

From crates.io (recommended)

cargo install cq

Pre-built binaries

# Linux/macOS
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/karkigrishmin/cq/releases/latest/download/cq-installer.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -c "irm https://github.com/karkigrishmin/cq/releases/latest/download/cq-installer.ps1 | iex"

Or download directly from GitHub Releases.

Upgrading

To upgrade to the latest version:

Check for updates

cq update

Upgrade via cargo

cargo install cq --force

Pre-built binaries

Re-run the installer script - it always fetches the latest version:

# Linux/macOS
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/karkigrishmin/cq/releases/latest/download/cq-installer.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -c "irm https://github.com/karkigrishmin/cq/releases/latest/download/cq-installer.ps1 | iex"

From source

cargo install --git https://github.com/karkigrishmin/cq

Quick Start

# Show full transaction (pretty output)
cq transaction.cbor

# Query specific fields
cq fee tx.cbor                    # Transaction fee
cq fee tx.cbor --ada              # Fee in ADA (not lovelace)
cq hash tx.cbor                   # Transaction hash

# Nested queries
cq outputs.0.address tx.cbor      # First output address
cq outputs.0.value.coin tx.cbor   # First output ADA amount
cq inputs.0.transaction_id tx.cbor

# Wildcard queries
cq outputs.*.address tx.cbor      # All output addresses
cq outputs.*.value tx.cbor        # All output values

# Different output formats
cq tx.cbor --json                 # JSON output
cq tx.cbor --raw                  # CBOR diagnostic notation

# Validation mode
cq tx.cbor --check && echo "Valid!"

# Read from stdin
cat tx.cbor | cq
cat tx.cbor | cq fee --ada

# Hex input (with or without 0x prefix)
cq 84a400818258203b40265111d8bb3c3c...
cq 0x84a400818258203b40265111d8bb3c3c...

# Filter queries (v0.2.0+)
cq 'outputs[value.coin > 1000000]' tx.cbor        # Outputs > 1 ADA
cq 'outputs[address.address ~ "addr1"]' tx.cbor   # Mainnet outputs
cq 'outputs[datum != null]' tx.cbor               # Outputs with datum

# Datum queries - decode Plutus data (v0.3.0+)
cq 'outputs.0.datum.value' tx.cbor --json         # Decoded datum structure
cq 'outputs.0.datum.value.constructor' tx.cbor    # Constructor index
cq 'outputs.0.datum.value.fields.0.int' tx.cbor   # First field (integer)
cq 'outputs.0.datum.value.fields.1.bytes' tx.cbor # Second field (bytes)

# Redeemer queries (v0.3.0+)
cq redeemers tx.cbor --json                       # All redeemers with decoded data
cq 'redeemers.0.purpose' tx.cbor                  # Redeemer purpose (spend/mint/etc)
cq 'redeemers.0.data' tx.cbor --json              # Decoded redeemer data
cq 'redeemers.0.ex_units' tx.cbor --json          # Execution units (mem/steps)

# Reference inputs (CIP-31, v0.3.0+)
cq reference_inputs tx.cbor --json                # Reference inputs (read-only)

# Decode any address (v0.2.0+)
cq addr addr1qy8ac7qqy0vtulyl7wntmsxc6wex80gvcyjy33qffrhm7sh927ysx5sftuw0dlft05dz3c7revpf7jx0xnlcjz3g69mq4afdhv
cq addr stake1uyehkck0lajq8gr28t9uxnuvgcqrc6070x3k9r8048z8y5gh6ffgw --json

Query Shortcuts

Example Output

$ cq transaction.cbor

Transaction
  Hash: 0edb4eac0b992ac4af71a2a52f41ab63c806e0ef4e5c5d9c7348ea03cf9a9e4e
  Valid: true

Body
  Fee: 171,617 lovelace

Inputs (1)
┌───┬─────────────────┬───────┐
│ # ┆ Transaction ID  ┆ Index │
╞═══╪═════════════════╪═══════╡
│ 0 ┆ 852ec7...73fa31 ┆ 0     │
└───┴─────────────────┴───────┘

Outputs (2)
┌───┬──────────────────────────┬────────────────────────┬───────┐
│ # ┆ Address                  ┆ Value                  ┆ Datum │
╞═══╪══════════════════════════╪════════════════════════╪═══════╡
│ 0 ┆ addr_test1vp9...jg52l8g8 ┆ 9,594,993,891 lovelace ┆ -     │
│ 1 ┆ addr_test1qz8...h7q3xhdsk│ 1,500,000 lovelace     ┆ -     │
└───┴──────────────────────────┴────────────────────────┴───────┘

Witnesses
  VKey signatures: 2

Fetching Real Transactions

Use Koios API to fetch CBOR from mainnet/testnet:

# Mainnet
curl -s -X POST 'https://api.koios.rest/api/v1/tx_cbor' \
  -H 'Content-Type: application/json' \
  -d '{"_tx_hashes": ["YOUR_TX_HASH"]}' | jq -r '.[0].cbor' | xxd -r -p | cq

# Preprod testnet
curl -s -X POST 'https://preprod.koios.rest/api/v1/tx_cbor' \
  -H 'Content-Type: application/json' \
  -d '{"_tx_hashes": ["YOUR_TX_HASH"]}' | jq -r '.[0].cbor' | xxd -r -p | cq

Pro tip - Add this to your .bashrc:

cqtx() {
  curl -s -X POST 'https://api.koios.rest/api/v1/tx_cbor' \
    -H 'Content-Type: application/json' \
    -d "{\"_tx_hashes\": [\"$1\"]}" | jq -r '.[0].cbor' | xxd -r -p | cq "${@:2}"
}

# Usage: cqtx <tx_hash> [query] [flags]
# cqtx 31ed9234a830667a0152fbfe4a244f896f5aad459831a5620571465283ec5f0c
# cqtx 31ed9234... fee --ada

Supported Certificate Types

Babbage Era

• StakeRegistration, StakeDeregistration, StakeDelegation
• PoolRegistration, PoolRetirement

Conway Era (Governance)

• RegCert, UnregCert
• VoteDelegCert, StakeVoteDelegCert
• StakeRegDelegCert, VoteRegDelegCert, StakeVoteRegDelegCert
• AuthCommitteeHotCert, ResignCommitteeColdCert
• RegDrepCert, UnregDrepCert, UpdateDrepCert

Exit Codes

Comparison with Alternatives

Building from Source

git clone https://github.com/karkigrishmin/cq
cd cq
cargo build --release
./target/release/cq --help

Requirements

• Rust 1.85+ (edition 2024)
• No system dependencies

Running Tests

cargo test              # All tests (89 total)
cargo test --test cli   # Integration tests only
cargo test --lib        # Unit tests only

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Run cargo test and cargo clippy
4. Submit a PR

License

MIT License - see LICENSE for details.

Acknowledgments

• CML (Cardano Multiplatform Lib) for Cardano type parsing
• Inspired by the excellent jq tool