query-blockchain

Querying the Flow Blockchain with flow-cli

Overview

Use this skill any time you need on-chain data. Choose the right command from the decision table, then run it.

When the entity commands don't expose what you need, use flow scripts execute — Cadence scripts can query any on-chain state and are the primary tool for anything not covered by the commands below. See Cadence Scripts.

Network

Default: mainnet. Infer from conversation context:

Access node endpoints (built-in):

• Mainnet: access.mainnet.nodes.onflow.org:9000
• Testnet: access.devnet.nodes.onflow.org:9000
• Emulator: 127.0.0.1:3569

Override with --host <endpoint> to point at a custom access node.

Decision Table

---

Commands

Accounts

flow accounts get <address|name> [--include contracts] [--network mainnet]

• --include contracts adds deployed contract source code to the output
• Flow addresses must include the 0x prefix (e.g. 0xf8d6e0586b0a20c7)
• <name> resolves via flow.json — only use names when a flow.json is present

flow accounts get 0xe467b9dd11fa00df --network mainnet
flow accounts get 0xe467b9dd11fa00df --include contracts --network mainnet
flow accounts staking-info 0xe467b9dd11fa00df --network mainnet

Blocks

flow blocks get <block_id|latest|block_height> [--include transactions] [--events <event_name>] [--network mainnet]

flow blocks get latest --network mainnet
flow blocks get 12884163 --include transactions --network mainnet
flow blocks get latest --events A.1654653399040a61.FlowToken.TokensDeposited --network mainnet

Events

flow events get <event_name> [<event_name2> ...] [--last 10] [--start N --end M] [--network mainnet]

• Default: last 10 blocks. Use --last N to widen.
• --start/--end for explicit block height range.
• Multiple event types are fetched in parallel.
• Event name format: A.<address>.<ContractName>.<EventName>

flow events get A.1654653399040a61.FlowToken.TokensDeposited --last 20 --network mainnet
flow events get A.1654653399040a61.FlowToken.TokensDeposited --start 11559500 --end 11559600 --network mainnet
flow events get A.1654653399040a61.FlowToken.TokensDeposited A.1654653399040a61.FlowToken.TokensWithdrawn --network mainnet

Transactions

# Regular transaction
flow transactions get <tx_id> [--include signatures,code,payload,fee-events] [--exclude events] [--network mainnet]

# System transaction (by block, not tx hash)
flow transactions get-system <block_id|latest|block_height> [tx_id] [--network mainnet]

# Scheduled transactions
flow schedule get <numeric-id> [--network mainnet]
flow schedule list <address|account-name> [--network mainnet]

Collections

flow collections get <collection_id> [--network mainnet]

Network Status

flow status --network mainnet

---

Output Format

All commands support --output json for machine-readable output.

flow accounts get 0xe467b9dd11fa00df --output json --network mainnet
flow events get A.1654653399040a61.FlowToken.TokensDeposited --output json --network mainnet

Use --filter <property> to extract specific fields from results.

---

Cadence Scripts

flow scripts execute is the most powerful read tool. Use it when:

• You need data from a contract that has no dedicated CLI command
• You need to call a view function or read a field from a contract
• You need to combine data from multiple contracts in one query
• You need a historical snapshot at a specific block height

flow scripts execute <script.cdc> [args...] [--args-json '[{"type":"...","value":"..."}]'] [--block-height N] [--block-id <id>] [--network mainnet]

• Simple types (Address, UInt64, String, Bool) can be passed as positional args
• Use --args-json for complex types (UFix64, optionals, structs, arrays)
• --block-height / --block-id execute against historical state
• Write a temporary .cdc file, execute it, then clean up

Writing and Running Scripts

Write script to a temp file, execute, clean up:

# Write
cat > /tmp/query.cdc << 'EOF'
import FungibleToken from 0xf233dcee88fe0abe
import FlowToken from 0x1654653399040a61

access(all) fun main(address: Address): UFix64 {
    let account = getAccount(address)
    let vaultRef = account.capabilities
        .borrow<&{FungibleToken.Balance}>(/public/flowTokenBalance)
        ?? panic("Could not borrow FungibleToken Balance capability for account \(address) at path /public/flowTokenBalance. Make sure the account has a FlowToken Vault set up properly.")
    return vaultRef.balance
}
EOF

# Execute
flow scripts execute /tmp/query.cdc 0xe467b9dd11fa00df --network mainnet

# Clean up
rm /tmp/query.cdc

Passing Arguments

# Simple types as positional args
flow scripts execute /tmp/query.cdc 0xe467b9dd11fa00df --network mainnet

# Complex types with --args-json (JSON-Cadence encoding)
flow scripts execute /tmp/query.cdc --args-json '[{"type":"UFix64","value":"100.0"},{"type":"Address","value":"0xe467b9dd11fa00df"}]' --network mainnet

# Historical state
flow scripts execute /tmp/query.cdc 0xe467b9dd11fa00df --block-height 12884163 --network mainnet

---

Contract Addresses

¹ The EVM bridge account hosts many contracts beyond FlowEVMBridge itself (FlowEVMBridgeConfig, FlowEVMBridgeUtils, FlowEVMBridgeNFTEscrow, FlowEVMBridgeTokenEscrow, CrossVMNFT, CrossVMToken, and more). Run flow accounts get 0x1e4aa0b87d10b141 --network mainnet for the current deployed contract list, or check the flow-evm-bridge repo for available scripts.

---

Cadence Script Recipes & Data Structures

See cadence-scripts.md for 20+ ready-to-use Cadence scripts organized by category:

• Token queries — FLOW balance, total supply, generic FT balance, FT metadata
• Account & storage — storage capacity, available balance, account creation fee, fee parameters
• Epoch — counter, phase, metadata, timing config
• Staking — node info, staked node IDs, total staked, by role, requirements, rewards, delegator info, staking collections
• Protocol — node version beacon, random beacon source
• NFT — collection IDs, NFT metadata (Display)
• Key data structures — NodeInfo, DelegatorInfo, EpochMetadata, EpochPhase, Node Roles

---

Common Event Types

---

Available Script Libraries

For more complex queries, clone these repos to /tmp and use their scripts directly:

# Example: use an existing script from flow-core-contracts
git clone --depth 1 https://github.com/onflow/flow-core-contracts.git /tmp/flow-core-contracts
flow scripts execute /tmp/flow-core-contracts/transactions/idTableStaking/scripts/get_node_info.cdc "abc123...def456" --network mainnet

Note: Some repo scripts use import "ContractName" syntax (no address). These require a flow.json with address mappings. For ad-hoc queries, replace with explicit addresses:

// Repo style (requires flow.json aliases):
import "FlowToken"
// Direct style (works without flow.json):
import FlowToken from 0x1654653399040a61