Primeros pasos con acs2md: instalacion y uso basico

La forma mas rapida de tener una mala primera impresion de acs2md es lanzar una exportacion masiva antes de que la maquina este lista. La documentacion oficial evita ese error a proposito: va de instalacion a diagnostico y a descubrimiento antes de la primera conversion real.

Ese orden merece mantenerse. Ahorra mucho mas tiempo que cualquier decision inteligente sobre flags al final.

Antes de empezar

La documentacion de cliente enumera los prerequisitos con bastante claridad. Para una primera ejecucion limpia necesitas:

• un sitio Confluence Cloud como mycompany.atlassian.net
• un usuario con acceso de lectura a los espacios que vas a exportar
• una licencia valida de acs2md, o un archivo de licencia local para entornos restringidos
• acceso de red desde la maquina hacia Confluence Cloud
• espacio suficiente en disco para la primera exportacion

acs2md no soporta Server ni Data Center, y los binarios publicados son actualmente para macOS y Linux.

Paso 1: instalar el binario y verificarlo

La documentacion separa la instalacion por plataforma:

• en macOS se distribuye como .pkg universal
• en Linux se distribuye como zip por arquitectura

En ambos casos, la primera comprobacion tecnica deberia ser version y ubicaciones:

acs2md --version
acs2md --version-extended
acs2md config where
acs2md license where

Si esos comandos responden como esperas, la instalacion es correcta y ya sabes donde viven el config y la licencia por defecto.

Paso 2: crear configuracion antes de tocar contenido

Usa el archivo de configuracion por defecto salvo que tengas una razon real para aislar entornos:

acs2md config create
acs2md config where

La documentacion muestra tres formas soportadas de configurar el acceso a Confluence.

Archivo de configuracion

confluence:
  domain: mycompany.atlassian.net
  username: you@example.com
  api_token: YOUR_API_TOKEN

Comandos CLI

acs2md config set confluence.domain mycompany.atlassian.net
acs2md config set confluence.username you@example.com
acs2md config set confluence.api_token YOUR_API_TOKEN

Variables de entorno

export ACS2MD_CONFLUENCE_DOMAIN=mycompany.atlassian.net
export ACS2MD_CONFLUENCE_USERNAME=you@example.com
export ACS2MD_CONFLUENCE_API_TOKEN=YOUR_API_TOKEN

La documentacion de configuracion es explicita con la precedencia: defaults internos, archivo de configuracion, variables de entorno y por ultimo flags CLI. Eso permite guardar valores duraderos en config y mover secretos o overrides a automatizacion.

Paso 3: activar la licencia y validar la maquina

Activa una vez en la maquina objetivo:

acs2md license activate --license-key YOUR_LICENSE_KEY
acs2md license validate

Si trabajas en un entorno aislado, usa --license-file.

Despues ejecuta el comando mas importante del producto:

acs2md doctor

doctor comprueba configuracion, credenciales, conectividad con la API, estado de licencia, identidad de maquina y version en una sola pasada. La documentacion recomienda ejecutarlo justo despues de activar la licencia, tras cambios de credenciales y antes de exportaciones programadas o de cara al cliente. Es la costumbre correcta.

Paso 4: descubrir el espacio antes de convertirlo

La exportacion masiva deberia empezar por descubrimiento, no por optimismo.

Usa space list para confirmar el conjunto objetivo:

acs2md space list --format json --limit 5

Luego inspecciona el espacio concreto:

acs2md space pages by-key TEAMDOCS --format json --limit 10
acs2md space pages by-key TEAMDOCS --tree

La documentacion senala un detalle facil de pasar por alto: space pages usa --format json; el flag antiguo --json ya no aplica a la release actual.

Eso importa porque la salida de descubrimiento suele ir a notas de proyecto, revision de migracion o validacion con cliente.

Paso 5: ejecutar la primera exportacion real

Una vez validados la maquina y el alcance, el primer comando real es sencillo:

acs2md space convert by-key TEAMDOCS --output-dir ./docs

El comportamiento del directorio de salida tambien importa: acs2md anade la key del espacio como subdirectorio, asi que el resultado cae en ./docs/TEAMDOCS y no directamente en ./docs.

Desde ahi, la herramienta:

• obtiene las paginas del espacio
• preserva la jerarquia como carpetas y archivos
• genera Markdown
• crea .convert-sync-state.json
• omite paginas sin cambios en ejecuciones futuras

En la documentacion observada, el comportamiento por defecto es incremental cuando no se pasa ni --sync ni --incremental.

Si algo falla, sigue la ruta de depuracion soportada

La documentacion da un orden de escalado muy limpio:

1. volver a ejecutar acs2md doctor
2. verificar el config activo con acs2md config where
3. confirmar la licencia con acs2md license validate
4. confirmar de nuevo el alcance con space list y space pages
5. reproducir con debug logging y luego generar un support bundle

acs2md --debug --log-file ./acs2md.log space convert by-key TEAMDOCS --output-dir ./docs
acs2md support --log-file ./acs2md.log --output bundle.txt

Ese flujo es mejor que depurar de forma ad hoc porque captura entorno, diagnostico y logs recientes en un solo artefacto.

Por que estos chequeos tambien son evidencia de cumplimiento

La secuencia de configuracion anterior tambien es un flujo silencioso de generacion de evidencia para programas ISO 27001 y SOC 2.

• acs2md doctor produce un chequeo de preparacion determinista que mapea directamente con ISO/IEC 27001:2022 A.8.6 (gestion de capacidad) y A.5.37 (procedimientos operativos documentados) — los operadores pueden demostrar que la validacion previa a la exportacion es repetible y no improvisada.
• acs2md config where y acs2md license validate producen evidencia de que ISO/IEC 27001:2022 A.5.18 (derechos de acceso) y los compromisos de cumplimiento de licencia se comprueban antes de que el contenido salga de la plataforma fuente.
• La via --debug --log-file produce logs aptos para evidencia de SOC 2 CC7.2 (monitorizacion del sistema) y de gestion de incidentes NIS 2. Conservalos en el mismo esquema de retencion que el resto de los logs operativos.

No hace falta meter una segunda herramienta para producir esta evidencia. Los comandos de setup que ibas a lanzar de todos modos ya son el artefacto correcto.

Recomendacion final

La primera ejecucion correcta de acs2md no es solo “instalar y convertir”. Es instalar, verificar, configurar, diagnosticar, descubrir y solo entonces exportar.

Si sigues ese orden, la primera exportacion masiva suele ser directa. Si te lo saltas, empujas errores de setup a la parte mas cara del flujo. Empieza con doctor, confirma el espacio con space pages --tree y deja que la primera exportacion ocurra solo cuando la maquina este obviamente lista.