Instalación y configuración inicial

Esta es la página recomendada para nuevos clientes. Lleva un puesto desde “nada instalado” hasta “primera exportación masiva completada correctamente” siguiendo el orden adecuado.

Antes de empezar

• un sitio de Confluence Cloud como mycompany.atlassian.net
• una cuenta con permiso de lectura sobre los espacios que vas a exportar
• una licencia válida de acs2md obtenida en store.climakers.com/acs2md, o un archivo de licencia local para entornos restringidos
• conectividad de red desde el puesto hasta Confluence Cloud
• espacio suficiente en disco para la primera exportación
• permisos de administrador solo para el paso de instalación, si la plataforma lo necesita

Paso 1: Descargar e instalar el paquete publicado

acs2md se distribuye a través de la tienda de Climakers. Compra un plan o inicia una prueba gratuita en store.climakers.com/acs2md. Tras la compra, la página de tu pedido y el correo de confirmación incluyen un enlace de descarga para cada paquete publicado y su archivo de checksum .sha256 correspondiente:

• acs2md-<version>-darwin-universal.pkg — instalador de macOS (Apple Silicon e Intel)
• acs2md-<version>-linux-amd64.zip — Linux x86-64
• acs2md-<version>-linux-arm64.zip — Linux ARM64
• un archivo de checksum .sha256 correspondiente para cada paquete

Descarga el paquete de tu plataforma junto con su archivo .sha256 en la misma carpeta y sigue después la sección que corresponda a tu puesto de trabajo.

Instalar en macOS

acs2md para macOS es un instalador universal .pkg firmado y notarizado para equipos Apple Silicon e Intel. Descarga acs2md-<version>-darwin-universal.pkg y su .sha256 desde tu pedido, luego valida e instala (define VERSION con la versión que aparece en tu pedido):

VERSION=v1.0.0   # use la versión que aparece en tu pedido de Climakers
shasum -a 256 -c "acs2md-${VERSION}-darwin-universal.sha256"
sudo installer -pkg "acs2md-${VERSION}-darwin-universal.pkg" -target /

También puedes abrir el .pkg con doble clic en Finder y seguir el asistente de instalación.

Instalar en Linux

acs2md para Linux se distribuye como un archivo .zip por arquitectura con su archivo de checksum .sha256 correspondiente. Descarga el archivo de la arquitectura de tu CPU (amd64 o arm64) y su .sha256 desde tu pedido, luego valida y coloca el binario en PATH:

VERSION=v1.0.0   # use la versión que aparece en tu pedido de Climakers
ARCH=amd64       # o arm64
sha256sum -c "acs2md-${VERSION}-linux-${ARCH}.sha256"
unzip -q -o "acs2md-${VERSION}-linux-${ARCH}.zip"
chmod +x acs2md
sudo mv acs2md /usr/local/bin/acs2md

Paso 2: Confirmar la instalación

Verifica el binario, la ubicación del archivo de configuración y la de la licencia antes de seguir:

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

Verificado en una estación macOS real:

$ acs2md --version
v1.0.0

$ acs2md --version-extended
acs2md v1.0.0 (darwin/arm64, built 2026-03-29T08:23:49Z)

$ acs2md config where
/Users/<user>/Library/Application Support/acs2md/config.yaml

$ acs2md license where
/Users/<user>/Library/Application Support/acs2md/license.bin

Paso 3: Ejecutar diagnóstico antes de tocar contenido del cliente

Ejecuta la comprobación de estado antes de iniciar una exportación real:

acs2md doctor

Esto valida licencia, configuración, identidad de máquina y conectividad con Confluence en un solo paso.

Paso 4: Crear el archivo de configuración

Usa el archivo de configuración por defecto salvo que tengas una razón clara para aislar entornos.

acs2md config create
acs2md config where

Abre la ruta indicada en el editor que prefieras.

Paso 5: Generar un token API de Confluence

Genera un token API en id.atlassian.com/manage-profile/security/api-tokens.

Necesitas:

• el dominio de Confluence, por ejemplo mycompany.atlassian.net
• el correo de la cuenta de Atlassian
• el token API generado

Paso 6: Configurar las credenciales de Confluence

Usar el archivo de configuración

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

Usar 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

Usar 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

env:
  ACS2MD_CONFLUENCE_DOMAIN: mycompany.atlassian.net
  ACS2MD_CONFLUENCE_USERNAME: ${{ secrets.CONFLUENCE_USERNAME }}
  ACS2MD_CONFLUENCE_API_TOKEN: ${{ secrets.CONFLUENCE_API_TOKEN }}

Paso 7: Activar la licencia adquirida

Activa la licencia una sola vez con la clave adquirida:

acs2md license activate --license-key YOUR_LICENSE_KEY

Si trabajas en un entorno aislado o restringido, activa en su lugar el archivo de licencia local vinculado a máquina:

acs2md license activate --license-file ./license.bin

Comprueba después el estado de la licencia:

acs2md license validate

Paso 8: Repetir el diagnóstico de extremo a extremo

Después de configurar credenciales y activar licencia, vuelve a ejecutar:

acs2md doctor

Salida de ejemplo de una sesión real, con datos del tenant y de la máquina anonimizados:

🩺 Running diagnostics for acs2md v1.0.0...

  ✅  Configuration file           /Users/<user>/Library/Application Support/acs2md/config.yaml
  ✅  Confluence credentials       <tenant>.atlassian.net (user: <redacted>)
  ✅  Confluence API               connected (310ms)
  ✅  License file                 loaded (<redacted>)
  ✅  License validation           active (<redacted>)
  ✅  Machine ID                   <redacted>
  ✅  Version                      acs2md v1.0.0 (darwin/arm64, built 2026-03-29T08:23:49Z)

📊 Result: all 7 checks passed

🎉 acs2md is ready to use!

Si necesitas todos los metadatos de compilación fuera de doctor, usa acs2md --version-extended.

Paso 9: Descubrir el espacio objetivo correcto

Los flujos masivos deben empezar con descubrimiento, no con conversión.

# Lista los espacios disponibles
acs2md space list --format json --limit 5
 
# Revisa las páginas de un espacio objetivo
acs2md space pages by-key TEAMDOCS --format json --limit 10
 
# Revisa la jerarquía antes de convertir
acs2md space pages by-key TEAMDOCS --tree

En v1.0.0, ambos comandos de descubrimiento devuelven objetos JSON estructurados, no arrays planos. space pages usa --format json; el flag legado --json ya no es válido.

Paso 10: Ejecutar la primera exportación masiva real

Localiza la clave del espacio en la URL de Confluence. Aparece después de /wiki/spaces/ y suele ser una cadena corta en mayúsculas como DOCS o MYSPACE.

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

Si todavía no está clara la clave del espacio, lista primero los espacios accesibles:

acs2md space list

Si algo falla

• vuelve a ejecutar acs2md doctor
• comprueba el archivo activo con acs2md config where
• valida la licencia con acs2md license validate
• verifica el espacio objetivo con space list y space pages
• usa el comando support si necesitas compartir un paquete de diagnóstico con Climakers

Qué leer a continuación

• Convertir espacios para ver toda la superficie de exportación masiva
• Recuperar contenido del espacio para recuperar cargas nativas
• Listar espacios y Listar páginas para los flujos de descubrimiento
• Flujos y comandos para escenarios operativos listos para usar con clientes
• Configuración para entender la prioridad de configuración, las variables de entorno y los ajustes de proxy