> ## 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. # Working with activations > Build, sign, simulate, submit, and inspect activations from the command line. This page is the CLI reference for the activation lifecycle: build an unsigned activation, optionally simulate it, sign it (in-process or on a separate machine), submit it, and then inspect the result. For the conceptual model (what an activation is, what is signed, how IDs are computed), see [Activations](/user-guide/concepts/activations) and [Activation structure](/user-guide/concepts/activation-structure). For the ready-made transfer and faucet wrappers, see [Sending transfers](/reference/cli/transfers). All commands accept the global `--rpc-url ` (`-s`), `--header `, and `--json` (`-j`) flags. JSON mode emits a single envelope (`{ ok, command, timestamp, result | error }`). ## Two surfaces: `gen wallet` and `gen client` The activation commands are mirrored under both `gen wallet` and `gen client`: * `gen wallet ` resolves the signing wallet via the usual precedence (positional `NAME`, `--wallet`, then the active wallet recorded in `~/.gen/wallets/config.toml`). * `gen client ` takes the same wallet arguments and resolves them the same way, including the fallback to the active wallet. Pick whichever fits your script. The on-chain effect is identical. ## Lifecycle in one flow The longest possible flow uses every command in sequence: ```bash theme={null} # 1. Build the unsigned activation against a component method. gen wallet --json build-activation alice \ --component-id grd@,grd@ \ --method transfer \ --params '{"to": "grd@...", "amount": ["1000"]}' \ | jq -r .result.unsigned_activation_hex > unsigned.txt # 2. (Optional) Dry-run against current state before broadcasting. gen client simulate-activation --unsigned-activation-file unsigned.txt # 3. Sign locally (or move unsigned.txt to a signer machine and sign there). gen wallet --json sign-activation alice --unsigned-activation-file unsigned.txt \ | jq -r .result.signed_activation_hex > signed.txt # 4. Submit the signed activation from anywhere. gen client submit-activation --signed-activation-file signed.txt # 5. Inspect the on-chain result. gen client get-activation --activation-id 0x... ``` For the common case where you want all five steps in one call, use `sign-and-submit-activation`. ## `build-activation` Construct an unsigned activation against a component method. The output is the canonical pre-image bytes: nothing has been signed and nothing has been submitted. Building still reaches the network to fetch the target component's ABI (and, unless you pass `--valid-until-block`, the current block index for the expiry window); it only stops short of broadcasting. ```bash theme={null} gen wallet build-activation alice \ --component-id grd@,grd@ \ --method transfer \ --params '{"to": "grd@...", "amount": ["1000"]}' gen wallet build-activation alice \ --component-id grd@,grd@ \ --method transfer \ --args '["grd@...", ["1000"]]' gen wallet build-activation alice \ --request '{"component_id":"grd@...,grd@...","function":"transfer","params":{"to":"grd@...","amount":["1000"]}}' gen wallet --json build-activation alice --request-file ./activation-request.json ``` Specify the call one of three mutually exclusive ways: `--component-id` with `--method` and one of `--params`/`--args`; a single `--request` JSON blob; or `--request-file` pointing at that same JSON. The `[NAME]` positional (or `--wallet`) selects the wallet whose public key is the signer (and, by default, the target), falling back to the active wallet when omitted; `gen client build-activation` takes the same flags and resolves the wallet the same way. * `[NAME]` (positional): Wallet to act on; defaults to the active wallet. * `--wallet `: Wallet to act on, as a flag instead of the positional NAME; defaults to the active wallet. * `--valid-until-block `: Explicit valid-until block index; set it to skip fetching the current block when building the unsigned activation. * `--component-id `: Target component ID when building from flags. * `--method `: Contract method name when building from flags. * `--params `: Method parameters as a JSON object with parameter names as keys. * `--args `: Method parameters as a JSON array in ABI parameter order. * `--request `: Build request as JSON with `component_id`, `function`, and optional `params` or `args`. * `--request-file `: Read the build request JSON from a file. The output is the unsigned activation bytes (`0x`-prefixed hex by default; or inside the JSON envelope under `--json`). Treat it as opaque: pass it to `sign-activation` or `simulate-activation` unchanged. ## `simulate-activation` Dry-run an unsigned activation against the validator without broadcasting. Returns the same execution result the network would produce: per-operation storage changes, emitted events, continuations, and the outcome. ```bash theme={null} gen client simulate-activation --unsigned-activation 0x... gen client simulate-activation --unsigned-activation-file ./unsigned.txt --block-index 42 gen client --json simulate-activation --unsigned-activation-file ./unsigned.txt ``` Supply the activation bytes one of two ways (one is required): inline with `--unsigned-activation`, or from a file with `--unsigned-activation-file`. * `--unsigned-activation `: Unsigned activation bytes encoded as 0x-prefixed hex or base64. * `--unsigned-activation-file `: Read unsigned activation bytes from a file containing 0x-prefixed hex or base64 text. * `--block-index `: Optional block index to simulate against. Defaults to the latest finalized block when omitted. Simulation does not check signatures and does not consume any tag or expiry; it is purely a state read. Use it before signing to verify parameters, surface ABI mismatches, and estimate gas. ## `sign-activation` Sign an unsigned activation with a wallet's private key. The signature covers the 82-byte pre-image derived from the activation; see [What is signed](/user-guide/concepts/activation-structure#what-is-signed). ```bash theme={null} gen wallet sign-activation --unsigned-activation-file ./unsigned.txt gen wallet sign-activation alice --unsigned-activation 0x... gen wallet sign-activation alice --unsigned-activation-file ./unsigned.txt --activation-tag 77 gen wallet --json sign-activation alice --unsigned-activation-file ./unsigned.txt ``` Supply the unsigned bytes one of two ways (one is required): inline with `--unsigned-activation`, or from a file with `--unsigned-activation-file`. The `[NAME]` positional (or `--wallet`) selects the signing wallet, defaulting to the active wallet. Override `--activation-tag` to resubmit a structurally identical activation without tripping replay protection - two activations with the same signer, target, and operations but different tags get different IDs. * `[NAME]` (positional): Wallet to act on; defaults to the active wallet. * `--wallet `: Wallet to act on, as a flag instead of the positional NAME; defaults to the active wallet. * `--unsigned-activation `: Unsigned activation bytes encoded as 0x-prefixed hex or base64. * `--unsigned-activation-file `: Read unsigned activation bytes from a file containing 0x-prefixed hex or base64 text. * `--activation-tag `: Override the activation tag before signing to make an otherwise-identical activation unique. The same wallet that built the activation must sign it (the signer public key is baked into the unsigned bytes). The output is the signed activation, ready for `submit-activation`. `gen client sign-activation` is the same command and resolves the wallet the same way, including the active-wallet fallback. ## `submit-activation` Send a pre-signed activation to the network. ```bash theme={null} gen client submit-activation --signed-activation 0x... gen client submit-activation --signed-activation-file ./signed.txt gen client submit-activation --signed-activation-file ./signed.txt --no-wait ``` Supply the signed bytes one of two ways (one is required): inline with `--signed-activation`, or from a file with `--signed-activation-file`. With `--no-wait` the call returns as soon as the validator acknowledges the submission; the response still contains the `activation_id`, so follow up with `get-activation` to confirm the final outcome. * `--signed-activation `: Pre-signed activation bytes encoded as 0x-prefixed hex or base64. * `--signed-activation-file `: Read a pre-signed activation from a file containing 0x-prefixed hex or base64 text. * `--no-wait`: Return immediately after sending without waiting for the activation to complete. `submit-activation` does not need a wallet: the activation is already signed, and the signer is recorded in the signed bytes. This is the command you run on an internet-connected machine after signing on an isolated one. ## `sign-and-submit-activation` Sign and submit in a single call. Convenience for the common in-process flow. ```bash theme={null} gen wallet sign-and-submit-activation alice --unsigned-activation 0x... gen wallet sign-and-submit-activation alice --unsigned-activation-file ./unsigned.txt --activation-tag 77 --no-wait gen wallet --json sign-and-submit-activation alice --unsigned-activation-file ./unsigned.txt ``` Supply the unsigned bytes one of two ways (one is required): inline with `--unsigned-activation`, or from a file with `--unsigned-activation-file`. The `[NAME]` positional (or `--wallet`) selects the signing wallet, defaulting to the active wallet on both surfaces; `gen client sign-and-submit-activation` is otherwise the same call. * `[NAME]` (positional): Wallet to act on; defaults to the active wallet. * `--wallet `: Wallet to act on, as a flag instead of the positional NAME; defaults to the active wallet. * `--unsigned-activation `: Unsigned activation bytes encoded as 0x-prefixed hex or base64. * `--unsigned-activation-file `: Read unsigned activation bytes from a file containing 0x-prefixed hex or base64 text. * `--no-wait`: Return immediately after sending without waiting for the activation to complete. * `--activation-tag `: Override the activation tag before signing to make an otherwise-identical activation unique. ## `get-activation` Fetch the on-chain record for an activation: status, gas used, emitted events, and the block range it occupied. ```bash theme={null} gen client get-activation --activation-id 0x<128 hex chars> gen client --json get-activation --activation-id 0x... ``` * `--activation-id `: Activation ID (128 hex characters with 0x prefix) (required). In `--json` mode the activation details are nested under `.result.activation`: * `status`: `pending`, `running`, `success`, or `failed`. * `start_block` / `end_block`: the block range the activation occupied. `end_block` is final once `status` is `success` or `failed`. * `gas_used`: `{ cpu, network, storage_io }`, each as a decimal `u128` string. See [Gas and fees](/user-guide/concepts/gas-and-fees). * `events`: domain events emitted during execution, with payloads as base64. * `continuations`: the IDs of any follow-up activations this one triggered. * `from` / `to`: signer entity and target entity. `get-activation` returns a JSON-RPC `NOT_FOUND` error if the ID is unknown. ## Tracing ### `get-trace` A trace groups an activation with every continuation it produced across entities. Use it when you need the full graph an activation kicked off, not just the activation itself. See [Traces](/user-guide/concepts/traces) for the concept. ```bash theme={null} gen client get-trace --trace-id 0x<128 hex chars> gen client --json get-trace --trace-id 0x... ``` * `--trace-id `: Trace ID (128 hex characters with 0x prefix) (required). In `--json` mode the trace activation IDs are under `.result.trace.activations`. Inspect each one with `get-activation` to assemble the per-step detail. ## When to use which * **Online, single machine.** Use `sign-and-submit-activation` directly, or skip the activation primitives entirely and use the wrappers in [Sending transfers](/reference/cli/transfers). * **Sign offline, submit elsewhere.** `build-activation` on the online machine, copy the unsigned bytes to the air-gapped signer, `sign-activation` there, copy the signed bytes back, `submit-activation` from anywhere on the network. * **Dry-run first.** Insert `simulate-activation` between `build-activation` and `sign-activation`. Cheap and signature-free, and it surfaces ABI mismatches and reverts before you commit to broadcasting. * **Submit and poll.** Pass `--no-wait` to `submit-activation` or `sign-and-submit-activation` when you want the activation ID immediately and will check the final state later with `get-activation`. * **Resubmit an identical-looking activation.** Override the tag with `--activation-tag ` on `sign-activation` or `sign-and-submit-activation`. This produces a different activation ID and bypasses dedup. ## See also * [Activations](/user-guide/concepts/activations): the developer model. * [Activation structure](/user-guide/concepts/activation-structure): byte layout, signed pre-image, and the validity window. * [Traces](/user-guide/concepts/traces): the spawn-tree returned by `get-trace`. * [Sending transfers](/reference/cli/transfers): high-level wrappers for the most common operations. * [Client queries](/reference/cli/client-queries): the read-side surface, including `view` for read-only calls. * [JSON-RPC API](/reference/rpc/overview): `gen_submitActivation`, `gen_simulateActivation`, `gen_getActivation`, `gen_getTrace`.