A Solana CLI

A Solana CLI é como a maioria dos desenvolvedores fala com um cluster pela primeira vez sem escrever client.

Não é runtime separado nem canal admin secreto.

É um client RPC local e assinado: config escolhe o cluster, keypair prova quem paga e faz upgrades, e cada subcomando transforma intenção em chamadas JSON-RPC e transações.

Noções Básicas da Solana CLI percorre instalação e solana config; Keypairs com solana-keygen, Airdrops e Saldos, Inspecionando Contas e Programas, Enviando SOL e Transações, Implantando Programas, spl-token CLI e Logs e Depuração possuem cada um um trabalho.

Esta página fica abaixo dessas receitas: como a CLI se encaixa em um loop completo de desenvolvedor e quando sair do terminal para clients programáticos.

Resumo

• A Solana CLI empacota config de cluster, identidade (keypairs), funding, inspeção, transfers, deploy de programa, ops de token e logs em uma superfície operacional sobre RPC.
• Por Que Importa: Quase todo incidente de "saldo errado", "deploy na rede errada" ou "quem assinou isso?" é erro de config ou keypair, não bug misterioso no seu programa.
• Conceitos-Chave: RPC URL / cluster, commitment, keypair padrão, solana-keygen, airdrop vs transfer, account e program show, deploy de programa / upgrade authority, spl-token, solana logs, CLI vs @solana/kit.
• Quando Usar: Bootstrap de máquina, financiar wallets dev, smoke-test RPC, inspecionar state após tx falhada, implantar ou fazer upgrade de programa, mintar tokens de teste ou streamar logs enquanto itera localmente.
• Limitações / Trade-offs: Ótima para ops interativas e glue CI; fraca como caminho de wallet de produto, submitter de alto volume ou client de app type-safe comparado a @solana/kit 7.0.0 e SDKs gerados.
• Tópicos Relacionados: Pin de install Agave, validator local, wrappers deploy Anchor, commitment RPC, upgrade authorities de programa.

Fundamentos

Pense na CLI como três camadas empilhadas em uma família de binários.

Primeiro é config: qual endpoint RPC, qual caminho de keypair e qual nível de commitment todo comando subsequente herda a menos que você sobrescreva flags.

Segundo é identidade: keypairs Ed25519 em disco (ou recuperados de seed phrases) que assinam pagamentos de fee, transfers, deploys e mudanças de upgrade authority.

Terceiro são verbos: balance, airdrop, transfer, account, program deploy, logs e ferramenta irmã spl-token que reutiliza o mesmo modelo de config para trabalho do Token Program.

Nada nessa pilha contorna regras do ledger que você já conhece.

Transfer ainda precisa de fee payer financiado, lifetime recente por baixo e assinaturas.

Deploy ainda cria contas de programa sob o loader, custa rent e fees e registra upgrade authority.

Print solana account ainda é o mesmo registro de conta: lamports, data, owner, flag executable.

A CLI apenas remove a necessidade de montar mensagens manualmente para trabalhos comuns.

Solana CLI 3.0.10 neste stack vem com o caminho de install da toolchain Agave 4.1.1.

Esse pin mantém shapes RPC, comportamento de deploy de programa e solana --version alinhados com validators e workflows Anchor 0.32.1 usados em outros lugares destes docs.

Versões incompatíveis produzem falhas sutis que parecem bugs de rede mas são skew client/server.

Config é a fundação mais subestimada.

solana config get responde três perguntas de que todo comando depende: onde (RPC URL para mainnet-beta, devnet, testnet ou local http://127.0.0.1:8899), quem (caminho keypair) e quão confirmado (commitment, frequentemente confirmed para dev do dia a dia).

Aponte para localnet enquanto suas keys e memória muscular assumem devnet, e airdrops, saldos e program IDs parecem "errados" pelo motivo errado.

solana-keygen é o companheiro de identidade, não extra opcional.

Até existir keypair padrão e estar definido em config, a CLI não pode pagar fees nem atuar como upgrade authority.

Trate keys de deployer, upgrade authority e dev do dia a dia como papéis separados mesmo que tutoriais iniciais compartilhem um arquivo.

Mecânica e Interações

O loop produtivo da CLI é ordenado, não saco de subcomandos.

  config          keypair           fund              inspect
  --------        --------          ----              -------
  RPC URL   ──►   default id   ──►  airdrop/SOL  ──►  account /
  keypair path    (solana-keygen)   balance           program show
  commitment            │                │                 │
                        │                │                 │
                        ▼                ▼                 ▼
                   send / deploy  ─────────────────►  logs / confirm
                   transfer             program deploy     debug loop
                   spl-token mint       upgrade authority

1. Config: escolha o cérebro do cluster

Defina RPC URL (e geralmente keypair) antes de qualquer coisa que mute state.

Todo check de saldo, airdrop, transfer e deploy é chamada client para essa URL; o binário não mantém ledger oculto segundo.

Trabalho com validator local usa RPC loopback; devnet pública usa endpoints amigáveis a faucet; mainnet-beta usa SOL real e consequências de produção.

Commitment diz à CLI quão estabilizado um resultado deve parecer antes de tratar leitura ou confirmação como bom o suficiente para seu workflow.

2. Keypair: estabeleça quem paga e controla

Gere ou recupere keypair com solana-keygen, depois aponte config para esse arquivo.

A public key é seu endereço on-chain; material privado assina mensagens que a CLI constrói para você.

Sem SOL nesse endereço no cluster configurado, comandos que pagam fee falham mesmo se o resto do setup estiver perfeito.

3. Fund: torne a identidade utilizável

Em devnet e localnet, airdrop é o caminho faucet usual para carregar SOL para fees e rent.

Em mainnet-beta não há história de faucet grátis; você financia de fonte externa e trata todo deploy e transfer como gasto real.

solana balance (para key padrão ou pubkey explícita) é o sanity check barato após mudanças de config ou airdrop.

4. Inspect: leia antes de escrever

solana account e solana program show (e helpers dump/show relacionados) deixam você verificar owners, lamports, metadata executável e upgrade authority de programa sem escrever probe TypeScript.

Inspeção é como você confirma que deploy pousou, buffer ainda existe ou conta ainda é data vazia system-owned versus state owned por programa.

5. Send e deploy: mute com a mesma identidade

Transfers movem SOL sob regras do System Program usando signer configurado como fee payer (e geralmente como source).

Deploy de programa faz upload de bytes sBPF (.so) compilados através de fluxos loader: buffers, contas de programa e upgrade authority que depois controla se esse programa pode mudar.

Projetos Anchor frequentemente envolvem deploy em anchor deploy, mas identidade de cluster e RPC subjacente ainda são a mesma história de config CLI.

6. Tokens e logs: mesmo loop, ferramentas mais amplas

spl-token é CLI irmã para criação de mint, ATAs, minting e transfers contra o programa SPL Token.

Reutiliza convenções de cluster e keypair para você não manter segundo modelo mental para "mundo token".

solana logs, solana confirm e inspeção de transação fecham o loop de debug quando send ou deploy falha: stream logs de programa, fixe signature e veja se o problema foi simulação, fundos insuficientes ou erro de programa on-chain.

Check orientador mínimo após install parece assim (não dump completo de receita):

solana --version          # expect solana-cli 3.0.10 with Agave 4.1.1
solana config get         # RPC URL, keypair path, commitment
solana balance            # identity funded on this cluster?

Receitas de comando profundas vivem nas páginas irmãs; a mecânica a guardar é config → identity → funds → inspect → mutate → logs.

Considerações Avançadas e Aplicações

A habilidade difícil não é memorizar flags.

É saber quando a CLI é a ferramenta certa versus quando mover as mesmas ideias para scripts, CI ou clients @solana/kit 7.0.0.

Pin de versão é hábito de higiene avançado, não capricho de iniciante.

Times padronizam install Agave / CLI 3.0.10 para artefatos de deploy e comportamento RPC corresponderem às máquinas dos revisores.

Separação de keys é o outro hábito avançado: key padrão de laptop para devnet é ok; o mesmo arquivo como upgrade authority mainnet não é.

Use --keypair explícito e cerimônias hardware ou offline quando authority importa.

Anchor 0.32.1 e Rust 1.91.1 ficam ao lado da CLI em vez de dentro: você constrói com cargo/Anchor, depois implanta e inspeciona com Solana CLI (ou wrapper fino do Anchor sobre os mesmos conceitos).

@solana/kit 7.0.0 implementa o mesmo modelo RPC e transação em TypeScript para código de aplicação; a CLI permanece console do operador para a mesma chain.

Ao depurar "funciona na CLI, falha no app", compare RPC URL, commitment, fee payer e se o app atualiza blockhashes e simula.

Equívocos Comuns

• "A CLI é API diferente da que meu app usa." Ambos falam JSON-RPC com cluster; CLI é client empacotado, não segundo caminho de consenso.
• "solana config é opcional se passo flags às vezes." Defaults ainda mordem comandos que você esquece de sobrescrever; trate config como fonte de verdade da sessão.
• "Airdrop funciona em todo lugar." Faucets são para clusters dev/test; funding mainnet é SOL real de fora dos comandos faucet.
• "Um arquivo keypair basta para sempre." Dev, deploy, tesouraria e upgrade authority são papéis de risco diferentes; combine apenas se aceitar o raio de explosão.
• "anchor deploy significa que posso ignorar Solana CLI." Anchor ainda depende de URL de cluster, keys e frequentemente do mesmo pin de install; inspeção CLI e logs permanecem essenciais.
• "Se saldo é não-zero, deploys sempre sucedem." Deploys precisam SOL suficiente para fees, contas de programa isentas de rent e fluxos buffer; "algum saldo" não é modelo de custo.
• "spl-token é tooling não relacionado." Compartilha padrões de config e identidade; state de token ainda são contas no mesmo cluster.
• "Logs substituem testes." solana logs explica falha live; não prova correção entre upgrades como testes automatizados.

FAQs

Relacionado

• Noções Básicas da Solana CLI - instalação, solana config e escolha de cluster
• Keypairs com solana-keygen - gerar, recuperar e gerenciar identidades de assinatura
• Airdrops e Saldos - financiar wallets dev e ler saldos SOL
• Inspecionando Contas e Programas - solana account e metadata de programa
• Enviando SOL e Transações - transfers e confirmação pelo terminal
• Implantando Programas - solana program deploy, buffers e upgrade authority
• spl-token CLI - mints, ATAs e transfers de token
• Logs e Depuração - solana logs e inspeção de transação

Versões do stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1 e @solana/kit 7.0.0.