Línea de comandos

¿Llamas a marsdawn desde un agente de IA o un script? Consulta marsdawn para agentes para ver la salida JSON, sus esquemas y todos los códigos de salida, o el servidor MCP si tu agente llama a herramientas por MCP.

Instalación

Con Homebrew:

brew tap redtear1115/tap && brew install marsdawn

¿Usas un agente de programación? Ejecuta marsdawn skill --install para agregar la skill de marsdawn: un solo archivo que le enseña a abrir lo que escribió en MarsDawn para que lo revises, y a exportar PDF.

En una Mac con chip de Apple, Homebrew instala una copia precompilada en segundos, sin nada más que instalar. En una Mac con Intel, compila marsdawn desde el código fuente, lo que toma unos minutos y requiere Xcode 26 o posterior (Swift 6.2). La herramienta funciona en macOS 15 o posterior.

O compílala desde el código fuente con Swift Package Manager:

git clone https://github.com/redtear1115/mars-dawn-kit.git
cd mars-dawn-kit
swift build -c release --product marsdawn

Revisa qué versión tienes con marsdawn --version.

Comandos

marsdawn open

Abre uno o varios archivos Markdown en la app MarsDawn para que los revises. Necesita la app instalada: sin ella, marsdawn open termina con el código 3 e indica que MarsDawn no está instalado. export no necesita la app. La app está en el Mac App Store.

marsdawn open notes.md
marsdawn open notes.md:120
marsdawn open notes.md --line 120
marsdawn open .
marsdawn open notes.md --folder .

• path:line: le pide a MarsDawn que vaya a esa línea. Una columna después, como en notes.md:120:8, se ignora. Si existe un archivo con el nombre completo, el argumento es ese archivo.
• --line <n>: lo mismo para un solo archivo, y la manera de pedir una línea en una ruta que termina en dos puntos y dígitos. Requiere exactamente un archivo.
• Las líneas van de 1 a 999999999.
• MarsDawn 1.0 abre el archivo en esa línea.
• Una carpeta como argumento se abre en la barra lateral de la ventana en lugar de como documento: marsdawn open . muestra la carpeta actual. --folder <path> hace lo mismo junto con archivos. La barra lateral de una ventana muestra una carpeta, así que indicar dos es un error de uso.
• --wait <n>: con MarsDawn 1.0.2 o posterior, que informa del resultado, --folder espera hasta n segundos (de 0 a 30, 2 de forma predeterminada) la respuesta de la app sobre la carpeta. Con --wait 0, o con una app que no informa del resultado, no espera y envía la misma solicitud que antes.
• Un valor de --wait fuera de 0 a 30 es un error de uso (código 64). Escribe un valor negativo como --wait=-1.
• Con --json, la carpeta figura como solicitada, no como mostrada, porque decide la app; con --wait, el resultado también dice qué pasó con ella. La lista completa está en marsdawn para agentes.
• --background: abrir sin traer MarsDawn al frente.
• --json: mostrar un resultado JSON en lugar de texto.

Las líneas llegaron con marsdawn 0.3.0, las carpetas y --background con la 0.5.1, y --wait y el estado de la carpeta con la 0.5.3.

marsdawn export

Convierte un archivo Markdown en un PDF paginado, con el mismo exportador que usa la exportación a PDF de MarsDawn. No necesita la app MarsDawn. Las imágenes relativas se resuelven a partir de la carpeta del archivo de entrada.

marsdawn export notes.md -o notes.pdf --theme classic --paper a4

• -o, --output <path>: dónde escribir el PDF. De forma predeterminada, la ruta de entrada con la extensión .pdf.
• --theme <dawn|classic|modern|vivid>: la paleta clara del tema de la vista previa. De forma predeterminada, $MARSDAWN_THEME y, si no, dawn.
• --paper <a4|letter>: tamaño del papel. De forma predeterminada, a4.
• --breaks: mostrar cada salto de línea dentro de un párrafo como un salto de línea, como HackMD. Sin esta opción, un salto de línea entre dos caracteres chinos o japoneses desaparece, y las líneas se leen como una sola frase.
• --layout <document|handbook>: la disposición de página. De forma predeterminada, document. handbook genera una guía: márgenes más anchos con un lado de encuadernación, cada encabezado de primer nivel en una página nueva, una tabla de contenido con números de página, números de página en el pie y marcadores PDF, además de una portada cuando el front matter tiene title.
• --toc-title <text>: el título de la página de contenido de la guía. De forma predeterminada, Contents.
• <!--BREAK--> solo en una línea empieza una página nueva, en ambas disposiciones.
• --allow-remote-images: cargar imágenes de la web durante el renderizado. Desactivado de forma predeterminada.
• --force: reemplazar el archivo de salida si ya existe.
• --json: mostrar un resultado JSON en lugar de texto.
• Un archivo de más de 16 MiB no se exporta: export termina con el código 5 y no escribe nada.

--breaks llegó con marsdawn 0.7.0, --layout y --toc-title con la 0.7.1, y el valor handbook con la 0.7.2. El valor anterior de la 0.7.1, manual, sigue funcionando.

marsdawn theme

Comprueba un archivo de tema (theme.json) y muestra cómo se ve antes de que lo compartas. No necesita la app MarsDawn. Para los campos de un tema, consulta Crea un tema con tu agente.

marsdawn theme validate my-theme.json
marsdawn theme css my-theme.json
marsdawn theme preview my-theme.json --appearance dark -o preview.png

• validate <file>: comprueba el archivo con cada regla que debe cumplir un tema de MarsDawn, con el mismo validador que usa la app. Termina con el código 0 si el tema es válido y con 1 si no, y enumera cada problema. --require-complete exige también los colores de sintaxis y de diagramas, que todo tema publicado debe tener.
• css <file>: muestra el CSS que usa la vista previa para un tema válido.
• preview <file> --appearance <light|dark> -o <out.png>: genera un documento de ejemplo con el tema en un PNG. --width fija su ancho en píxeles, de 600 a 2000 (1200 de forma predeterminada). Un archivo existente solo se reemplaza con --force.
• --json: mostrar un resultado JSON en lugar de texto.

Los comandos theme llegaron con marsdawn 0.6.1.

La variable $MARSDAWN_THEME

Cuando no se pasa --theme, export lee la variable de entorno $MARSDAWN_THEME. Su valor debe ser dawn, classic, modern o vivid; cualquier otro vuelve a dawn. La CLI no lee el ajuste de tema de la propia app, porque leer el contenedor de otra app puede hacer que macOS muestre un aviso de privacidad.

Sobrescribir archivos

export se niega a reemplazar un archivo de salida existente a menos que pases --force.

Códigos de salida

Salida --json

Si todo sale bien, marsdawn open --json muestra ok, opened (una lista con el path de cada archivo, más line cuando se pidió una), app (la ruta de la app) y, cuando se indicó una carpeta, folder. marsdawn export --json muestra ok, output, pages, theme, paper y diagramErrors. Si algo falla, ambos muestran ok, error y message.