Referência da CLI do Solana

A interface de linha de comando solana configura a conexão com um cluster, lê o estado da rede, envia SOL, gerencia nonces duráveis, implanta programas e opera contas de stake e de voto.

Esta referência segue o Agave v4.2.1. Execute solana --version para verificar a versão instalada e use --help para ver as opções exatas disponíveis nessa versão.

Comandos que criam, transferem, autorizam, sacam ou implantam enviam transações. Confirme o cluster e o signatário configurados antes de executá-los. Os tokens da Devnet e da Testnet não têm valor; os comandos na Mainnet usam SOL real.

Estrutura dos comandos

solana [GLOBAL_OPTIONS] <COMMAND> [COMMAND_OPTIONS]

Obtenha ajuda em qualquer nível:

solana --help
solana transfer --help
solana address-lookup-table extend --help

Opções globais

As opções globais podem ser colocadas antes do comando. A ajuda específica de cada comando repete as opções que se aplicam a ele.

Opção	Finalidade
`-u, --url <URL_OR_MONIKER>`	Seleciona uma URL de RPC ou `mainnet-beta`, `testnet`, `devnet` ou `localhost`.
`--ws <URL>`	Substitui o endpoint WebSocket.
`-k, --keypair <KEYPAIR>`	Seleciona um arquivo de keypair, `ASK`, stdin (`-`) ou uma URL de signatário compatível.
`-C, --config <FILEPATH>`	Usa um arquivo de configuração da CLI diferente.
`--commitment <LEVEL>`	Lê com o nível de commitment `processed`, `confirmed` ou `finalized`.
`--output <FORMAT>`	Retorna `json` ou `json-compact` onde houver suporte.
`--skip-preflight`	Envia sem simulação de RPC. Use apenas quando entender os riscos de falha.
`--use-tpu-client`	Envia transações por meio do cliente TPU.
`--no-address-labels`	Imprime endereços sem rótulos locais.
`--skip-seed-phrase-validation`	Permite uma frase de recuperação fora da lista em inglês do BIP39.
`-v, --verbose`	Mostra saída adicional do comando.
`-V, --version`	Imprime a versão instalada da CLI.

Configurar a CLI

# Inspect the effective configuration.
solana config get

# Use Devnet and a specific signer by default.
solana config set --url devnet
solana config set --keypair ./devnet-keypair.json

# Override defaults for one command.
solana --url mainnet-beta --keypair usb://ledger address

A configuração contém uma URL de RPC, uma URL de WebSocket, o signatário padrão e o commitment. Uma opção de linha de comando substitui o valor salvo naquela invocação.

Fluxos comuns de contas e transações

# Print the default signer's address and balance.
solana address
solana balance

# Read an account as JSON.
solana account <ACCOUNT_ADDRESS> --output json

# Request Devnet SOL.
solana airdrop 1 --url devnet

# Send SOL and then confirm the returned signature.
solana transfer <RECIPIENT_ADDRESS> 0.1 --allow-unfunded-recipient
solana confirm <TRANSACTION_SIGNATURE>

# Inspect recent activity and stream logs mentioning an address.
solana transaction-history <ADDRESS> --limit 20
solana logs <ADDRESS>

transfer aceita SOL por padrão. Use ALL como valor para mover o saldo disponível depois das taxas. Para exemplos com tokens, consulte o guia rápido de tokens.

Fluxos de programas

# Deploy or upgrade an SBF program.
solana program deploy ./target/deploy/my_program.so

# Inspect the deployed program and list programs controlled by the signer.
solana program show <PROGRAM_ID>
solana program show --programs

# Close a program buffer and recover its lamports.
solana program close <BUFFER_ADDRESS>

Passe --program-id <KEYPAIR_OR_ADDRESS> quando uma implantação precisar usar um ID de programa conhecido. --final torna uma nova implantação imutável; leia a ajuda com atenção antes de usá-lo, pois a autoridade de atualização não pode ser restaurada.

Fluxos de nonce durável

solana-keygen new --outfile nonce-account.json
solana create-nonce-account nonce-account.json 0.1
solana nonce nonce-account.json
solana new-nonce nonce-account.json
solana withdraw-from-nonce-account nonce-account.json <RECIPIENT_ADDRESS> ALL

Use authorize-nonce-account para alterar a autoridade do nonce e nonce-account para inspecionar o estado completo da conta. As transações que usam um nonce também aceitam --nonce e --nonce-authority nos comandos compatíveis.

Fluxos de stake

solana-keygen new --outfile stake-account.json
solana create-stake-account stake-account.json 1
solana delegate-stake stake-account.json <VOTE_ACCOUNT_ADDRESS>
solana stake-account stake-account.json

solana deactivate-stake stake-account.json
solana withdraw-stake stake-account.json <RECIPIENT_ADDRESS> ALL

A desativação é concluída no limite de um epoch e pode levar mais de um epoch. Use stakes, validators, stake-history e stake-minimum-delegation para inspecionar o estado do cluster e das delegações antes de enviar alterações.

Utilitários de endereço

# Derive a PDA from typed seeds.
solana find-program-derived-address \
  <PROGRAM_ID> \
  string:profile \
  pubkey:<OWNER_ADDRESS>

# Create and extend an address lookup table.
solana address-lookup-table create
solana address-lookup-table extend \
  <LOOKUP_TABLE_ADDRESS> \
  --addresses <ADDRESS_1>,<ADDRESS_2>

Os seeds de PDA usam PREFIX:VALUE. Os prefixos compatíveis incluem string, pubkey, hex, u8 e codificações de inteiros com largura fixa, com ou sem sinal, como u64le.

Mensagens off-chain e autocompletar do shell

solana sign-offchain-message "terms accepted"
solana verify-offchain-signature \
  "terms accepted" \
  <SIGNATURE> \
  --signer <SIGNER_ADDRESS>

# Print a completion script for the current shell.
solana completion --shell zsh

Índice completo de comandos

O índice a seguir inclui todos os comandos de nível superior do Agave v4.2.1. Comandos como program, config, feature e address-lookup-table contêm subcomandos; execute <command> --help para listá-los.

Comando	Descrição
`account`	Mostra os lamports, o proprietário, os dados e o estado executável de uma conta.
`address`	Imprime a chave pública do signatário selecionado.
`address-lookup-table`	Cria, estende, congela, desativa, fecha e inspeciona tabelas de consulta de endereços.
`airdrop`	Solicita SOL a um faucet do cluster.
`alpenglow-genesis-info`	Lê informações sobre o certificado de gênese do Alpenglow.
`authorize-nonce-account`	Atribui uma autoridade a uma conta de nonce durável.
`balance`	Mostra o saldo de SOL de uma conta.
`block`	Busca um bloco confirmado por slot.
`block-height`	Mostra a altura atual do bloco.
`block-production`	Mostra a produção de blocos do líder para um intervalo de slots.
`block-time`	Estima o horário de produção de um bloco.
`catchup`	Aguarda um validator alcançar o cluster.
`close-vote-account`	Fecha uma conta de voto e saca os fundos restantes.
`cluster-date`	Estima a data do cluster a partir do horário de gênese e do horário da rede.
`cluster-version`	Mostra a versão do software do entrypoint do cluster.
`completion`	Gera um script de autocompletar do shell.
`config`	Obtém ou define os padrões da CLI.
`confirm`	Verifica o status de confirmação da assinatura de uma transação.
`create-address-with-seed`	Deriva um endereço do sistema a partir de uma base, um seed e um ID de programa.
`create-nonce-account`	Cria e inicializa uma conta de nonce durável.
`create-stake-account`	Cria uma conta de stake.
`create-stake-account-checked`	Cria uma conta de stake verificando a autoridade de saque como signatária.
`create-vote-account`	Cria uma conta de voto de validator.
`deactivate-stake`	Inicia a desativação do stake delegado.
`decode-transaction`	Decodifica uma transação serializada.
`delegate-stake`	Delega uma conta de stake a uma conta de voto.
`epoch`	Mostra o número do epoch atual.
`epoch-info`	Mostra informações de epoch, slot, altura do bloco e contagem de transações.
`feature`	Inspeciona e gerencia contas de recursos (feature) do runtime.
`find-program-derived-address`	Deriva um PDA e o bump canônico a partir de seeds tipados.
`first-available-block`	Mostra o primeiro bloco completo retido pelo nó RPC.
`genesis-hash`	Mostra o hash de gênese do cluster.
`gossip`	Lista os nós visíveis por meio do gossip.
`help`	Imprime a ajuda raiz ou de um comando.
`inflation`	Mostra informações sobre o governador de inflação, a taxa ou as recompensas.
`largest-accounts`	Lista as maiores contas do cluster.
`leader-schedule`	Exibe o cronograma de líderes.
`live-slots`	Transmite em fluxo a progressão do slot atual.
`logs`	Transmite em fluxo os logs de transações, opcionalmente filtrados por endereço.
`merge-stake`	Mescla contas de stake compatíveis.
`new-nonce`	Avança um nonce durável.
`nonce`	Imprime o valor de um nonce durável.
`nonce-account`	Mostra o estado completo de uma conta de nonce durável.
`program`	Implanta, atualiza, inspeciona, exporta, define a autoridade de ou fecha programas e buffers.
`recent-prioritization-fees`	Mostra as taxas de priorização recentes para contas graváveis.
`rent`	Calcula o mínimo isento de aluguel para o tamanho dos dados de uma conta.
`resolve-signer`	Resolve uma referência geral de signatário, como uma URL de Ledger, para o caminho específico.
`sign-offchain-message`	Assina uma mensagem off-chain em UTF-8.
`slot`	Mostra o slot atual.
`split-stake`	Divide lamports de uma conta de stake em outra.
`stake-account`	Mostra as autoridades, o saldo e o estado de delegação de uma conta de stake.
`stake-authorize`	Altera uma autoridade de stake ou de saque.
`stake-authorize-checked`	Altera uma autoridade de stake verificando a nova autoridade como signatária.
`stake-history`	Mostra o histórico de ativação e desativação de stake do cluster.
`stake-minimum-delegation`	Mostra a delegação mínima de stake do cluster.
`stake-set-lockup`	Define o lockup de uma conta de stake.
`stake-set-lockup-checked`	Define um lockup verificando o novo custodiante como signatário.
`stakes`	Lista contas de stake, opcionalmente filtradas por validator ou autoridade.
`supply`	Mostra a oferta circulante, não circulante e total de SOL.
`transaction-count`	Mostra a contagem de transações do cluster.
`transaction-history`	Lista as transações que envolvem um endereço, da mais recente para a mais antiga.
`transfer`	Transfere SOL entre contas do sistema.
`upgrade-nonce-account`	Atualiza de forma idempotente uma conta de nonce legada.
`validator-info`	Publica ou lê informações de validator.
`validators`	Mostra um resumo de stake, comissão, taxa de skip e versão dos validators.
`verify-offchain-signature`	Verifica uma mensagem off-chain assinada.
`vote-account`	Mostra as autoridades, a comissão, os créditos e os votos de uma conta de voto.
`vote-authorize-voter`	Altera a autoridade de votante de uma conta de voto.
`vote-authorize-voter-checked`	Altera a autoridade de votante verificando a nova autoridade como signatária.
`vote-authorize-withdrawer`	Altera a autoridade de saque de uma conta de voto.
`vote-authorize-withdrawer-checked`	Altera a autoridade de saque verificando a nova autoridade como signatária.
`vote-update-commission`	Altera a comissão de uma conta de voto.
`vote-update-validator`	Altera a identidade do validator atribuída a uma conta de voto.
`withdraw-from-nonce-account`	Saca parte ou todo o SOL de uma conta de nonce durável.
`withdraw-from-vote-account`	Saca lamports de uma conta de voto.
`withdraw-stake`	Saca SOL inativo de uma conta de stake.

Saída para scripts

Use --output json ou --output json-compact onde houver suporte, em vez de analisar a saída legível por humanos:

solana epoch-info --output json
solana account <ACCOUNT_ADDRESS> --output json-compact
solana validators --output json > validators.json

Nem todo comando oferece suporte a saída estruturada. Verifique a ajuda do comando antes de depender dela em automações e trate um status de saída diferente de zero como falha.