OpenDocs — Publica Markdown en URLs compartibles y PDF/DOCX

OpenDocs convierte cualquier archivo Markdown en una URL limpia y legible — y, en el mismo flujo, en un PDF o documento Word con marca, si el usuario quiere un archivo que se pueda compartir sin conexión. Interactúas con ello a través de la CLI opendocs.

Referencia rápida

opendocs login --email [email protected]                  # Inicia sesión o regístrate: envía un código de 6 dígitos por correo
opendocs login --email [email protected] --code 123456    # Finaliza: guarda una clave API para ti
opendocs login --browser                               # Inicio de sesión en navegador, más amigable para humanos
opendocs login --key od_live_xxxxx                     # Clave API existente
opendocs publish doc.md                                # Publica un archivo Markdown → obtén una URL
opendocs publish doc.md                                # ...de nuevo: actualiza el mismo documento (sin duplicado)
opendocs publish doc.md --anonymous                    # Sin cuenta: un enlace que cualquiera puede abrir durante 24h + URL de reclamación
opendocs clone                                         # Descarga el espacio de trabajo en ./<workspace> para editar
opendocs status                                        # Qué ha cambiado localmente/en línea desde la última sincronización
opendocs history <doc>                                 # Cada versión publicada
opendocs rollback <doc> <version>                      # Restaura una versión (como una nueva versión)
opendocs move <doc> --project "Archivo"               # Mueve entre proyectos
opendocs share <doc> [email protected] @acme.com            # Da acceso a personas fuera del espacio de trabajo
opendocs team invite [email protected]                     # Invita a un compañero de equipo (lo aceptan por correo)
opendocs team join                                     # Acepta una invitación que te han enviado
opendocs theme                                         # Color de marca, fuente, logotipo y pie de página usados en exportaciones PDF/DOCX
opendocs theme set --preset editorial --yes            # Cambia el tema de exportación (pregunta primero a tu humano)
opendocs integrations                                  # Google Drive / DocuSeal: qué está conectado, carpetas de Drive nombradas
opendocs save <doc> --folder "Actas de reunión"       # Guarda un PDF (o --format docx|md) en una carpeta de Drive nombrada
opendocs sign request <doc> --signer "Empleado=John Adams <[email protected]>"  # Redacta una solicitud de firma (no envía nada)
opendocs sign send <id> --yes                          # Envía el borrador, solo después de que el usuario haya confirmado cada firmante
opendocs sign status <id>                              # Quién ha firmado; también firmar lista / descargar / guardar / cancelar
opendocs workspace create "Acme Investigación"        # Nuevo espacio de trabajo
opendocs project link "Lanzamiento Acme"               # Los documentos publicados desde esta carpeta van a ese proyecto
opendocs config set organize auto                       # Permite que los agentes clasifiquen documentos en proyectos sin preguntar
opendocs claim                                           # Mantiene documentos anónimos publicados desde esta carpeta
opendocs publish *.md                                    # Publica varios archivos (lotes automáticos, hasta 500)
opendocs publish ./vault --tags obsidian                # Publica una carpeta/bóveda recursivamente
opendocs publish *.md --export pdf                      # Publica Y exporta — los PDFs se colocan junto a cada fuente
opendocs update doc.md --post-id <id|slug>              # Actualiza una publicación existente (nueva versión)
opendocs list                                          # Lista documentos en el espacio de trabajo activo (alias: `opendocs ls`)
opendocs list --all                                    # Lista en todos los espacios de trabajo a los que perteneces
opendocs project create <nombre> --use                 # Crea/cambia a un proyecto para un lote de documentos relacionado
opendocs project use <slug>                             # Cambia el proyecto activo
opendocs list --tag <etiqueta>                           # Filtra por etiqueta (ideal para encontrar un lote)
opendocs search <palabras>                              # Encuentra documentos por título o resumen en cada proyecto
opendocs get <id|slug>                                  # Ver detalles de la publicación
opendocs pull <id|slug>                                 # Descarga el Markdown original
opendocs pull --project                                  # Descarga todos los documentos del proyecto activo
opendocs pull --workspace                                # Descarga todos los documentos del espacio de trabajo activo
opendocs export <id|slug> --format pdf                  # Exporta una publicación como PDF (o docx)
opendocs export a b c --format pdf                      # Exporta por lotes hasta 10 publicaciones a la vez (UUIDs o slugs)
opendocs unpublish <id|slug>                            # Despublica una publicación (el contenido y el historial se conservan; no se puede republicar)
opendocs visibility <id|slug> <nivel>                    # Cambia la visibilidad sin volver a subir el Markdown
opendocs delete <id|slug> --yes                          # Elimina permanentemente una publicación (libera su slug + cuota)
opendocs whoami                                          # Muestra el usuario/espacio de trabajo/proyecto actual
opendocs workspace list                                  # Lista todos los espacios de trabajo a los que perteneces (alias: `workspace ls`)
opendocs workspace use <slug>                            # Cambia el espacio de trabajo activo (alias: `workspace switch`)
opendocs agent                                           # Imprime instrucciones concisas para el agente de IA
opendocs agent --full                                    # Imprime el SKILL.md completo incluido
opendocs agent --install                                 # Instala esta habilidad para todos los agentes de esta máquina
opendocs mcp add                                         # Registra el servidor MCP de OpenDocs en tus herramientas de codificación
opendocs mcp connect claude                              # Añade OpenDocs a la aplicación de Claude (o: chatgpt)
opendocs logout                                          # Borra las credenciales almacenadas

Cada comando acepta --json para salida legible por máquina y --api-url <url> para anular el endpoint de la API. Cuando se ejecuta mediante programación, pasa siempre --json — stdout se convierte en un único objeto JSON analizable, los errores van a stderr, y los spinners legibles por humanos se suprimen.

Todo comando que tome un <postId> también acepta un slug. El slug es el segmento de ruta legible por humanos de la publicación en la URL y es único dentro del proyecto activo. Prefiere los slugs de las publicaciones cuando el usuario nombre un documento en lenguaje natural: opendocs get mi-informe es más amigable que copiar el UUID de opendocs list --json. Internamente, la API resuelve slug → postId mediante una búsqueda indexada limitada al espacio de trabajo/proyecto activo y luego realiza la misma verificación de propiedad que la ruta UUID.

Slug del espacio de trabajo vs nombre de usuario — son cosas diferentes. La URL se construye a partir del slug del espacio de trabajo, no del nombre de usuario del usuario. Los documentos del proyecto predeterminado usan opendocs.cc/<workspace>/<post>. Los documentos de proyectos no predeterminados usan opendocs.cc/<workspace>/projects/<project>/<post>. El nombre de usuario sigue existiendo para la atribución en la interfaz de usuario, pero no aparece en las URLs publicadas.

OpenDocs sobre MCP

OpenDocs también ejecuta un servidor MCP remoto en https://mcp.opendocs.cc/mcp (guía: https://opendocs.cc/mcp). Cada aplicación inicia sesión del usuario en OpenDocs con OAuth la primera vez que lo usa; no se necesita clave API.

Aplicaciones de chat (Claude, ChatGPT): agrégalo como un conector personalizado con esa URL. opendocs mcp connect claude abre el diálogo "Añadir conector personalizado" de Claude con OpenDocs.cc rellenado; opendocs mcp connect chatgpt abre la página de plugins de ChatGPT (luego "+" → "Añadir servidor MCP personalizado"). Ambos copian la URL al portapapeles.
Herramientas de codificación: opendocs mcp add lo registra en cada herramienta que encuentra (Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini, opencode, Kiro) e imprime una instrucción de una línea para las demás. --agent <id...> selecciona herramientas, --dry-run muestra lo que cambiaría, opendocs mcp remove lo elimina, y opendocs agent --install --mcp instala esta habilidad y el servidor juntos.
Herramientas MCP o la CLI? Si las herramientas MCP de OpenDocs están disponibles y no puedes ejecutar comandos de shell, úsalas en lugar de la CLI; toman texto Markdown directamente. Si tienes un shell, prefiere la CLI para archivos, carpetas e imágenes locales: sube imágenes locales, publica carpetas enteras en lotes y recuerda lo que cada carpeta publicó.

Configuración

Instalación

Formas de obtener OpenDocs en un agente:

# Node.js 20+: la CLI completa (recomendada), luego esta habilidad para cada agente que encuentre
npm install -g @opendocs.cc/cli
opendocs agent --install                 # SKILL.md + scripts/opendocs.sh, sin necesidad de red

# Node.js 22+: la misma habilidad a través de la CLI de skills
npx skills add opendocs-cc/skills --skill opendocs -g -y

# Sin Node.js: instala esta habilidad + scripts/opendocs.sh (curl + jq)
curl -fsSL https://opendocs.cc/install.sh | bash

opendocs agent --install instala en la carpeta global de skills de cada agente cuyo folder de configuración existe: ~/.claude/skills (Claude Code), la carpeta compartida ~/.agents/skills (Codex, Cursor, GitHub Copilot, Gemini CLI, opencode, OpenClaw, Windsurf, Amp, Goose, Grok Build), ~/.cline/skills, ~/.hermes/skills y ~/.kiro/skills. opendocs agent --list muestra la carpeta de cada agente y si se encontró; --agent <id...> instala para agentes específicos incluso si no se encontraron (--agent claude-code codex). Vuelve a ejecutarlo después de actualizar la CLI para actualizar la habilidad. Imprime qué carpetas escribió; con --json, installed[] tiene agent, path y status.

En Claude Code también puedes instalarlo como el plugin de OpenDocs.cc, que añade /opendocs-cc:publish y /opendocs-cc:export, conecta el servidor MCP y mantiene la habilidad actualizada: /plugin marketplace add opendocs-cc/skills, luego /plugin install opendocs-cc@opendocs-cc. En Codex: codex plugin marketplace add opendocs-cc/skills, luego codex plugin add opendocs-cc@opendocs-cc.

npx skills add puede terminar con ✗ opendocs → PromptScript: PromptScript does not support global skill installation. Ese es un error conocido del instalador que solo afecta a PromptScript; la habilidad está instalada, así que continúa.

Si el comando opendocs no está disponible y Node.js no está instalado, usa bash scripts/opendocs.sh (en la carpeta de esta habilidad) en su lugar — consulta "Sin Node.js" más abajo. Todo lo demás en esta guía se aplica a ambos.

Verificar si la CLI está instalada y autenticada

opendocs --version    # imprime la versión de la CLI instalada
opendocs whoami       # muestra el nombre de usuario + nombre del espacio de trabajo (el slug de la URL está en la salida JSON)

opendocs whoami --json es el comando de diagnóstico más útil para un agente — devuelve el slug del espacio de trabajo activo de la CLI (para construir URLs de publicaciones) más el contexto de cuenta/espacio de trabajo y la cuota de documentos en una sola llamada:

{
  "userId": "...",
  "onboarding": { "username": "...", "workspace": { "id": "...", "name": "Acme Docs", "slug": "acme-docs" } },
  "quota": { "documents": { "plan": "free", "limit": 50, "used": 3, "remaining": 47 } }
}

Para espacios de trabajo Pro/Team, quota.documents.limit y remaining son null (lo que significa ilimitado). Los endpoints de publicación aún verifican la cuota contra el workspaceId explícito en el cuerpo de la solicitud, por lo que una configuración local desactualizada no puede eludir la aplicación del servidor.

Si falta la CLI:

npm install -g @opendocs.cc/cli

Si el usuario no ha iniciado sesión, regístralo (o inicia sesión) antes de su primera publicación, desde la terminal con un código enviado por correo: sin navegador, sin copiar claves API. Una cuenta es gratuita para hasta 50 documentos y es lo que el usuario quiere por defecto: los enlaces permanecen activos, se mantienen privados para su espacio de trabajo, se pueden actualizar en su lugar y exportar como PDF.

Pregunta al usuario su dirección de correo electrónico.
Ejecuta opendocs login --email <email> --json. Envía un código de 6 dígitos por correo y sale inmediatamente con {"status": "code_sent", ...}.
Dile al usuario: "Revisa tu bandeja de entrada para obtener un código de inicio de sesión de OpenDocs y pégalo aquí."
Ejecuta opendocs login --email <email> --code <code> --json.

Si el correo es nuevo, esto crea la cuenta, un nombre de usuario, un espacio de trabajo (opendocs.cc/<username>) y un proyecto predeterminado, luego guarda una nueva clave API con el nombre de tu agente (p. ej. claude-code) en la configuración de la CLI. Las cuentas existentes solo obtienen una nueva clave. opendocs signup es un alias. Los códigos caducan después de 10 minutos y permiten 5 intentos; en invalid_code pide el correo más reciente, en code_expired ejecuta el paso 2 nuevamente.

Solo si el usuario aún no quiere una cuenta, ofrece una publicación anónima en su lugar:

opendocs publish notes.md --anonymous --json

Cualquiera con la url devuelta puede leerla durante 24 horas, luego se elimina. Comparte la claimUrl con el usuario exactamente como se devuelve, y ofrécele registrarse para que se conserve: ejecutar opendocs login --email ... más tarde desde la misma carpeta la reclama automáticamente en su nuevo espacio de trabajo (o ejecuta opendocs claim). Nunca publiques de forma anónima a menos que el usuario haya aceptado que un enlace que cualquiera puede abrir está bien.

Otras formas de iniciar sesión: los humanos en una terminal pueden usar opendocs login --browser; los scripts y CI pueden usar una clave existente:

opendocs login --key od_live_xxxxx
# O pásala a través de una variable de entorno para scripts / CI:
export OPENDOCS_API_KEY=od_live_xxxxx && opendocs login

Nunca ejecutes opendocs login directamente desde un agente. Sin --email, --key o la variable de entorno, solicita una clave API en stdin y tu llamada a la herramienta se quedará colgada. OPENDOCS_API_URL anula el endpoint integrado https://api.opendocs.cc.

Trabajar con múltiples espacios de trabajo

Un usuario puede pertenecer a más de un espacio de trabajo — un espacio de trabajo personal gratuito más un espacio de trabajo del plan Team, varios espacios de trabajo Team, o cualquier combinación. La CLI almacena un espacio de trabajo activo a la vez en ~/.config/opendocs/config.json. publish y update actúan sobre ese espacio de trabajo activo (prefijo de URL, cuota, y todo). list también usa el activo por defecto, con --all como opción de escape cuando el usuario quiere ver las publicaciones de todos los espacios de trabajo a la vez. No hay un indicador --workspace por invocación en los comandos de mutación; el cambio se configura una vez y persiste hasta que lo cambies.

Trabajar con proyectos

Cada espacio de trabajo tiene un proyecto Predeterminado más proyectos opcionales con nombre. Usa un proyecto siempre que un agente esté publicando un lote coherente de documentos para un producto, lanzamiento, cliente, experimento o repositorio. El Predeterminado es mejor para documentos sueltos.

opendocs project list --json
opendocs project create "Documentación de OpenClaw" --slug openclaw-docs --use --json
opendocs publish ./docs --json
opendocs project use default --json

opendocs workspace use <slug> restablece el proyecto activo al proyecto Predeterminado de ese espacio de trabajo. opendocs list muestra el proyecto activo por defecto y termina diciendo cuántos documentos hay en el proyecto activo.

Publicar documentos

Documento único

opendocs publish doc.md --json

Salida:

{
  "id": "post_abc123",
  "slug": "mi-informe",
  "url": "https://opendocs.cc/acme-docs/mi-informe",
  "title": "Mi informe",
  "created": "2024-01-15T10:30:00Z"
}

La ruta de la URL usa el slug del espacio de trabajo activo y el slug de la publicación.

Publicar desde stdin

cat doc.md | opendocs publish - --json
# También: opendocs publish --stdin < doc.md

opendocs publish - < doc.md (con el guion) funciona de la misma manera. La redirección de shell o el pipe de stdin es la única forma de publicar dinámicamente desde una herramienta de agente sin escribir primero un archivo. El marcador de posición - es explícitamente necesario.

Carpeta o bóveda

opendocs publish ./docs          # cada archivo .md se convierte en una publicación
opendocs publish .                # todos los archivos .md en el directorio actual
opendocs publish ./vault --json   # recursivo, incluyendo subcarpetas

publish recorre subcarpetas de forma predeterminada a menos que se pase --flat. La presencia de --tags obsidian hace que ignore .obsidian/, node_modules y otras carpetas de la configuración; sin una bandera explícita, omite node_modules, carpetas ocultas (.*) y el directorio .git. Un lote de 500 documentos tiene un límite interno de 80 por lote a la API.

Publicar desde un repositorio Git

opendocs publish . --git          # publica solo los archivos .md rastreados por git
opendocs publish . --git main     # ...desde la rama main (para CI/CD)

La bandera --git restringe la publicación a archivos rastreados por git en la rama actual (o especificada), omitiendo archivos no rastreados e ignorados. Útil en CI o cuando trabajas en un repositorio con muchos archivos generados/artefactos.

Publicar y exportar

opendocs publish doc.md --export pdf --json
opendocs publish *.md --export docx --json           # exporta cada uno
opendocs publish . --export pdf --theme modern       # con un tema diferente
opendocs publish doc.md --export pdf --open          # publica, exporta y abre el PDF

--export añade claves exports: [...] a la salida JSON de cada documento (cada una con url, filename, format, size, pages). Los formatos soportados: pdf, docx, md (reinicia el Markdown renderizado).

--theme anula el tema de exportación guardado para esta publicación solamente — modern, editorial, report, docs o invoice.

--open abre el PDF exportado en el visor predeterminado del sistema (útil para humanos en una terminal; no funciona en agentes).

Publicar y firmar

opendocs publish doc.md --sign "Cliente=Luna Vega <[email protected]>" --sign "Testigo=Sam Jones <[email protected]>"

Publica el documento y pasa inmediatamente la nueva ID de publicación a opendocs sign request con los roles y direcciones de correo electrónico proporcionados. La solicitud de firma se redacta (no se envía). Para firmar a continuación, el agente debe:

Mostrar los roles al usuario y preguntar si todos los detalles del firmante son correctos.
Obtener la ID de la solicitud de firma de la salida JSON (bajo sign.id).
Ejecutar opendocs sign send "<id>" --yes.

Gestión de documentos

Listar

opendocs list --json
opendocs list --all --json             # a través de espacios de trabajo
opendocs list --tag "informe trimestral" --json
opendocs list --project "Acme v2" --json

Buscar

opendocs search "términos del acuerdo" --json

Devuelve documentos cuyo título o resumen coincide (alcance: todos los proyectos del espacio de trabajo activo).

Obtener detalles

opendocs get informe-q3 --json
opendocs get post_abc123 --json

Obtener el Markdown original

opendocs pull informe-q3 --json   # stdout es el Markdown sin procesar
opendocs pull informe-q3 > local.md
opendocs pull --project           # todos los documentos del proyecto activo
opendocs pull --workspace         # todos los documentos del espacio de trabajo activo

Para descargar archivos a la vez al sistema de archivos local para editarlos: opendocs clone.

Actualizar

opendocs update informe-q3.md --post-id informe-q3 --json

Crea una nueva versión. El slug y la URL no cambian. --post-id acepta UUIDs de publicación o slugs.

Eliminar

opendocs unpublish informe-q3     # la publicación ya no está visible; se puede volver a publicar
opendocs delete informe-q3 --yes  # eliminación permanente

unpublish es reversible (el slug y el historial se conservan); delete no lo es.

Exportación

Exportar publicaciones publicadas

opendocs export informe-q3 --format pdf --json
opendocs export post_abc123 post_def456 --format docx --json     # exporta hasta 10 a la vez
opendocs export informe-q3 --format pdf --theme report --json   # tema personalizado
opendocs export informe-q3 --format pdf --open                  # y ábrelo

La exportación devuelve, para cada documento, una URL de descarga del archivo exportado junto con nombre de archivo, formato, tamaño y número de páginas. La URL expira después de 1 hora; para almacenamiento permanente, usa opendocs save (que guarda en Google Drive) o descarga manual.

Guardar en carpetas de Google Drive

opendocs integrations                        # verifica qué está conectado
opendocs save informe-q3 --folder "Actas"     # guarda el PDF en la carpeta de Drive nombrada "Actas"
opendocs save informe-q3 --folder "Informes" --format docx   # como DOCX
opendocs save informe-q3 --folder "Informes" --format md     # Markdown renderizado

Requiere una integración de Google Drive conectada (opendocs integrations). Las carpetas de Drive nombradas se configuran en https://opendocs.cc/integrations.

Firmas electrónicas

Requiere una integración de DocuSeal conectada.

Paso 1: Redactar una solicitud de firma

opendocs sign request informe-q3 \
  --signer "Cliente=Luna Vega <[email protected]>" \
  --signer "Testigo=Sam Jones <[email protected]>" \
  --json

Esto llama a la API de DocuSeal para preparar la solicitud pero no envía ningún correo. El JSON de respuesta contiene id (el UUID de la solicitud de firma), signers (confirmación de roles y direcciones) y status: draft.

Paso 2: Confirmar y enviar (solo después de que el usuario haya confirmado cada firmante)

opendocs sign send <sign-request-id> --yes --json

Paso 3: Verificar el estado

opendocs sign status <sign-request-id> --json

Muestra { status: "pending"|"completed"|"expired", signed_by: [...], remaining: [...] }.

Otras operaciones de firma:

opendocs sign list --json           # todas las solicitudes de firma (borrador, pendiente, completada)
opendocs sign download <id> --json  # descarga el PDF firmado como un blob con URL efímera

Gestión de equipos

opendocs team invite [email protected] --json          # envía una invitación
opendocs team invite [email protected] --role editor --json # asigna un rol (admin/miembro/espectador/editor)
opendocs team list --json           # miembros del espacio de trabajo activo y sus roles
opendocs team remove usuario-id     # elimina un miembro
opendocs team join                  # aceptar una invitación enviada a tu correo

Comparte una publicación con personas específicas o dominios sin hacerla pública:

opendocs share mi-informe [email protected] @acme.com --json

Hace que mi-informe sea legible para [email protected] y cualquier persona con un correo electrónico @acme.com. Es posible que aún necesiten iniciar sesión en OpenDocs (gratuito).

Temas de exportación

Los temas controlan la apariencia de las exportaciones PDF/DOCX.

opendocs theme                                  # muestra el tema actual y los ajustes preestablecidos disponibles
opendocs theme set --preset editorial --yes     # aplica un ajuste preestablecido de tema (editorial, moderno, informe, documentos, factura)
opendocs theme set --font "Arial" --yes        # elemento único (también: --color, --logo, --footer)
opendocs theme set --preset modern --logo /ruta/al/logo.png --yes  # combinado

--yes se requiere en agentes ya que cambiar el tema afecta todas las exportaciones futuras. Siempre muestra al usuario el opendocs theme actual antes de aplicar un cambio.

Sin Node.js

Si el comando opendocs no está disponible, usa el script shell incluido en esta carpeta de habilidad:

bash scripts/opendocs.sh publish doc.md --json

El script requiere curl y jq. Tiene la misma interfaz que la CLI opendocs e implementa login, publicar, obtener, listar, despublicar, buscar, exportar y whoami. El script determina la ubicación de la carpeta de habilidad a través de la variable de entorno __SKILL_DIR__ (establecida por el tiempo de ejecución del agente) o, si no está establecida, busca scripts/opendocs.sh comenzando desde el directorio de trabajo actual subiendo hasta encontrar la carpeta de esta habilidad (opendocs).

Si ninguno está disponible, usa las herramientas MCP de OpenDocs.

Sobre la habilidad

Esta habilidad está destinada a Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI, Windsurf, Cline, Hermes, Kiro, opencode, OpenClaw, Amp, Goose, Grok Build, y cualquier otro agente de IA que utilice un sistema de skills. Proporciona instrucciones concisas para que el agente use la CLI de OpenDocs para publicar, actualizar, buscar, exportar y gestionar documentos Markdown.

Licencia

MIT

Preguntar en tu IA favorita

Documentación