SDK · Manuales
Descargas

La consola interactiva

La consola (xamisdk console) es una forma cómoda de usar el xamiSDK: en vez de teclear comandos largos, abres una sesión interactiva y trabajas con comandos cortos. Es una opción adicional — todos los comandos sueltos (serve, pades:sign, etc.) siguen funcionando igual.

Cómo abrirla

Con el SDK ya instalado y pareado, ejecuta:

xamisdk console

Verás el banner y el prompt xami> esperando comandos:

xamisdk console
   _  __ ___    __  _______   ____  __  ___   __
  | |/ //   |  /  |/  /  _/  / __ \/ / / / | / /
  |   // /| | / /|_/ // /   / /_/ / / / /  |/ /
 /   |/ ___ |/ /  / // / _ / _, _/ /_/ / /|  /
/_/|_/_/  |_/_/  /_/___/(_)_/ |_|\____/_/ |_/

        Firma digital y blockchain  ·  consola interactiva

  Conectado como tenant 5  |  endpoint https://api.xami.run
  Escribe 'help' para ver los comandos, 'exit' para salir.

xami> start
  servicio iniciado en segundo plano (puerto 8300, modo pull (cada 2s))
  usa 'logs' para ver su salida
xami> credentials
  5 credencial(es) en cache:
    b52c2ec0-...  tipo=pades  device=Xami-A1  default_design=531ba341-...
xami> sign documento.pdf b52c2ec0-... name="Jose Zarate"
  Preparando y enviando el hash a Xami (el documento NO sale)...
  requestId: sig_4dd0...
  Firmado -> documento_firmado.pdf
xami> logs -f
  (siguiendo el log en vivo — Ctrl+C para volver)
  2026-08-07 09:15:02  INFO  servicio listo — esperando peticiones
  2026-08-07 09:15:47  WARN  no se pudo consultar a Xami: HTTP 503
  2026-08-07 09:15:49  INFO  conexion con Xami restablecida
  2026-08-07 09:16:10  ERROR fallo inesperado en el polling
  ^C
  (fin del seguimiento)
xami> exit
  hasta luego.

Si aún no estás pareado, la consola te lo dirá. Ejecuta xamisdk init primero (ver Instalar).

Al iniciar el servicio: manejo del puerto

Cuando ejecutas start, la consola comprueba si el puerto ya está en uso y actúa según lo que encuentre:

↻
Si el puerto lo ocupa otro servicio xamiSDK
Lo detecta (por ejemplo, un servicio que quedó corriendo de una sesión anterior) y lo reinicia automáticamente, para no dejar dos servicios en el mismo puerto haciendo eco. Verás: había un servicio xamiSDK anterior en el puerto 8300; lo reinicio.
⚠
Si el puerto lo ocupa otro programa
No lo toca (nunca cierra un proceso ajeno) y te avisa para que uses otro puerto: el puerto 8300 está ocupado por otro programa (no es xamiSDK). Usa otro puerto: start <otro_puerto>.

Comandos de la consola

Dentro del prompt xami>, estos son los comandos disponibles:

credentials
Lista las credenciales que el SDK tiene en caché, con su credential_key. Es lo que puedes usar para firmar.
designs
Lista los diseños de sello en caché, con su design_key.
sync
Vuelve a descargar las credenciales y los diseños desde Xami y reemplaza la caché local con esa información fresca, sin reiniciar el servicio. Lo que ya no exista en el servidor (por ejemplo credenciales de un chip dado de baja) se elimina también de la caché. Úsalo cuando cambiaste un diseño o una credencial en la consola de Xami y quieres que el SDK lo tome de inmediato.
reinstall [--force]
Actualiza el SDK a la última versión publicada. Comprueba si hay una versión más reciente; si la hay, lanza una ventana nueva que hace todo el ciclo: detiene el servicio, reinstala, lo levanta de nuevo y abre la consola. Si ya estás al día no hace nada (usa --force para reinstalar igual). La consola actual se cierra: un programa no puede reemplazarse a sí mismo mientras corre.
wrappers
Lista las credenciales de wrapper (las que usan tus apps con XamiLib), con su wrapper_key, estado y último uso.
wrapper create <nombre>
Crea una nueva credencial de wrapper para una app. Muestra el wrapper_key y el secret (el secret no se vuelve a mostrar, guárdalo).
wrapper revoke <key>
Revoca una credencial de wrapper por su wrapper_key. Esa app deja de poder usar el SDK.
sign <pdf> <credential_key> [variable=valor ...]
Firma un PDF. Indicas la ruta del documento, la credencial y, si el diseño lo requiere, variables (por ejemplo name="Jose Zarate"). El PDF firmado se guarda junto al original. No necesita que el servicio esté levantado para lanzarse, pero sí para recibir el resultado.
report <requestId>
Arma un reporte técnico de una firma y lo envía a Xami para dar soporte. Antes de enviar, te muestra exactamente qué se incluirá y te pide confirmación. El paquete lleva la versión del SDK, el estado de la caché (sin secretos) y el registro detallado de ese requestId; no se envía tu llave privada, tu token ni el contenido de tus documentos. Xami responde con un número de incidente que puedes mencionar al pedir soporte. El requestId aparece en verde tras firmar y en el log.
start [puerto]
Inicia el servicio (serve) en segundo plano, en modo pull. La consola sigue disponible mientras el servicio corre. Puerto por defecto: 8300. Si el puerto ya está ocupado por otro servicio xamiSDK (por ejemplo uno que quedó de una sesión anterior), lo detecta y lo reinicia automáticamente; si lo ocupa otro programa, no lo toca y te avisa para que uses otro puerto.
stop
Detiene el servicio que iniciaste con start.
restart
Reinicia el servicio (equivale a stop seguido de start). Útil para que el SDK vuelva a sincronizar su configuración desde Xami.
logs
Muestra las últimas líneas del registro de actividad: arranque del servicio, firmas (envío y recepción), comandos ejecutados y errores. Es un registro unificado: reúne lo que ocurre en el servicio y en los comandos que ejecutas, en orden cronológico.
logs -f · follow
Sigue el log en vivo (como tail -f): las nuevas líneas aparecen según llegan, coloreadas por nivel — INFO en verde, WARN en amarillo, y las líneas de ERROR completas en rojo. Presiona Ctrl+C para volver al prompt. También disponible como follow.
status
Muestra el estado general: si estás pareado, el tenant, el endpoint, cuántas credenciales y diseños hay en caché, y si el servicio está corriendo.
clear
Limpia la pantalla de la consola. También disponible como cls.
help [comando]
Sin argumento, muestra la lista de comandos. Con un comando (por ejemplo help sign), muestra la documentación detallada de ese comando: uso, descripción, ejemplos y notas.
exit · quit
Sale de la consola. Si el servicio quedó corriendo, te pregunta si quieres detenerlo o dejarlo en segundo plano.

Diferencia con los comandos sueltos

La consola no reemplaza nada: por dentro usa los mismos comandos que puedes ejecutar directamente desde la terminal. La ventaja es que, una vez dentro, no repites xamisdk ni las opciones largas, y puedes tener el servicio corriendo mientras firmas y consultas — todo en un solo lugar. Para automatizaciones y scripts, sigue siendo mejor usar los comandos sueltos (ver Comandos).