Automatización local para macOS

De un comando a una imagen que se entiende.

La CLI usa el mismo motor visual que la app. Renderiza archivos, entradas canalizadas, diffs de Git, terminales e imágenes locales; puede copiar, guardar, abrir el editor o producir conjuntos completos para documentación y CI.

⌘K

resultados visibles · Pulsa ⌘K para buscar

Una captura de Vitrine que muestra los comandos recipe validate y recipe show sobre una receta nombrada explícitamente.
01 · Empezar

Instalar y comprobar

Homebrew instala la app y añade vitrine al PATH. Con el DMG, actívala desde Ajustes ▸ General ▸ Herramienta de línea de comandos.

brew install --cask johnny4young/tap/vitrine
vitrine --version
Disponibilidad. La App Store no incluye la CLI. Los comandos que renderizan requieren una licencia PRO activa de la compilación de descarga directa; version, list y recipe funcionan sin renderizar.

Tu primera imagen

Empieza sin configurar nada. Vitrine infiere Swift por la extensión, usa One Dark y el fondo aurora, y escribe un PNG retina.

vitrine render Sources/App.swift --out app-card.png
02 · Comandos

Mapa de comandos

Elige el verbo por el resultado que quieres obtener; no necesitas memorizar opciones para empezar.

renderCrear una imagen

Renderiza un archivo, la entrada estándar, un diff de Git o una imagen local. Guárdalo, cópialo o envía la fuente al editor.

vitrine render <input> --out <image> [options]
multi-sizeUna fuente, varios destinos

Carga una fuente una sola vez y exporta tamaños deterministas como OpenGraph, X, LinkedIn y Story en una carpeta.

vitrine multi-size <input> --out <folder> [--presets <ids>]
batchRenderizar una carpeta con seguridad

Convierte un árbol de fuentes en imágenes con recorrido recursivo, filtros, simulación, manifiestos y resultados estrictos para CI.

vitrine batch <input-folder> --out <output-folder> [options]
recipeInspeccionar recetas portátiles

Valida o muestra una receta nombrada explícitamente sin renderizar. Vitrine nunca busca configuración en el repositorio ni en carpetas superiores.

vitrine recipe <validate|show> <path> [--json]
listDescubrir identificadores válidos

Lista temas, lenguajes, ajustes, fuentes, fondos, marcos, formatos, perfiles y otros valores incluidos en la compilación instalada.

vitrine list <catalog> [--json]
versionVerificar la compilación instalada

Muestra la versión y el número de compilación antes de iniciar AppKit. Es una comprobación rápida y segura para automatizaciones.

vitrine --version [--json]
shell-initInstalar ayudantes de terminal

Muestra las funciones de shell de vgrab y vpane. Nada se ejecuta en segundo plano; solo actúan cuando las invocas.

vitrine shell-init [zsh|bash|fish]
03 · Casos prácticos

Casos prácticos

Ejemplos completos para tareas reales. Puedes copiarlos y cambiar solo las rutas.

Renderiza tu primer archivo

El lenguaje se infiere del nombre del archivo y el formato de la extensión.

vitrine render Sources/App.swift --out app-card.png

Convierte una canalización en una imagen

Usa una pista de nombre para que la detección y los metadatos sigan siendo útiles.

cat Component.tsx | vitrine render --stdin \
  --stdin-name Component.tsx --copy

Crea una imagen enfocada para un PR

Lee Git directamente, conserva prefijos estables y limita la imagen a las rutas que estás explicando.

vitrine render --git-diff main...HEAD \
  --git-path Vitrine/CLI --git-context 6 \
  --out cli-review.png

Captura solo los cambios preparados

Útil antes de confirmar cambios: la imagen coincide con el índice y no con trabajo no relacionado.

vitrine render --git-staged --out staged-review.png

Comparte un comando con contexto

vgrab conserva el color y añade el proyecto, la rama Git cuando existe y el comando exacto sobre el resultado.

vgrab npm test
vgrab -e git status
vgrab --no-context env | sort

Usa --no-context cuando los argumentos, rutas o nombres de rama deban mantenerse privados.

Embellece una captura de producto

Una imagen local puede usar el mismo lienzo, fondo, sombra y marcos de navegador o dispositivo que la app.

vitrine render --image dashboard.png --out showcase.png \
  --frame browser --frame-appearance dark \
  --window-title app.example.com --background night

Reutiliza un estilo del espacio de trabajo

Inspecciona primero la receta y luego nómbrala al renderizar. Las opciones explícitas siguen teniendo prioridad.

vitrine recipe validate docs.vitrine-recipe.json
vitrine recipe show docs.vitrine-recipe.json
vitrine render README.md --out readme.png \
  --recipe docs.vitrine-recipe.json --scale 2

Oculta secretos antes de crear archivos auxiliares

Las filas detectadas se ocultan en la imagen y se sustituyen en cada archivo de texto auxiliar.

vitrine render config.swift --out safe.png \
  --redact-secrets --sidecars all

Un --blur-box visual no limpia el texto fuente. Usa --redact-lines o --redact-secrets cuando haya contenido sensible.

Crea un paquete para redes

Una fuente se renderiza en cada tamaño con nombres de archivo estables.

vitrine multi-size launch.swift --out launch-assets \
  --presets twitter,linkedin,opengraph \
  --recipe launch.vitrine-recipe.json

Prepara lotes confiables para CI

Simula primero, exige entradas, falla si omite archivos y conserva evidencia legible por máquinas.

vitrine batch Sources --out docs/cards --recursive \
  --include-ext swift,md --dry-run --fail-on-empty

vitrine batch Sources --out docs/cards --recursive \
  --include-ext swift,md --fail-on-empty --fail-on-skipped \
  --manifest docs/cards/manifest.json \
  --skipped-report docs/cards/skipped.json

Empieza en Terminal y termina en el editor

Envía la fuente al editor cuando la automatización te acerca al resultado pero la imagen final necesita anotaciones.

vitrine render --git-diff main...HEAD --edit
04 · Opciones

Referencia de opciones

La referencia sigue la ayuda del binario. Usa la búsqueda para encontrar cualquier opción en segundos.

Entrada y envío al editor

Elige una fuente y, si hace falta, limítala o asígnale un nombre.

--stdin

Lee texto desde la entrada estándar.

--stdin-name<name>

Infiere lenguaje y metadatos desde un nombre sin leer ese archivo.

--image<path>

Embellece una imagen local en lugar de renderizar texto.

--git-diff<range>

Carga una revisión o rango local con /usr/bin/git, sin shell ni descarga de red.

--git-staged

Carga solo los cambios preparados en el repositorio actual.

--git-path<path>

Limita una fuente Git a una ruta literal; repítelo para varias rutas.

--git-context<0...100>

Define líneas sin cambios alrededor de cada bloque; el valor predeterminado es 3.

-e, --edit

Abre la fuente en Vitrine en vez de escribir o copiar una imagen.

Salida y control del proceso

Elige el destino y cómo las automatizaciones comprueban el resultado.

-o, --out<path>

Ruta de imagen o carpeta para multi-size y batch.

--copy

Copia la imagen al portapapeles de macOS.

--format<png|pdf|heic|avif>

Selecciona la codificación. Una extensión conocida la elige automáticamente.

--profile<srgb|p3>

Selecciona el perfil de color PNG; sRGB es el predeterminado.

--scale<1|2|3>

Multiplica las dimensiones lógicas para obtener los píxeles finales.

--preset<id>

Usa un tamaño de destino de la lista de ajustes de Vitrine.

--canvas-size<WxH>

Define un lienzo lógico exacto de 64–2048 puntos.

-q, --quiet

Oculta la salida de éxito y conserva los errores.

--json

Emite resultados estructurados para render, multi-size, batch, list, recipe o version.

-v, --version

Muestra la versión instalada y el número de compilación.

--no-overwrite, --no-clobber

Evita reemplazar imágenes o archivos auxiliares existentes.

-h, --help

Muestra la ayuda local de la compilación instalada.

Código y estilo visual

Empieza con valores predeterminados, una receta o un ajuste integrado; las opciones explícitas se aplican al final.

--theme<id>

Tema de sintaxis de vitrine list themes.

--language<id>

Fuerza un lenguaje en vez de inferirlo.

--style-preset<id>

Aplica un ajuste visual integrado e inmutable.

--recipe<path>

Carga una receta portátil de espacio de trabajo nombrada explícitamente.

--font<family>

Familia tipográfica de vitrine list fonts.

--font-ligatures, --no-font-ligatures

Activa o desactiva ligaduras de programación.

--font-size<10...20>

Tamaño de la fuente en puntos.

--padding<16...64>

Relleno del lienzo en puntos.

--corner-radius<0...48>

Radio de las esquinas de la tarjeta.

--shadow-radius<0...40>

Radio de desenfoque de la sombra.

--terminal-width<1...1000>

Fija el ancho de reconstrucción; vgrab -w lo define automáticamente.

--wrap-columns<40...200>

Ajusta líneas largas en una columna estable.

--format-code, --tidy

Aplica el ajuste local de indentación antes de renderizar.

--line-numbers, --no-line-numbers

Muestra u oculta los números de línea.

--chrome, --no-chrome

Muestra u oculta el marco de ventana.

--shadow, --no-shadow

Muestra u oculta la sombra renderizada.

Lienzo y fondo

Usa una fuente de fondo; los modificadores de imagen requieren --background-image.

--transparent

Renderiza un fondo con transparencia real.

--background<id>

Degradado integrado de vitrine list backgrounds.

--background-color<hex>

Color sólido RGB o RGBA.

--background-gradient<hex,hex,...>

Degradado personalizado con al menos dos colores.

--background-angle<0...360>

Dirección de un degradado personalizado; valor predeterminado 135.

--background-image<path>

Usa una imagen local como fondo del lienzo.

--background-fit<fill|fit>

Recorta para llenar o conserva la imagen completa.

--background-blur<0...40>

Desenfoca localmente una imagen de fondo.

--background-dimming<0...1>

Aplica una capa oscura normalizada sobre la imagen.

Marcos para imágenes locales

Estos controles se aplican cuando --image es la entrada.

--frame<id>

Usa none, macos-window, browser, macbook o iphone.

--frame-appearance<auto|light|dark>

Controla la apariencia de un marco seleccionado.

Títulos y metadatos

Añade contexto para que la imagen se entienda fuera del repositorio.

--window-title<text>

Título en el marco de ventana o navegador.

--filename<text>

Etiqueta de archivo en la cabecera.

--title<text>

Título principal de metadatos.

--caption<text>

Texto de apoyo bajo el título.

--language-badge, --no-language-badge

Muestra u oculta la etiqueta del lenguaje.

Anotaciones, enfoque y censura

Las coordenadas de 0 a 1 permiten que las marcas escalen con el lienzo.

--callout<text>

Añade una llamada de texto.

--callout-x, --callout-y<0...1>

Define el ancla; proporciona ambas coordenadas.

--callout-color<hex>

Color del texto de la llamada.

--callout-size<2...28>

Peso visual de la llamada.

--counter<1...99>

Añade una insignia numerada.

--counter-x, --counter-y<0...1>

Define el centro; proporciona ambas coordenadas.

--counter-color<hex>

Color de relleno del contador.

--counter-size<2...28>

Peso visual del contador.

--arrow<x1,y1,x2,y2>

Dibuja una flecha repetible desde la cola a la punta.

--arrow-color, --arrow-size<hex> / <2...28>

Color y peso compartidos por todas las flechas.

--line<x1,y1,x2,y2>

Dibuja una línea recta repetible.

--line-color, --line-size<hex> / <2...28>

Color y peso compartidos por todas las líneas.

--rectangle<x1,y1,x2,y2>

Contornea una región repetible.

--rectangle-color, --rectangle-size<hex> / <2...28>

Color y peso compartidos por todos los rectángulos.

--highlighter<x1,y1,x2,y2>

Resalta una región repetible.

--highlighter-color<hex>

Color compartido del resaltador.

--blur-box<x1,y1,x2,y2>

Desenfoca visualmente una región; no limpia los archivos auxiliares.

--highlight-lines<spec>

Resalta filas desde 1, como 3,7-9,12.

--redact-lines<spec>

Oculta filas en la imagen y las sustituye en los archivos auxiliares.

--redact-secrets

Busca secretos probables y oculta las filas correspondientes.

--focus-lines, --no-focus-lines

Atenúa o restaura las filas fuera del resaltado.

--diff-bands, --no-diff-bands

Muestra u oculta bandas de cambios al estilo GitHub.

Marca de agua

Añade texto, un logo local o ambos con la misma capa de Brand Kit.

--watermark<text>

Texto de la marca de agua.

--watermark-logo<path>

Imagen de logo local.

--watermark-color<hex>

Color del texto; requiere texto.

--watermark-position<corner|free>

Usa una esquina nombrada o posición libre.

--watermark-x, --watermark-y<0...1>

Centro normalizado para posición libre; proporciona ambas.

Automatización multi-size y batch

Usa destinos estables y haz visible cualquier resultado parcial en CI.

--presets<ids|all>

Destinos de multi-size separados por comas; all es el valor predeterminado.

--recursive

Recorre subcarpetas y conserva rutas relativas.

--dry-run

Descubre y carga entradas sin escribir artefactos.

--include-ext<list>

Considera solo las extensiones indicadas.

--exclude-ext<list>

Ignora extensiones antes de cargar archivos.

--fail-on-empty

Falla cuando ningún archivo se renderizaría.

--fail-on-skipped

Falla al terminar si alguna entrada fue omitida.

--skipped-report<json>

Escribe un informe de archivos omitidos.

--manifest<json>

Escribe rutas y dimensiones de resultados reales o planeados.

Archivos auxiliares accesibles

Entrega texto seleccionable junto a la imagen sin cambiar sus píxeles.

--text-sidecar

Escribe un archivo .txt de texto plano.

--markdown-sidecar

Escribe una referencia Markdown y la fuente en un bloque.

--html-sidecar

Escribe un fragmento HTML con la imagen y la fuente escapada.

--sidecars<text,markdown,html|all>

Activa varios archivos auxiliares con una opción.

05 · Soluciones

Problemas frecuentes y soluciones

Las diferencias entre Homebrew, DMG, App Store y compilaciones de desarrollo explican la mayoría de problemas de instalación.

vitrine: command not found

Con Homebrew, ejecuta brew reinstall --cask johnny4young/tap/vitrine. Con el DMG, abre Ajustes ▸ General ▸ Command-line tool ▸ Install… o crea el enlace manual documentado en README.

“Vitrine PRO is required”

Activa la licencia en la app de descarga directa y vuelve a ejecutar el comando. Las compilaciones Release ignoran VITRINE_PRO_UNLOCK por diseño.

La App Store no tiene el binario

Es intencional: ese canal no distribuye herramientas en PATH. Instala el DMG firmado o el paquete de Homebrew para usar la CLI.

El lenguaje detectado no es correcto

Pasa --language <id> o, cuando uses --stdin, añade --stdin-name con una extensión útil. Consulta vitrine list languages.

El archivo ya existe

Omite --no-overwrite para reemplazarlo, cambia --out o elimina el artefacto anterior. En batch, los existentes se informan como omitidos.

El texto sigue presente tras --blur-box

--blur-box solo cambia los píxeles. Usa --redact-lines o --redact-secrets para limpiar también los archivos auxiliares.

Una canalización pierde los colores ANSI

Muchos programas desactivan el color fuera de un TTY. Usa vgrab, o fuerza el color en el programa antes de enviarlo a vitrine render --stdin.

Necesito ver el resultado antes de exportar

Cambia --out o --copy por --edit. Vitrine abre la fuente en el editor para ajustar y anotar manualmente.

Límite de privacidad

El renderizado de código, terminales e imágenes locales no necesita red, Screen Recording ni Accessibility. Una receta solo se carga cuando pasas --recipe; Git se invoca directamente sin shell, pagers, textconv ni descargas implícitas.