Configuración

acp2md aplica la configuración desde cuatro fuentes, en orden creciente de prioridad:

En la práctica, esto te permite mantener ajustes estables en el archivo de configuración, inyectar secretos mediante variables de entorno y sobrescribir el comportamiento por ejecución con flags de CLI.

Ubicación del archivo de configuración

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

acp2md config where

Uso recomendado:

• mantener los valores no secretos en el archivo de configuración
• inyectar secretos mediante variables de entorno siempre que sea posible
• reservar los flags de CLI para sobrescrituras por ejecución y depuracion

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

acp2md config create

Referencia completa del archivo de configuración

# Confluence connection
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 # Token API de id.atlassian.com
 
# HTTP client behaviour
http:
  client:
    max_retries: 3 # Numero de reintentos en caso de error
    base_timeout: 500ms # Tiempo de espera inicial de la petición
    max_timeout: 30s # Tiempo de espera máximo tras reintentos
    proxy: "" # URL del proxy HTTP (por ej. http://proxy.corp:8080)
 
# Logging
log:
  level: info # debug | info | warn | error
  format: text # text | json
  file:
    "" # Ruta del archivo de log; stdout | stderr | /path/to/file.log
    # Cada ejecución trunca el archivo
 
# Debug mode
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 (por defecto 2 MB)

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, acp2md ancla la caché en <output-dir>/.image_cache junto al archivo de estado, o en ./.image_cache cuando escribe en stdout. 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 se puede definir con una variable de entorno añadiendo el prefijo ACP2MD_ 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 los tokens API en sistemas compartidos o gestionados.
• Usa config create para establecer la forma esperada del archivo antes de editarlo manualmente.
• Ejecuta doctor después de cambios de configuración para validar conjuntamente 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 'acp2md config set
                        http.client.base_timeout 500ms' and ...

Después súbelos:

acp2md config set http.client.base_timeout 500ms
acp2md 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

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

Con autenticación:

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

Logging a un archivo

acp2md page convert by-id 123456 --log-file app.log

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

acp2md page convert by-id 123456 --log-file stdout