Configuración

acs2md aplica la configuración desde cuatro fuentes, en orden de prioridad ascendente:

En la práctica, esto permite a los equipos separar valores persistentes de la estacion de trabajo, ajustes puntuales por ejecución y gestion de secretos especifica de la automatizacion.

Ubicación del archivo de configuración

La ubicación predeterminada del archivo de configuración depende del sistema operativo. Ejecuta:

acs2md config where

Uso recomendado:

• guarda los valores no secretos en el archivo de configuración
• inyecta secretos mediante variables de entorno cuando sea posible
• reserva los flags de CLI para overrides puntuales y depuracion

Para crear un archivo de configuración con todos los valores por defecto rellenados:

acs2md config create

Referencia completa del archivo de configuración

# Conexion con Confluence
confluence:
  type: cloud # cloud | server | datacenter — solo se admite cloud
  domain: mycompany.atlassian.net # Dominio de tu instancia de Confluence
  username: you@example.com # Correo de tu cuenta de Atlassian
  api_token: YOUR_API_TOKEN # API token de id.atlassian.com
 
# Comportamiento del cliente HTTP
http:
  client:
    max_retries: 3 # Numero de reintentos tras un fallo
    base_timeout: 500ms # Timeout inicial de la petición
    max_timeout: 30s # Timeout máximo después de reintentos
    proxy: "" # URL del proxy HTTP (ej. http://proxy.corp:8080)
 
# Logging
log:
  level: info # debug | info | warn | error
  format: text # text | json
  file:
    "" # Ruta del log; stdout | stderr | /path/to/file.log
    # Cada ejecución trunca el archivo
 
# Modo debug
debug:
  enabled: false # Activa salida de depuración detallada
  dir: debug # Directorio para artefactos de depuración
 
# Gestión de imágenes
image:
  cache_dir: "" # Define esto solo si quieres fijar una caché compartida
  max_size_bytes: 2097152 # Tamaño máximo por imagen (10 MB por defecto)

Cuando image.cache_dir queda sin definir, las configuraciones generadas suelen omitir la clave para mantener el comportamiento por defecto orientado a la salida. En ese modo, acs2md ancla la caché en <output-dir>/<space-key>/.image_cache junto al archivo de estado, o en ./.image_cache cuando escribe en stdout. La clave del espacio siempre se añade a --output-dir. Define image.cache_dir explícitamente solo cuando necesites una ubicación fija de caché compartida entre exportaciones.

Variables de entorno

Cada clave de configuración puede definirse con una variable de entorno añadiendo el prefijo ACS2MD_ y sustituyendo . por _:

Flags globales de CLI

Estos flags están disponibles en todos los comandos:

Prácticas seguras de configuración

• Prefiere variables de entorno para API tokens en sistemas compartidos o gestionados.
• Usa config create para establecer la estructura esperada del archivo antes de editarlo manualmente.
• Ejecuta doctor después de cambios de configuración para validar juntos licencia, credenciales y conectividad.
• Usa un --config-file personalizado cuando necesites configuraciones aisladas de prueba y produccion en la misma máquina.

Reintentos y límite de peticiones

Todas las peticiones pasan por un único cliente HTTP compartido con un presupuesto de reintentos acotado. Lo controlan tres ajustes:

Con los valores por defecto, los tres reintentos esperan 500 ms, 1 s y 2 s.

Se respeta Retry-After

Cuando Confluence responde a una petición limitada con 429 o 503 e indica un retardo, el cliente espera exactamente ese tiempo en lugar de recurrir a su propia planificación. El servidor sabe cuánto dura su ventana; el cliente no.

Un Retry-After superior a 60 segundos no se respeta: se muestra la respuesta para que decidas tú, en vez de que el comando parezca colgado. La espera es interrumpible, así que Ctrl+C durante una pausa por límite de peticiones surte efecto de inmediato.

Compruébalo con doctor, que informa del backoff total que produce realmente tu configuración y avisa cuando es demasiado corto para aguantar un límite de peticiones:

❌  HTTP retry budget   only 70ms total across 3 retries — too short to wait out
                        a rate limit; raise it with 'acs2md config set
                        http.client.base_timeout 500ms' and ...

Después súbelos:

acs2md config set http.client.base_timeout 500ms
acs2md config set http.client.max_timeout 30s

Un proxy inválido es un error

Un http.client.proxy que no se puede interpretar detiene el comando, en lugar de registrar un aviso y continuar sin proxy. Enviar el tráfico directo en silencio cuando se pidió explícitamente enrutarlo es, en una red corporativa, un fallo por el que merece la pena detenerse.

Detrás de un proxy corporativo

acs2md config set http.client.proxy "http://proxy.corp.example.com:8080"

Con autenticación:

acs2md config set http.client.proxy "http://user:password@proxy.corp.example.com:8080"

Escribir logs en un archivo

acs2md space convert by-key MYSPACE --log-file acs2md.log

Cada ejecución trunca el archivo de log, por lo que siempre contiene solo la salida de la ejecución más reciente. Usa stdout o stderr para enviar logs directamente a tu terminal:

acs2md space convert by-key MYSPACE --log-file stdout