Referencia de la CLI

Esta referencia se agrupa por forma de comando:

• el comando principal de publicación: pubm [version]
• comandos de gestión como init, secrets y sync
• comandos del flujo de changesets bajo pubm changesets ...
• el comando pubm snapshot para releases de previsualización y pruebas

Para el uso diario, el comando principal es:

pubm

Ejecutar pubm sin argumento de versión sigue el flujo interactivo normal. Te permite elegir la siguiente versión en la terminal antes de que continúe el pipeline de release.

Resumen de comandos

Comando	Propósito
pubm [version]	Ejecuta el pipeline de publicación usando un tipo de release o un semver explícito.
pubm snapshot [tag]	Publica versiones snapshot para previsualización y pruebas.
pubm init	Asistente de configuración interactivo para detección de paquetes, configuración, changesets, workflows de CI y skills de agentes de código.
pubm setup-skills	Descarga e instala skills de agentes de código (Claude Code, Codex, Gemini).
pubm secrets sync	Sube tokens guardados localmente a GitHub Secrets a través de gh.
pubm sync --discover	Escanea el repositorio en busca de referencias de versión fuera de los archivos manifest.
pubm update	Actualiza el CLI a la última versión publicada.
pubm changesets add	Crea un nuevo changeset.
pubm changesets status	Muestra los changesets pendientes y su impacto en bumps.
pubm changesets version	Consume los changesets y escribe nuevas versiones.
pubm changesets changelog	Genera texto de changelog a partir de changesets pendientes.
pubm changesets migrate	Migra desde .changeset/ a .pubm/.

Comando principal de publicación

Sintaxis

pubm [version] [flags]

[version] puede ser:

• un tipo de bump semver: patch, minor, major
• un tipo de bump de pre-release: prepatch, preminor, premajor, prerelease
• una versión explícita como 1.8.0

Si omites la versión:

• las terminales interactivas pueden preguntar por la siguiente versión
• las ejecuciones en CI requieren que la versión se resuelva sin interacción

Uso interactivo

pubm

Flujo típico:

1. ejecuta pubm
2. elige patch, minor o major
3. deja que pubm continúe con checks, build, tagging y publicación

Ejemplos comunes

pubm
pubm --dry-run
pubm 1.8.0
pubm --registry npm,jsr
pubm --tag beta

Flags de publicación

Flag	Por defecto	Descripción
-d, --dry-run	false	Muestra el grafo de tareas sin mutar el estado de Git ni publicar.
--mode <mode>	local	Modo de ejecución: local (interactivo) o ci (no interactivo, basado en tags).
--phase <phase>	-	Fase del pipeline: prepare (validar y dry-run) o publish (publicar desde el último tag).
--release-draft	false	Crea un GitHub Release en borrador en lugar de uno publicado.
-b, --branch <name>	main	Exige que el branch actual coincida antes de publicar.
-a, --any-branch	false	Desactiva la protección por branch para la ejecución actual.
-t, --tag <name>	latest	Usa un dist-tag específico como beta o next.
-c, --contents <path>	none	Cambia a un subdirectorio antes de ejecutar el pipeline de release.
--registry <registries>	npm,jsr	Registries destino separados por coma. Soporta npm, jsr, crates o URLs personalizadas de registry.
--test-script <script>	test	Nombre del script usado para el paso de test.
--build-script <script>	build	Nombre del script usado para el paso de build.
--no-save-token	false	No persiste los tokens compatibles para ejecuciones futuras.
--dangerously-allow-unpublish	false	Permite el unpublish/yank del registry durante el rollback en entornos sin TTY.
--locale <locale>	en	Establece el idioma de salida del CLI. Admitidos: en, ko, zh-cn, fr, de, es.
--create-pr	false	Crea un pull request para el version bump en lugar de hacer push directamente.

Flags de control del pipeline

Flag	Descripción
--no-pre-check	Omite comprobaciones previas como la validación de branch y working tree.
--no-condition-check	Omite comprobaciones de condiciones requeridas como la validación de tokens y registries.
--no-tests	Omite el paso de tests.
--no-build	Omite el paso de build.
--no-publish	Ejecuta el pipeline hasta publish, pero no publica artefactos realmente.
--skip-release	Omite la creación de GitHub Release.

Modos de ejecución

Ejecución local interactiva

El modo normal para releases locales:

pubm

Comportamiento:

• empieza con selección interactiva de versión cuando no se proporciona argumento de versión
• los prompts pueden aparecer cuando falta información requerida
• tests y build se ejecutan salvo que se omitan
• versionado, publicación, push y pasos de GitHub Release se ejecutan en orden

Modo dry-run

pubm --dry-run

Usa el modo dry-run cuando necesites inspeccionar el plan de tareas sin efectos secundarios.

Modo de preparación de CI

pubm --mode ci --phase prepare

Preparación de CI:

• recopila tokens faltantes de forma interactiva
• puede sincronizarlos con GitHub Secrets
• cambia a comportamiento no interactivo para imitar CI
• ejecuta comprobaciones previas y de condiciones
• simula la publicación para los registries configurados

Modo de publicación en CI

pubm --mode ci --phase publish

El modo de publicación en CI publica desde el último Git tag y crea un GitHub Release mediante la API. Úsalo cuando el bump de versión y el tagging ya hayan ocurrido antes en el pipeline. Pasa --release-draft para crear un release en borrador en lugar de uno publicado.

Variables de entorno

Variable	Uso
NODE_AUTH_TOKEN	Autenticación de npm en CI
JSR_TOKEN	Autenticación de jsr
CARGO_REGISTRY_TOKEN	Autenticación de crates.io
PUBM_LOCALE	Idioma de salida del CLI (en, ko, zh-cn, fr, de, es)

Los prompts se desactivan automáticamente cuando:

• stdin no es un TTY
• el proceso se ejecuta en una plataforma CI reconocida

pubm snapshot

Publica versiones snapshot para previsualización y pruebas. Compatible con proyectos de paquete único y monorepo.

pubm snapshot [tag]

Opción	Descripción
[tag]	Tag del snapshot (por defecto: snapshot)
-f, --filter <name>	Filtrar paquetes por nombre o ruta (repetible)
-d, --dry-run	Simular sin efectos secundarios
--no-tests	Omitir tests
--no-build	Omitir build
-b, --branch <name>	Rama destino (por defecto: main)
-a, --any-branch	Permitir publicar desde cualquier rama

Ejemplos

# Snapshot de todos los paquetes
pubm snapshot

# Snapshot con tag personalizado
pubm snapshot beta

# Snapshot de paquetes específicos
pubm snapshot --filter @pubm/core --filter pubm

pubm init

Asistente de configuración interactivo para pubm. Requiere un TTY.

pubm init

El asistente pasa por estas etapas:

1. Detección de paquetes: escanea el repositorio en busca de archivos manifest (package.json, jsr.json, deno.json, deno.jsonc, Cargo.toml) y la configuración del workspace, y confirma los paquetes y registries detectados.
2. Configuración básica: solicita el branch de release y la estrategia de versionado (independent o fixed).
3. Opciones de release: pregunta sobre la generación de changelog y los borradores de GitHub Release.
4. Configuración de workflows: ofrece activar el workflow de changesets (crea .pubm/changesets/, .github/workflows/changeset-check.yml y actualiza .gitignore) y generar workflows de release para CI (.github/workflows/release.yml).
5. Skills de agentes de código: ofrece descargar e instalar skills de agentes de código para Claude Code, Codex CLI o Gemini CLI. Esto equivale a pubm setup-skills.

El archivo pubm.config.ts solo se crea cuando tus elecciones difieren de los valores por defecto. Si todos los valores coinciden con el comportamiento por defecto, no se escribe ningún archivo de configuración.

Este comando no acepta flags ni opciones: toda la configuración se recopila de forma interactiva.

pubm setup-skills

Descarga e instala skills de agentes de código para usarlas con pubm.

pubm setup-skills

Agentes admitidos y sus rutas de instalación:

Agente	Directorio de skills
Claude Code	.claude/skills/pubm/
Codex CLI	.agents/skills/pubm/
Gemini CLI	.gemini/skills/pubm/

Las skills se descargan desde el repositorio de GitHub de pubm (última etiqueta de release, con fallback a la rama main).

Este comando también está disponible como paso final de pubm init.

pubm secrets sync

Sube tokens guardados localmente a GitHub Secrets usando el CLI gh.

pubm secrets sync
pubm secrets sync --registry npm
pubm secrets sync --registry npm,jsr

Flag	Por defecto	Descripción
--registry <registries>	npm,jsr,crates	Limita la sincronización de secrets a registries concretos.

Notas:

• requiere que gh esté instalado y autenticado
• usa tokens almacenados localmente, así que ejecuta primero pubm --mode ci --phase prepare si todavía no se ha guardado nada

pubm sync --discover

Escanea el repositorio en busca de referencias de versión fuera de los archivos manifest.

pubm sync --discover

Este comando está pensado para ayudar a configurar plugins de version-sync. Omite directorios generados y lockfiles comunes, y luego imprime archivos candidatos y rutas JSON o líneas coincidentes que puedes adaptar a la configuración del plugin.

pubm update

Actualiza el CLI pubm instalado a la última versión publicada.

pubm update

Comandos de changesets

Todos los comandos del ciclo de vida de changesets viven bajo pubm changesets.

pubm changesets add

Crea un nuevo changeset.

pubm changesets add
pubm changesets add --empty
pubm changesets add --packages @acme/core,@acme/react --bump minor --message "Add public metrics API."

Flag	Descripción
--empty	Crea un archivo de changeset vacío.
--packages <list>	Nombres de paquetes separados por comas para creación no interactiva.
--bump <type>	Uno de patch, minor, major.
--message <text>	Resumen usado en el cuerpo del changeset y en el changelog.

pubm changesets status

Inspecciona los changesets pendientes.

pubm changesets status
pubm changesets status --verbose
pubm changesets status --since origin/main

Flag	Descripción
--verbose	Imprime el resumen de cada changeset registrado.
--since <ref>	Comprueba desde un ref de Git.

pubm changesets version

Consume changesets, actualiza las versiones de los manifests, escribe changelogs y hace commit del resultado.

Para los paquetes que no tienen archivos de changeset pendientes, pubm changesets version puede replegarse en commits convencionales para determinar el tipo de bump. Este comportamiento se controla mediante la opción de configuración versionSources. Consulta la guía de Configuración para más detalles.

pubm changesets version
pubm changesets version --dry-run

Flag	Descripción
--dry-run	Imprime el plan de versiones y changelog sin escribir archivos.

pubm changesets changelog

Genera texto de changelog a partir de changesets pendientes.

pubm changesets changelog
pubm changesets changelog --dry-run
pubm changesets changelog --version 1.8.0

Flag	Descripción
--dry-run	Previsualiza la salida del changelog sin escribir CHANGELOG.md.
--version <ver>	Usa un encabezado de sección concreto en lugar de Unreleased.

pubm changesets migrate

Mueve archivos pendientes del layout heredado .changeset/ a .pubm/.

pubm changesets migrate

Códigos de salida

pubm devuelve un código de salida distinto de cero cuando:

• falla una comprobación previa o de condiciones
• no se puede completar la resolución de versión
• falla la publicación en cualquier target
• un subcomando encuentra entrada no válida

En el modo de publicación normal, los fallos también desencadenan rollback cuando es posible.

Patrones de comandos de ejemplo

Primera release local en un repositorio nuevo

pubm init
pubm changesets add
pubm changesets version
pubm --mode ci --phase prepare
pubm --dry-run
pubm

Prueba local de CI

pubm --mode ci --phase prepare

Publicar solo la release etiquetada actual en CI

pubm --mode ci --phase publish

Sincronizar tokens guardados después de la preparación

pubm secrets sync