> ## Documentation Index > Fetch the complete documentation index at: https://docs.genlabs.co/llms.txt > Use this file to discover all available pages before exploring further. # Client queries > Read on-chain state (accounts, balances, blocks, contracts, components, storage) from the CLI. `gen client` exposes the read-side of the network: every JSON-RPC query method has a matching subcommand. This page covers the pure read commands. For balance and transfer commands that move tokens, see [Sending transfers](/reference/cli/transfers). For activation build/sign/submit and tracing, see [Working with activations](/reference/cli/activations). All `gen client` commands accept the global `--rpc-url ` (`-s`), `--header `, and `--json` (`-j`) flags. JSON mode emits a single envelope: ```json theme={null} { "ok": true, "command": "", "timestamp": "2026-05-27T13:19:36.051512Z", "result": { /* command-specific */ } } ``` On failure, `ok` is `false`, a `code` field is set (for example `TransportError`), and `error` carries the message. Use `--json` for any scripted consumption; text mode is for humans. ## Accounts ### `gen client get-account` Fetch the components installed on an account and its owner. ```bash theme={null} gen client get-account --account grd@1snr7fek9... ``` * `--account `: GvmAccount in bech32m format (HRP grd@) (required). The result lists each component (header, contract, index, version) attached to the account. An account that has never been used returns an error: only accounts that have been bootstrapped (typically by a faucet call) exist on chain. See [Entities and accounts](/user-guide/concepts/entities-and-accounts) for the model. ## Balances (read-only) `gen client balance` and `gen client balances` are documented with the rest of the balance and transfer surface in [Sending transfers](/reference/cli/transfers#balances). They are listed here for completeness: * `gen client balance` queries a single token contract for a wallet or account. * `gen client balances` returns every routed balance for a wallet or account. Both accept `--wallet ` (a local wallet) or `--account ` (any on-chain account). If neither is supplied, the active wallet is used. ## Blocks ### `gen client get-current-block-index` Return the latest finalized block index known to the RPC unit. Useful for picking a `valid_until_block` when building activations. ```bash theme={null} gen client get-current-block-index ``` ```json theme={null} { "ok": true, "command": "get-current-block-index", "result": { "block_index": "8576536" } } ``` The block index is serialized as a decimal string to preserve `u64` precision in JSON. ### `gen client get-block` Return the aggregated closed block at a given index. ```bash theme={null} gen client get-block --block-index 8576500 ``` * `--block-index `: Block index as a decimal integer. The result includes the block's order events: per-activation start/end markers with the activation ID, target entity, and Lamport timestamp. Use this to reconstruct execution order within a block. ## Contracts ### `gen client get-contract` Return contract metadata and all component ABIs for a deployed contract. ```bash theme={null} gen client get-contract --contract grd@1... ``` * `--contract `: Deployed contract identifier from deploy command output (bech32m format with 'grd@' prefix) (required). ### `gen client get-abi-by-contract-id` Return only the ABIs (no metadata) for a deployed contract. Useful when you just need to look up function signatures. ```bash theme={null} gen client get-abi-by-contract-id --contract grd@1... gen client get-abi-by-contract-id --contract grd@1... --output-file ./contract-abis.json ``` * `--contract `: Deployed contract identifier from deploy command output (bech32m format with 'grd@' prefix) (required). * `--output-file `: Write the pretty-printed ABI response JSON to a file. With --json, the ABI also remains in the JSON stdout output. Without --json, stdout shows only a confirmation line instead of the full ABI dump. ### `gen client get-abi-by-contract-code-id` Same shape as `get-abi-by-contract-id`, but takes a contract **code** ID, not a deployed contract ID. This is the identifier returned by `gen client push` before you deploy. ```bash theme={null} gen client get-abi-by-contract-code-id --contract-code-id grd@1... ``` * `--contract-code-id `: Contract code ID from push command output (bech32m format with 'grd@' prefix) (required). * `--output-file `: Write the pretty-printed ABI response JSON to a file. With --json, the ABI also remains in the JSON stdout output. Without --json, stdout shows only a confirmation line instead of the full ABI dump. ## Components ### `gen client get-component` Return the ABI and owner for a single component instance on a specific entity. ```bash theme={null} gen client get-component --gvm-component-id grd@,grd@ ``` * `--gvm-component-id `: GVM component ID (short: grd@\,grd@\; full: grd@\,grd@\,grd@\,grd@\) (required). The short form is what you will pass everywhere else (for `view`, `build-activation`, `get-storage-at`). The full form pins a specific contract code and component type; use it when you need to disambiguate versions. ### `gen client view` Execute a read-only call against a component. No state changes; no signature required. ```bash theme={null} gen client view \ --component-id grd@,grd@ \ --method balance_of \ --params '{"holder": "grd@..."}' ``` * `--component-id `: Target component ID (short: grd@\,grd@\; full: grd@\,grd@\,grd@\,grd@\) (required). * `--method `: Contract method name to invoke (required). * `--params `: Method parameters as JSON object with parameter names as keys. `view` is the read counterpart to `build-activation` + `submit-activation`: the parameter encoding is identical, but no activation is built and no signature is required. ### `gen client get-storage-at` Return the raw storage value for a component at a specific 32-byte key. ```bash theme={null} gen client get-storage-at \ --gvm-component-id grd@,grd@ \ --storage-key 0x<64 hex chars> ``` * `--gvm-component-id `: GVM component ID (short: grd@\,grd@\; full: grd@\,grd@\,grd@\,grd@\) (required). * `--storage-key `: Storage key as a 32-byte hex value with 0x prefix (required). The result is base64-encoded raw bytes, or `null` if the key is unset. This is a low-level escape hatch: prefer `view` against a contract method when one exists. ## Traces ### `gen client get-trace` Return every activation ID that participated in a trace. A trace groups the original activation with every continuation it produced across entities. See [Traces](/user-guide/concepts/traces) for the concept. ```bash theme={null} gen client get-trace --trace-id 0x<128 hex chars> ``` * `--trace-id `: Trace ID (128 hex characters with 0x prefix) (required). For the activation detail itself (status, gas used, events), follow up with `gen client get-activation --activation-id ` on each ID. See [Working with activations](/reference/cli/activations#tracing) for the full pattern. ## Output formatting for scripts Use `--json` and pipe through `jq` for any non-interactive use. The envelope shape is stable across commands, so the same script pattern works everywhere: ```bash theme={null} RPC_URL=$(gen config show | grep rpc_url | awk '{print $2}') BLOCK=$(gen client --json get-current-block-index | jq -r .result.block_index) echo "current finalized block: $BLOCK" ``` For non-JSON output the format is human-targeted and may change between releases. Do not parse it from scripts. ## See also * [Sending transfers](/reference/cli/transfers): `balance`, `balances`, `transfer`, and `faucet`. * [Working with activations](/reference/cli/activations): build, sign, submit, simulate, and inspect activations. * [JSON-RPC API](/reference/rpc/overview): the RPC methods these commands wrap, with parameter and response schemas.