Noções Básicas da Solana CLI

10 exemplos para você começar com a Solana CLI - 7 básicos e 3 intermediários.

Pré-requisitos

Instale a toolchain Agave (Solana CLI 3.0.10 vem com Agave 4.1.1):

sh -c "$(curl -sSfL https://release.anza.xyz/v4.1.1/install)"
solana --version
# solana-cli 3.0.10

Adicione o diretório de instalação ao seu PATH se o instalador solicitar. Você precisa de um keypair padrão antes de enviar transações - veja Keypairs com solana-keygen.

Exemplos Básicos

1. Verificar Versão da CLI

Confirme que a CLI e tooling de cluster correspondem ao seu stack fixado.

solana --version
agave-install --version

• Imprime solana-cli 3.0.10 quando alinhado com Agave 4.1.1.
• Versões incompatíveis causam erros sutis de RPC e deploy.
• Fixe versões por projeto com agave-install (veja Gerenciamento de Versão).

Relacionado: Visão Geral da Toolchain - como as peças se encaixam

2. Ver Config Atual

Veja qual RPC URL, keypair e nível de commitment a CLI usa.

solana config get

• RPC URL é onde todo comando envia requests JSON-RPC.
• Keypair Path é a identidade de assinatura para transfers e deploys.
• Commitment padrão é confirmed - bom para workflows de dev.

Relacionado: Noções Básicas de RPC - níveis de commitment explicados

3. Apontar para Devnet

Mude a CLI para devnet pública da Solana para airdrops gratuitos e testes.

solana config set --url devnet
solana config get

• devnet resolve para o endpoint RPC público de devnet.
• SOL de devnet não tem valor real - reajuste expectativas de saldo.
• Use mainnet-beta apenas quando pretender gastar SOL real.

Relacionado: Airdrops e Saldos - financie sua wallet de dev

4. Apontar para Localnet

Direcione para instância solana-test-validator na sua máquina.

solana config set --url http://127.0.0.1:8899
solana config get

• Porta 8899 é a porta JSON-RPC padrão de solana-test-validator.
• Localnet dá iteração determinística e rápida sem rate limits.
• Restaure config para devnet quando terminar trabalho local.

Relacionado: solana-test-validator - iniciar cluster local

5. Definir Keypair Padrão

Diga à CLI qual keypair assina transações de saída.

solana config set --keypair ~/.config/solana/id.json
solana address

• solana address imprime a public key derivada do arquivo keypair.
• Nunca commite arquivos JSON de keypair no git.
• Use keypairs separados por ambiente (local, devnet, mainnet).

Relacionado: Keypairs com solana-keygen - gerar e recuperar keys

6. Verificar Saldo da Wallet

Leia lamports do keypair configurado.

solana balance
solana balance <PUBKEY>

• Saldo é mostrado em SOL; internamente a chain armazena lamports (1 SOL = 10^9 lamports).
• Saldo zero bloqueia fees de transação - faça airdrop em devnet primeiro.
• Use pubkey específica para inspecionar qualquer conta, não apenas seu padrão.

Relacionado: Airdrops e Saldos - solicite SOL de devnet

7. Inspecionar Saúde do Cluster

Verifique se o endpoint RPC está acessível e produzindo slots.

solana cluster-version
solana slot

• cluster-version confirma versão do software validator no cluster.
• slot retorna o slot atual - se estagnar, seu RPC pode estar unhealthy.
• Compare progressão de slot entre duas chamadas para detectar endpoint preso.

Relacionado: Provedores RPC - quando usar RPC dedicado

Exemplos Intermediários

8. RPC Customizado com API Key

Roteie a CLI por URL de provedor mantendo os mesmos comandos.

solana config set --url "https://devnet.helius-rpc.com/?api-key=YOUR_KEY"
solana config get
solana slot

• URLs de provedor adicionam folga de rate limit e melhor uptime que endpoints públicos.
• Armazene API keys em variáveis de ambiente, não no histórico do shell.
• A CLI não faz cache de respostas - todo comando atinge a URL configurada.

Relacionado: Provedores RPC - trade-offs de provedor

9. Definir Nível de Commitment

Ajuste quão finalizada uma leitura deve estar antes da CLI retornar.

solana config set --commitment finalized
solana config get

• processed é o mais rápido mas pode reverter em forks.
• confirmed é o sweet spot padrão para dev e a maioria dos scripts.
• finalized é o mais seguro para operações de tesouraria mas mais lento.

Relacionado: Noções Básicas de RPC - semântica de commitment

10. Exportar Config para Scripts

Capture settings para CI e colegas usarem o mesmo cluster e keypair.

solana config get --json > solana-config.json
cat solana-config.json

• Output JSON é legível por máquina para pipelines de automação.
• Não faça check-in de caminhos de keypair com keys de produção em repos compartilhados.
• Pareie config exportada com pins de versão agave-install para reprodutibilidade.

Relacionado: Boas Práticas da Solana CLI - workflows repetíveis de time

Versões do stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0 e LiteSVM 0.6.x.