Aptos Node Management & CLI Cheat Sheet

Staking (Validator Staking Pool)

Create Staking Pool (Validator Contract)

aptos stake create-staking-contract \
  --operator <operator-address> \
  --voter <voter-address> \
  --amount 100000000000000 \
  --commission-percentage 10 \
  --profile <owner-profile>

Initializes a staking pool (requires ≥1,000,000 APT stake). Commission 10 equals 10%.

Add Stake to Validator Pool

aptos stake add-stake --amount <amount> --profile <owner-profile>

Adds more APT to an existing validator’s stake.

Increase Stake Lockup

aptos stake increase-lockup --profile <owner-profile>

Extends the lockup period for the staked funds (uses the maximum lockup by default).

Unlock Stake (Begin Unstaking)

aptos stake unlock-stake --amount <amount> --profile <owner-profile>

Requests to unlock a portion of stake. The stake moves to pending_inactive and will become withdrawable after the lockup period ends.

Withdraw Stake (After Unlock)

aptos stake withdraw-stake --amount <amount> --profile <owner-profile>

Withdraws unlocked stake (must be in inactive state after lockup expiration).

Switch Operator Account

aptos stake set-operator --operator-address <new-operator-address> --profile <owner-profile>

Changes the operator of the staking pool (the new operator should be running a node).

Switch Delegated Voter

aptos stake set-delegated-voter --voter-address <new-voter-address> --profile <owner-profile>

Changes the designated voting account for governance (the new voter must have the same or longer lockup as the owner).

Request Staking Commission

aptos stake request-commission \
  --operator-address <operator-address> \
  --owner-address <owner-address> \
  --profile <operator-profile>

Claims the validator operator’s commission rewards. This must be called twice for each epoch’s rewards: once before the lockup period ends (to initiate unlocking of commission), and once after the epoch/lockup ends (to actually withdraw the commission). Ensure both the operator and owner addresses are provided.

Update Commission Percentage

aptos move run \
  --function-id 0x1::staking_contract::update_commission \
  --args address:<operator_address> u64:<new_commission_percentage> \
  --profile <owner-profile>

Updates the staking pool’s commission rate (owner only). For example, 1325 = 13.25%. Must be requested at least 7.5 days before the current lockup ends; new rate takes effect after the lockup expires and a new epoch begins (triggered by calling request-commission after lockup).

Set Commission Beneficiary (Operator)

aptos move run \
  --function-id 0x1::staking_contract::set_beneficiary_for_operator \
  --args address:<beneficiary_address> \
  --profile <operator-profile>

Sets an address to receive the operator’s commission rewards for this staking pool. Any commission accrued but not yet paid will be paid out to the new beneficiary upon the next distribution.

View Commission Beneficiary

aptos move view \
  --function-id 0x1::staking_contract::beneficiary_for_operator \
  --args address:<operator_address> \
  --url https://fullnode.mainnet.aptoslabs.com/v1

Displays the current beneficiary address set for the operator.

Check Staking Pool Status

aptos node get-stake-pool --owner-address <owner_address> --profile <profile>

Shows details of your staking pool (state, pool_address, operator, voter, total_stake, commission %, etc.). Use the pool_address (resource account) in your node’s config. State will be Active if already in validator set or Pending_active if waiting for next epoch.

Delegation Pool (Multi-Delegator Staking)

Add Stake to Delegation Pool

aptos move run \
  --function-id 0x1::delegation_pool::add_stake \
  --args address:<pool_address> u64:<amount> \
  --profile <delegator-profile>

Delegate coins to a validator’s delegation pool at pool_address. Minimum 10 APT required to delegate. (plus a small fee, mostly refunded as rewards).

Unlock Delegated Stake

aptos move run \
  --function-id 0x1::delegation_pool::unlock \
  --args address:<pool_address> u64:<amount> \
  --profile <delegator-profile>

Initiates unstaking of delegated APT. The specified amount moves to a pending inactive state in the pool, and will become withdrawable after the lockup period ends.

Reactivate Stake (Cancel Unlock)

aptos move run \
  --function-id 0x1::delegation_pool::reactivate_stake \
  --args address:<pool_address> u64:<amount> \
  --profile <delegator-profile>

Reverses a pending unlock, moving the stake back to active status (before it becomes fully inactive).

Withdraw Inactive Stake

aptos move run \
  --function-id 0x1::delegation_pool::withdraw \
  --args address:<pool_address> u64:<amount> \
  --profile <delegator-profile>

Withdraws your inactive stake from the delegation pool to your account (only funds that have completed the unlock period can be withdrawn).

Set Delegation Pool Operator (Owner)

aptos move run \
  --function-id 0x1::delegation_pool::set_operator \
  --args address:<new_operator_address> \
  --profile <pool_owner-profile>

Assigns a new operator for the delegation pool (owner only).The operator’s account will run the validator node and earn the set commission on rewards.

Update Delegation Pool Commission

aptos move run \
  --function-id 0x1::delegation_pool::update_commission_percentage \
  --args u64:<new_commission_percentage> \
  --profile <pool_owner-profile>

Changes the commission rate for the delegation pool (owner only). The value has two decimal places (e.g. 1325 = 13.25%). Must be initiated >7 days before epoch end; new rate takes effect after the current lockup cycle finishes and the owner calls synchronize_delegation_pool in the new epoch.

Set Commission Beneficiary (Delegation Pool Operator)

aptos move run \
  --function-id 0x1::delegation_pool::set_beneficiary_for_operator \
  --args address:<beneficiary_address> \
  --profile <operator-profile>

Sets an address to receive the operator’s commission for all delegation pools this operator manages. The beneficiary can then unlock/withdraw the commission rewards on behalf of the operator.

View Delegation Pool Beneficiary

aptos move view \
  --function-id 0x1::delegation_pool::beneficiary_for_operator \
  --args address:<operator_address> \
  --url https://fullnode.mainnet.aptoslabs.com/v1

Shows the currently set beneficiary address for the operator’s commission.

Find Delegation Pool Address (by Owner)

aptos move view \
  --function-id 0x1::delegation_pool::get_owned_pool_address \
  --args address:<owner_address> \
  --url https://fullnode.mainnet.aptoslabs.com/v1

Returns the resource account address of the delegation pool owned by the given owner address (if one exists).

Check Delegation Pool Stake

aptos move view \
  --function-id 0x1::delegation_pool::get_delegation_pool_stake \
  --args address:<pool_address> \
  --url https://fullnode.mainnet.aptoslabs.com/v1

Shows the total stake in the pool split by state: active, inactive, pending_active, pending_inactive.

Governance (On-Chain Proposals & Voting)

List Active Proposals

aptos governance list-proposals --url https://fullnode.mainnet.aptoslabs.com/v1

Displays all on-chain governance proposals and their details (proposal ID, status, etc.).

Vote on Proposal (Staking Pool Owner/Voter)

aptos governance vote \
  --proposal-id <PROPOSAL_ID> \
  --pool-address <staking_pool_address> \
  --profile <voter-profile> \
  --url https://fullnode.mainnet.aptoslabs.com/v1

Casts a vote on a governance proposal using your stake pool’s voting power. Use the stake owner’s profile (or delegated voter’s profile) and the stake pool’s address. Ensure your stake’s lockup is at least as long as the proposal voting period.

Execute Approved Proposal

aptos governance execute-proposal --proposal-id <PROPOSAL_ID> --url https://fullnode.mainnet.aptoslabs.com/v1

Anyone may execute a proposal that has passed and met quorum, to enact the changes on-chain. This will run the proposal’s payload (such as code upgrade or parameter change). Only use on proposals in "Passed" state.

Vote as Delegator (Delegation Pool)

aptos move run \
  --function-id 0x1::delegation_pool::vote \
  --args address:<pool_address> u64:<proposal_id> u64:<voting_power> bool:<yes_or_no> \
  --profile <delegator-profile>

Vote on a proposal with a delegation pool stake. You can specify an amount of voting power (in APT) up to your active stake. bool:true = YES, bool:false = NO.

Delegate Your Voting Power

aptos move run \
  --function-id 0x1::delegation_pool::delegate_voting_power \
  --args address:<pool_address> address:<delegate_to_address> \
  --profile <delegator-profile>

Delegates your governance voting rights to another address. The delegated voter will vote on proposals using your stake’s power. This change takes effect in the next lockup cycle.

View Delegated Voter

aptos move view \
  --function-id 0x1::delegation_pool::calculate_and_update_delegator_voter \
  --args address:<pool_address> address:<delegator_address> \
  --url https://fullnode.mainnet.aptoslabs.com/v1

Shows which voter address is currently designated to vote on behalf of the given delegator in the pool.

Node Operations & Status

Update Validator Network Addresses

aptos node update-validator-network-addresses \
  --pool-address <pool_address> \
  --operator-config-file ~/workspace/<user>/operator.yaml \
  --profile <operator-profile>

Updates your validator’s on-chain network addresses (for validator node and its fullnode). Run this after editing your operator.yaml with the correct addresses. Changes take effect at the next epoch.

Update Consensus Key

aptos node update-consensus-key \
  --pool-address <pool_address> \
  --operator-config-file ~/workspace/<user>/operator.yaml \
  --profile <operator-profile>

Rotates the validator’s consensus public key on-chain. Use the new key in your node config file before running this. Takes effect after the current epoch ends.

Join Validator Set

aptos node join-validator-set --pool-address <pool_address> --profile <operator-profile>

Signals that your validator (with an active stake pool) wants to join the consensus validator set. The validator will enter Pending_active state and will become an active validator at the next epoch boundary.

Leave Validator Set

aptos node leave-validator-set --profile <operator-profile>

Voluntarily removes your validator from the active set. The validator will move to an inactive state at the next epoch (or immediately if stake falls below minimum).

Check Validator Set Status

aptos node show-validator-set --profile <operator-profile>

Displays the current on-chain list of validators. Look for your pool_address in the output. (For example, to see if you’re in pending or active set: aptos node show-validator-set | jq -r '.Result.pending_active[] | .pool_address' and likewise for .active_validators).

Check Validator Performance

aptos node get-performance --pool-address <pool_address> --profile <operator-profile>

Shows your validator’s performance stats for recent epochs, including successful proposals and voting on governance, as well as rewards earned.

Analyze Performance (All Epochs)

aptos node analyze-validator-performance \
  --analyze-mode detailed-epoch-table \
  --start-epoch 0 --profile <operator-profile> | grep <pool_address>

Outputs a table of performance metrics for every epoch since genesis. You can grep for your pool address to find your validator’s history.

Basic Node Health Check

curl -s http://127.0.0.1:8080/v1/-/healthy

Returns HTTP 200 if the node’s REST API is up and the node is healthy (latest ledger info is recent). A non-200 response or error indicates the node is unhealthy.

Check Sync Progress

curl -s http://127.0.0.1:9101/metrics | grep "aptos_state_sync_version{.*\"synced\"}" | awk '{print $2}'

Queries the node’s metrics to get the highest synced ledger version. Compare this number with the latest block height on an explorer; if it’s catching up, the node is syncing properly (Requires the metrics port, default 9101, to be accessible).

Check Peer Connectivity

curl -s http://127.0.0.1:9101/metrics | grep 'aptos_connections{direction="outbound"' 

Shows the count of outbound peer connections from your node. A healthy node should have a non-zero number of outbound peers. If it’s 0, your node isn’t connecting to the network (check network config or update to the latest release).

Get Node Ledger Info

curl -s http://127.0.0.1:8080/v1/ | jq '{chain_id, block_height, git_hash}'

Fetches basic ledger information from the node’s REST API, including the chain ID, current block height, and the node’s git commit hash (version).

Check Node Version (Binary)

aptos-node --version

If running a local binary, this outputs the Aptos node software version and commit hash (Not an Aptos CLI command, but the node binary itself).

View Running Docker Container (if using Docker)

docker ps | grep aptos

Verifies the Aptos node container is running. Note the container NAME or ID and image tag (which indicates the release version).

Check Ledger DB Size (Docker)

docker exec -it <aptos_container_name_or_id> du -sh /opt/aptos/data

Shows the storage used by the node’s ledger database inside the container. This helps monitor disk usage growth over time.

Check Ledger DB Size (Bare Metal)

du -sh /opt/aptos/data

If running natively on bare metal, check the data directory size (path may vary based on your config). Default ledger directory is /opt/aptos/data for many installations.

Tail Node Logs (Docker)

docker logs -f <aptos_container_name_or_id>

Streams the Aptos node’s logs in real-time. Useful for debugging issues (e.g., consensus, networking problems). Press Ctrl+C to stop.