La CLI de Solana
La CLI de Solana es la forma en que la mayoría de los desarrolladores interactúan por primera vez con un clúster sin escribir un cliente.
No es un runtime separado ni un canal de administración secreto.
Es un cliente RPC local y firmado: la configuración elige el clúster, un par de claves demuestra quién paga y actualiza, y cada subcomando convierte la intención en llamadas JSON-RPC y transacciones.
Conceptos básicos de la CLI de Solana cubre la instalación y solana config; Pares de claves con solana-keygen, Airdrops y Saldos, Inspección de Cuentas y Programas, Envío de SOL y Transacciones, Despliegue de Programas, CLI de spl-token y Registros y Depuración se encargan de cada tarea individual.
Esta página se sitúa debajo de esas recetas: cómo la CLI encaja en un ciclo de desarrollo completo y cuándo abandonar la terminal para usar clientes programáticos.
Resumen
- La CLI de Solana empaqueta la configuración del clúster, la identidad (pares de claves), la financiación, la inspección, las transferencias, el despliegue de programas, las operaciones con tokens y los registros en una única superficie operativa sobre RPC.
- Por Qué Importa: Casi todos los incidentes de "saldo incorrecto", "despliegue en la red incorrecta" o "¿quién firmó esto?" son un error de configuración o de par de claves, no un misterioso error en tu programa.
- Conceptos Clave: URL RPC / clúster, compromiso (commitment), par de claves predeterminado, solana-keygen, airdrop vs transferencia, muestra de cuenta y programa, despliegue de programa / autoridad de actualización, spl-token, registros de solana, CLI vs @solana/kit.
- Cuándo Usar: Para arrancar una máquina, financiar billeteras de desarrollo, probar rápidamente RPC, inspeccionar el estado después de una transacción fallida, desplegar o actualizar un programa, acuñar tokens de prueba o transmitir registros mientras iteras localmente.
- Limitaciones / Compensaciones: Genial para operaciones interactivas y pegamento de CI; débil como ruta de billetera de producto, remitente de alto volumen o cliente de aplicación con tipos seguros en comparación con @solana/kit 7.0.0 y SDKs generados.
- Temas Relacionados: Fijación de versión de instalación de Agave, validador local, envoltorios de despliegue de Anchor, compromiso RPC, autoridades de actualización de programas.
Fundamentos
Piensa en la CLI como tres capas apiladas en una familia de binarios.
La primera es la configuración: qué punto final RPC, qué ruta de par de claves y qué nivel de compromiso hereda cada comando posterior a menos que anules las banderas.
La segunda es la identidad: pares de claves Ed25519 en disco (o recuperados de frases semilla) que firman los pagos de tarifas, transferencias, despliegues y cambios de autoridad de actualización.
La tercera son los verbos: saldo, airdrop, transferencia, cuenta, despliegue de programa, registros y la herramienta complementaria spl-token que reutiliza el mismo modelo de configuración para el trabajo del Programa de Tokens.
Nada en esa pila elude las reglas del ledger que ya conoces.
Una transferencia todavía necesita un pagador de tarifas financiado, una vida útil reciente bajo el capó y firmas.
Un despliegue todavía crea cuentas de programa bajo el cargador, cuesta alquiler y tarifas, y registra una autoridad de actualización.
Una impresión de solana account sigue siendo el mismo registro de cuenta: lamports, datos, propietario, indicador ejecutable.
La CLI solo elimina la necesidad de ensamblar manualmente mensajes para trabajos comunes.
Solana CLI 3.0.10 en esta pila se envía con la ruta de instalación de la cadena de herramientas Agave 4.1.1.
Esa fijación mantiene las formas de RPC, el comportamiento de despliegue de programas y solana --version alineados con los validadores y los flujos de trabajo de Anchor 0.32.1 utilizados en otros lugares de esta documentación.
Las versiones desajustadas producen fallos sutiles que parecen errores de red pero son desajustes cliente/servidor.
La configuración es el fundamento más subestimado.
solana config get responde tres preguntas de las que dependen todos los comandos: dónde (URL RPC para mainnet-beta, devnet, testnet o local http://127.0.0.1:8899), quién (ruta del par de claves) y cuán confirmado (compromiso, a menudo confirmed para el día a día del desarrollo).
Apuntar a localnet mientras tus claves y memoria muscular asumen devnet, y los airdrops, saldos y las IDs de programa parecen "incorrectos" por la razón equivocada.
solana-keygen es el compañero de identidad, no una opción extra.
Hasta que exista un par de claves predeterminado y se establezca en la configuración, la CLI no puede pagar tarifas ni actuar como autoridad de actualización.
Trata las claves de despliegue, autoridad de actualización y desarrollo del día a día como roles separados, incluso si los tutoriales iniciales comparten un solo archivo.
Mecánica e Interacciones
El ciclo productivo de la CLI está ordenado, no es una bolsa de subcomandos al azar.
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 authority1. Configuración: elige el cerebro del clúster
Establece la URL RPC (y generalmente el par de claves) antes de cualquier cosa que modifique el estado.
Cada comprobación de saldo, airdrop, transferencia y despliegue es una llamada de cliente a esa URL; el binario no mantiene un segundo ledger oculto.
El trabajo con el validador local utiliza un RPC de bucle invertido; devnet público utiliza puntos finales amigables para el grifo (faucet); mainnet-beta utiliza SOL real y consecuencias de producción.
El compromiso (commitment) le dice a la CLI cuán asentado debe parecer un resultado antes de que trate una lectura o confirmación como suficiente para tu flujo de trabajo.
2. Par de claves: establece quién paga y quién controla
Genera o recupera un par de claves con solana-keygen, luego apunta la configuración a ese archivo.
La clave pública es tu dirección en la cadena; el material privado firma los mensajes que la CLI construye para ti.
Sin SOL en esa dirección en el clúster configurado, los comandos que pagan tarifas fallan incluso si el resto de la configuración es perfecta.
3. Financiación: haz que la identidad sea utilizable
En devnet y localnet, airdrop es la ruta habitual del grifo para cargar SOL para tarifas y alquiler.
En mainnet-beta no hay historia de grifo gratuito; financias desde una fuente externa y tratas cada despliegue y transferencia como un gasto real.
solana balance (para la clave predeterminada o una clave pública explícita) es la comprobación de cordura barata después de cambios de configuración o airdrop.
4. Inspección: lee antes de escribir
solana account y solana program show (y utilidades relacionadas de volcado/muestra) te permiten verificar propietarios, lamports, metadatos ejecutables y la autoridad de actualización del programa sin escribir una sonda de TypeScript.
La inspección es cómo confirmas que un despliegue aterrizó, que todavía existe un buffer, o que una cuenta sigue siendo propiedad del sistema de datos vacíos frente al estado propiedad del programa.
5. Envío y despliegue: muta con la misma identidad
Las transferencias mueven SOL bajo las reglas del Programa del Sistema utilizando el firmante configurado como pagador de tarifas (y generalmente como origen).
El despliegue de programas carga bytes sBPF compilados (.so) a través de flujos de carga: buffers, cuentas de programa y una autoridad de actualización que más tarde controla si ese programa puede cambiar.
Los proyectos de Anchor a menudo envuelven el despliegue en anchor deploy, pero la identidad del clúster subyacente y RPC siguen siendo la misma historia de configuración de la CLI.
6. Tokens y registros: mismo ciclo, herramientas más amplias
spl-token es una CLI hermana para la creación de acuñaciones (mint), ATAs, acuñación y transferencias contra el programa SPL Token.
Reutiliza las convenciones de clúster y par de claves para que no mantengas un segundo modelo mental para el "mundo de los tokens".
solana logs, solana confirm y la inspección de transacciones cierran el ciclo de depuración cuando un envío o despliegue falla: transmite los registros del programa, fija una firma y ve si el problema fue la simulación, fondos insuficientes o error del programa en cadena.
Una comprobación orientativa mínima después de la instalación se ve así (no es un volcado completo de recetas):
solana --version # espera solana-cli 3.0.10 con Agave 4.1.1
solana config get # URL RPC, ruta del par de claves, compromiso
solana balance # ¿identidad financiada en este clúster?Las recetas de comandos detalladas se encuentran en las páginas hermanas; la mecánica a mantener es configuración → identidad → fondos → inspección → mutación → registros.
Consideraciones y Aplicaciones Avanzadas
La habilidad difícil no es memorizar banderas.
Es saber cuándo la CLI es la herramienta adecuada frente a cuándo deberías mover las mismas ideas a scripts, CI o clientes @solana/kit 7.0.0.
| Trabajo | Prefiere CLI | Prefiere programático (kit / scripts / clientes Anchor) | Por qué |
|---|---|---|---|
| Configuración inicial de máquina | Sí | No | La configuración interactiva, keygen y la fijación de versión son nativas de la terminal |
| Airdrop / saldo / vistazo de cuenta único | Sí | Opcional | Retroalimentación rápida; sin andamiaje de aplicaciones |
| Operaciones de despliegue de programas y autoridad de actualización | A menudo | Los envoltorios de CI aún llaman a la CLI o a Anchor | Con forma de operación; requiere un manejo cuidadoso de claves |
| Experiencia de usuario de billetera de producto y envíos de dapp | No | Sí (@solana/kit, adaptador de billetera) | UX, reintentos, simulación, instrucciones tipadas |
| Despliegue de transacciones de alto volumen o concurrentes | No | Sí | Mercados de tarifas, actualización de blockhash, remitentes personalizados |
| Pruebas de humo de acuñación SPL | CLI spl-token | Kit/scripts para acuñaciones de producción | CLI para ensayo; el producto necesita políticas y automatización |
| Pruebas de regresión en CI | Comprobaciones finas de CLI | Pruebas de Anchor, LiteSVM, Surfpool, scripts de kit | Determinismo y aserciones superan a los shell ad hoc |
| "Qué es esta cuenta" en incidentes | Sí | Más indexadores si la escala lo exige | La CLI es la verdad fundamental rápida contra RPC |
La fijación de versiones es un hábito avanzado de higiene, no una cortesía para principiantes.
Los equipos se estandarizan en la instalación de Agave / CLI 3.0.10 para que los artefactos de despliegue y el comportamiento de RPC coincidan con las máquinas de los revisores.
La separación de claves es el otro hábito avanzado: un par de claves predeterminado de portátil para devnet está bien; el mismo archivo que la autoridad de actualización de mainnet no lo está.
Utiliza --keypair explícito y ceremonias fuera de línea o de hardware cuando la autoridad importe.
Anchor 0.32.1 y Rust 1.91.1 se sientan junto a la CLI en lugar de dentro de ella: construyes con cargo/Anchor, luego despliegas e inspeccionas con Solana CLI (o el envoltorio fino de Anchor sobre los mismos conceptos).
@solana/kit 7.0.0 implementa el mismo modelo RPC y de transacciones en TypeScript para el código de aplicación; la CLI sigue siendo la consola del operador para la misma cadena.
Al depurar "funciona en la CLI, falla en la aplicación", compara la URL RPC, el compromiso, el pagador de tarifas y si la aplicación actualiza los blockhashes y simula.
Conceptos Erróneos Comunes
- "La CLI es una API diferente a la que usa mi aplicación." Ambas hablan JSON-RPC a un clúster; la CLI es un cliente empaquetado, no una segunda ruta de consenso.
- "solana config es opcional una vez que paso banderas a veces." Los valores predeterminados todavía muerden los comandos que olvidas anular; trata la configuración como la fuente de verdad de la sesión.
- "Airdrop funciona en todas partes." Los grifos son para clústeres de desarrollo/prueba; la financiación de mainnet son SOL reales de fuera de los comandos de grifo.
- "Un par de claves es suficiente para siempre." Desarrollo, despliegue, tesorería y autoridad de actualización son roles de riesgo diferentes; combínalos solo cuando aceptes el radio de explosión.
- "anchor deploy significa que puedo ignorar Solana CLI." Anchor todavía depende de la URL del clúster, las claves, y a menudo de la misma fijación de instalación; la inspección de la CLI y los registros siguen siendo esenciales.
- "Si el saldo no es cero, los despliegues siempre tendrán éxito." Los despliegues necesitan suficiente SOL para tarifas, cuentas de programa exentas de alquiler y flujos de buffer; "algún saldo" no es un modelo de costo.
- "spl-token es una herramienta no relacionada." Comparte patrones de configuración e identidad; el estado del token sigue siendo cuentas en el mismo clúster.
- "Los registros reemplazan a las pruebas."
solana logsexplica un fallo en vivo; no prueba la corrección a través de actualizaciones como lo hacen las pruebas automatizadas.
Preguntas Frecuentes
¿Qué es la CLI de Solana en una frase?
Una cadena de herramientas local que configura RPC y pares de claves, y luego construye y firma operaciones comunes de Solana (saldos, transferencias, despliegues, inspección, registros) contra un clúster.
¿Cómo se relaciona la CLI con Agave 4.1.1?
Esta pila de documentación fija Solana CLI 3.0.10 con la línea de instalación Agave 4.1.1 para que el comportamiento del cliente coincida con las herramientas del validador actual; instala y verifica la versión con el flujo de trabajo del instalador de Agave utilizado en Conceptos básicos de la CLI de Solana.
¿Qué controla realmente solana config?
Principalmente la URL RPC predeterminada (clúster), la ruta del par de claves predeterminado y el nivel de compromiso que heredan otros comandos a menos que se anulen.
¿Por qué necesito solana-keygen si ya instalé solana?
La instalación te da el cliente; keygen crea o recupera la identidad de firma que el cliente utiliza para pagar tarifas y autorizar despliegues.
¿Cuál es la diferencia entre airdrop y transfer?
Airdrop solicita fondos del grifo en clústeres no mainnet compatibles; transfer mueve SOL existente desde una cuenta financiada que controlas a otra dirección.
¿Cuándo debo usar localnet vs devnet vs mainnet-beta?
Localnet para iteración rápida sin conexión con solana-test-validator; devnet para pruebas públicas compartidas y grifos; mainnet-beta solo cuando pretendes valor real y IDs de programa de producción.
¿Cómo encaja el despliegue de programas en el mismo flujo de trabajo que la transferencia?
Ambos requieren configuración correcta y un firmante financiado; el despliegue además carga los bytes del programa bajo el cargador y establece metadatos de autoridad de actualización que puedes inspeccionar con program show.
¿Dónde encaja spl-token si es un binario separado?
Es una CLI complementaria para operaciones del Programa de Tokens que reutiliza la misma mentalidad de clúster y par de claves; úsala para ensayos de acuñación/ATA antes de codificar los mismos flujos en clientes de aplicaciones.
¿Cómo depuro una transacción fallida de la CLI?
Confirma primero la configuración y el saldo, vuelve a ejecutar con comandos de inspección, luego usa solana confirm / vistas de transacciones y solana logs como se cubre en Registros y Depuración.
¿Deben las dapps de producción enviar transacciones de usuario a través de la CLI?
No. Usa clientes conectados a billeteras y bibliotecas como @solana/kit 7.0.0 para rutas de producto; reserva la CLI para operadores, CI y arranque.
¿Puede Anchor reemplazar el aprendizaje de la CLI de Solana?
No. Anchor acelera el flujo de trabajo del programa, pero la configuración, las claves, los airdrops, la inspección, la semántica de despliegue en bruto y los registros todavía se exponen a través de conceptos de la CLI de Solana, incluso cuando están envueltos.
¿Qué compromiso debo usar mientras desarrollo?
confirmed es un valor predeterminado común de la CLI para el trabajo interactivo; ajústalo o relájalo deliberadamente cuando te importe ver el estado aún no finalizado frente a esperar una mayor finalidad.
¿Por qué mi saldo parece incorrecto después de cambiar de clúster?
Los saldos son por clúster; el mismo par de claves en devnet y mainnet-beta son diferentes ledgers con saldos de lamports independientes.
¿Es la CLI segura para las claves de autoridad de actualización de mainnet?
Puede serlo, si las claves están protegidas, los comandos son explícitos y evitas pares de claves predeterminados casuales; muchos equipos todavía prefieren ceremonias con scripts, hardware o gobernanza multisig en lugar de un archivo JSON desbloqueado en un portátil.
¿Qué debo aprender a continuación después de esta página?
Instalación y configuración en Conceptos básicos de la CLI de Solana, luego keygen, financiación, inspección, envío/despliegue, tokens y registros en la lista Relacionados a continuación.
Relacionados
- Conceptos básicos de la CLI de Solana - instalación,
solana configy elección de un clúster - Pares de claves con solana-keygen - genera, recupera y gestiona identidades de firma
- Airdrops y Saldos - financia billeteras de desarrollo y lee saldos de SOL
- Inspección de Cuentas y Programas -
solana accounty metadatos del programa - Envío de SOL y Transacciones - transferencias y confirmación desde la terminal
- Despliegue de Programas -
solana program deploy, buffers y autoridad de actualización - CLI de spl-token - acuñaciones, ATAs y transferencias de tokens
- Registros y Depuración -
solana logse inspección de transacciones
Versiones de la pila: Esta página fue escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1 y @solana/kit 7.0.0.