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 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 las páginas que vas a exportar
• una licencia válida de acp2md obtenida en store.climakers.com/acp2md, o un archivo de licencia local para entornos restringidos
• conectividad de red desde el puesto hasta Confluence Cloud
• permisos de administrador solo para el paso de instalación, si la plataforma lo necesita

Paso 1: Instalar el binario publicado

Elige la sección que corresponda al puesto donde se va a ejecutar la herramienta.

Instalar en macOS

acp2md para macOS se distribuye como un instalador universal .pkg para equipos Apple Silicon e Intel. Los binarios publicados están disponibles en la página de GitHub Releases. Usa la tienda de Climakers para elegir plan, comprar o activar la licencia, y descarga después el instalador publicado desde GitHub.

Para descargar el instalador publicado y su checksum:

VERSION=v1.0.0
curl -L -o acp2md.pkg \
  "https://github.com/climakers/ac2md/releases/download/${VERSION}/acp2md-${VERSION}-darwin-universal.pkg"
curl -L -o acp2md.pkg.sha256 \
  "https://github.com/climakers/ac2md/releases/download/${VERSION}/acp2md-${VERSION}-darwin-universal.sha256"

Valida el checksum antes de instalar:

echo "$(cat acp2md.pkg.sha256)  acp2md.pkg" | shasum -a 256 -c -

Después, abre acp2md.pkg con doble clic en Finder y sigue el asistente de instalación, o instálalo sin interacción:

sudo installer -pkg acp2md.pkg -target /

Instalar en Linux

acp2md para Linux se distribuye como un archivo zip por arquitectura en la página de GitHub Releases. La versión publicada también incluye un archivo de checksum y un bundle opcional de Sigstore para equipos con requisitos de verificación de la cadena de suministro.

VERSION=v1.0.0
ARCH=amd64
curl -L -o acp2md.zip \
  "https://github.com/climakers/ac2md/releases/download/${VERSION}/acp2md-${VERSION}-linux-${ARCH}.zip"
curl -L -o acp2md.zip.sha256 \
  "https://github.com/climakers/ac2md/releases/download/${VERSION}/acp2md-${VERSION}-linux-${ARCH}.sha256"

Para validar el checksum descargado:

echo "$(cat acp2md.zip.sha256)  acp2md.zip" | sha256sum -c -

Si también necesitas verificar procedencia, descarga el bundle opcional de Sigstore y valídalo con Cosign:

curl -L -o acp2md.sigstore.json \
  "https://github.com/climakers/ac2md/releases/download/${VERSION}/acp2md-${VERSION}-linux-${ARCH}.sigstore.json"
unzip -q acp2md.zip
cosign verify-blob \
  --bundle acp2md.sigstore.json \
  --certificate-identity-regexp 'https://github\.com/climakers/ac2md/\.github/workflows/release\.yaml@.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ./acp2md

Descomprime y mueve el binario a PATH:

unzip -q -o acp2md.zip
chmod +x acp2md
sudo mv acp2md /usr/local/bin/acp2md

Actualmente no se publican binarios .exe para Windows. Si lo necesitas, puedes compilarlo desde el código fuente, pero los artefactos publicados para clientes se limitan a macOS y Linux.

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:

acp2md --version
acp2md --version-extended
acp2md config where
acp2md license where

Verificado en una estación macOS real:

$ acp2md --version
v1.0.0

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

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

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

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

Ejecuta la comprobación de estado antes de apuntar a una página real:

acp2md doctor

Esto confirma estado de 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.

acp2md config create
acp2md 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

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

Usar variables de entorno

export ACP2MD_CONFLUENCE_DOMAIN=mycompany.atlassian.net
export ACP2MD_CONFLUENCE_USERNAME=you@example.com
export ACP2MD_CONFLUENCE_API_TOKEN=YOUR_API_TOKEN

env:
  ACP2MD_CONFLUENCE_DOMAIN: mycompany.atlassian.net
  ACP2MD_CONFLUENCE_USERNAME: ${{ secrets.CONFLUENCE_USERNAME }}
  ACP2MD_CONFLUENCE_API_TOKEN: ${{ secrets.CONFLUENCE_API_TOKEN }}

Paso 7: Activar la licencia adquirida

Activa la licencia una sola vez con la clave adquirida:

acp2md 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:

acp2md license activate --license-file ./license.bin

Comprueba después el estado de la licencia:

acp2md license validate

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

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

acp2md doctor

Es la forma más rápida de detectar problemas antes de empezar a exportar contenido del cliente.

Salida de ejemplo de una sesión real, con datos anonimizados:

🩺 Running diagnostics for acp2md v1.0.0...

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

📊 Result: all 7 checks passed

🎉 acp2md is ready to use!

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

Paso 9: Descubrir el objetivo correcto antes de exportar

Cuando se salta directamente a un comando de conversión, el error más habitual es apuntar al espacio o a la página equivocados. Usa primero los comandos de descubrimiento.

# Lista los espacios disponibles
acp2md space list --limit 5
 
# Lista las páginas de un espacio conocido
acp2md space pages by-key TEAMDOCS --limit 10
 
# Muestra la jerarquía cuando la ubicación de la página importa
acp2md space pages by-key TEAMDOCS --tree

Paso 10: Ejecutar la primera exportación real

Localiza el ID de página en la URL de Confluence. Es el número que aparece en /pages/123456/.

acp2md page convert by-id 123456 --output my-page.md

También puedes convertir por título:

acp2md page convert by-title "Título de mi página" --output my-page.md

Si ya tienes la URL del navegador, también puedes exportar directamente desde ella:

acp2md page convert by-url "https://mycompany.atlassian.net/wiki/spaces/ENG/pages/123456/My+Page" --output my-page.md

Si algo falla

• vuelve a ejecutar acp2md doctor
• comprueba el archivo activo con acp2md config where
• valida la licencia con acp2md license validate
• verifica el 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 páginas para ver toda la superficie de conversión
• Recuperar páginas cuando necesitas salida nativa ADF o Storage
• Conteo y análisis para análisis estructural antes de una migración o ingesta en IA
• Flujos y comandos para escenarios listos para ejecutar en clientes
• Configuración para entender la prioridad de configuración, las variables de entorno y los ajustes de proxy