Configuración

El CLI tecsas3-cli resuelve su configuración combinando flags del comando, variables de entorno, un archivo TOML local al proyecto y un archivo TOML global del usuario. Los secretos (tokens) nunca viven en estos archivos: se gestionan por separado en authentication. La regla de oro es: lo más específico pisa a lo más general. Si un flag y un archivo de config definen el mismo campo, gana el flag; si un env y el archivo global lo definen, gana el env; y así sucesivamente.

Precedencia de configuración

De mayor a menor prioridad. El CLI evalúa cada capa en este orden y la última escritura gana:

Prioridad	Origen	Ejemplo
1 (mayor)	Flags del comando	`--tenant ebs-norte --format json`
2	Variables de entorno	`export TECSAS3_TENANT=ebs-norte`
3	`./.tecsas3/config.toml` (proyecto)	`tenant = "ebs-norte"` bajo `[profile.demo]`
4 (menor)	`~/.tecsas3/config.toml` (global)	`base_url = "https://dev.tecsas3.com"` bajo `[profile.demo]`

El archivo local pisa al global para todos los campos del mismo perfil. Si el campo no está definido en ninguna capa, se usa el valor por defecto del runtime (DEFAULT_BASE_URL = "https://dev.tecsas3.com", DEFAULT_TIMEOUT = 30.0).

Variables de entorno

Todas las variables usan el prefijo TECSAS3_ y son consumidas por pydantic-settings. Equivalen 1:1 a los flags del CLI.

Variable	Tipo	Default	Descripción
`TECSAS3_BASE_URL`	str	`https://dev.tecsas3.com`	URL base del backend. Debe ser HTTPS salvo `localhost`.
`TECSAS3_TOKEN`	str	—	Token literal (DRF Token o JWT). Prevalece sobre keyring.
`TECSAS3_TENANT`	str	—	Slug del tenant activo. Se envía como `X-Tenant-Slug`.
`TECSAS3_TENANT_ORG`	int	—	ID numérico del `TenantOrg`. Se envía como `X-Tenant-Org-ID`.
`TECSAS3_PLAN_ID`	int	—	ID numérico del `PlanGestionEcosistema`. Se envía como `X-Plan-ID`.
`TECSAS3_AUTH_SCHEME`	`token` \| `jwt`	`token`	Esquema de autenticación. Auto-detección puede sobrescribir.
`TECSAS3_OUTPUT_FORMAT`	`table` \| `json` \| `yaml` \| `csv`	`table`	Formato por defecto. Equivale al flag `--format`.
`TECSAS3_NO_COLOR`	bool	`false`	Desactiva colores en `rich`. Respeta además el estándar `NO_COLOR=1`.
`TECSAS3_TIMEOUT`	float	`30.0`	Timeout en segundos para `httpx` (connect timeout fijo a 10s).
`TECSAS3_PROFILE`	str	`demo`	Perfil activo. Selecciona la sección `[profile.<name>]` del TOML.
`TECSAS3_FORMAT`	str	—	Alias histórico de `TECSAS3_OUTPUT_FORMAT`.
`NO_COLOR`	bool	—	Estándar externo (`https://no-color.org`). Si está presente, fuerza `--no-color`.

Archivos TOML

Los perfiles viven bajo la clave profile.<nombre> en uno o ambos archivos. El formato es estable y compatible con tomllib (Python 3.11+).

`~/.tecsas3/config.toml` (global)

Es el archivo que tecsas3 config show lee primero. Lo crea el sub-comando tecsas3 config set con permisos 0600; el directorio padre se crea con 0700.

# ~/.tecsas3/config.toml
[profile.demo]
base_url    = "https://dev.tecsas3.com"
tenant      = "ebs-norte"
tenant_org  = 1
plan_id     = 42
auth_scheme = "token"
timeout     = 30.0

[profile.prod]
base_url    = "https://api.tecsas3.com"
tenant      = "ebs-andina"
auth_scheme = "jwt"
timeout     = 15.0

`./.tecsas3/config.toml` (proyecto)

Vive en la raíz del repo y se versiona con el código. Sirve para fijar el tenant y plan_id por proyecto sin contaminar el global. Pisar al global para campos del mismo perfil.

# ./.tecsas3/config.toml  (commit-friendly)
[profile.demo]
tenant      = "ebs-piloto-cordoba"
plan_id     = 7
timeout     = 20.0

El archivo config.toml no contiene secretos. Si necesitas versionar credenciales, usa variables de entorno o un secreto de CI. Cualquier TECSAS3_TOKEN o clave API en este archivo es un anti-patrón: queda expuesto en el historial de git.

HTTPS obligatorio

load_settings rechaza cualquier base_url que use http:// salvo que el host sea localhost, 127.0.0.1 o ::1. Esto protege contra fugas accidentales de Authorization headers en redes no confiables.

# OK: producción con TLS.
tecsas3 --base-url https://api.tecsas3.com paciente list

# OK: desarrollo local sin TLS.
tecsas3 --base-url http://localhost:8000 paciente list

# ERROR: ConfigError (exit 4).
tecsas3 --base-url http://api.tecsas3.com paciente list
# base_url 'http://api.tecsas3.com' usa HTTP sin cifrar.
# Usa HTTPS en producción o localhost en desarrollo.

Si necesitas conectarte a un proxy local sobre HTTP, usa http://localhost:... o configura verify_tls = false sólo bajo perfil de desarrollo.

Sub-comandos de `tecsas3 config`

Sub-comando	Descripción
`config set <clave> <valor>`	Escribe un campo en el perfil activo. Tipos booleanos y numéricos se castean automáticamente.
`config show`	Imprime la configuración efectiva (perfil + env + capas combinadas) en `table`, `json` o `yaml`.
`config get <clave>`	Devuelve el valor resuelto para una clave concreta del perfil activo.
`config unset <clave>`	Elimina la clave del TOML del perfil activo.
`config list`	Lista los perfiles definidos en los TOML global y local.

Ejemplos de uso

# Configurar el tenant activo del perfil demo.
tecsas3 config set tenant ebs-norte

# Fijar la base URL de producción.
tecsas3 config set base-url https://api.tecsas3.com --profile prod

# Inspección de la configuración efectiva.
tecsas3 config show --json --no-input

# Sobrescribir el formato por defecto para una sesión.
TECSAS3_OUTPUT_FORMAT=yaml tecsas3 paciente list

Verificación rápida

# Ping con la configuración efectiva.
tecsas3 --json --no-input ping
# {"status": "ok", "base_url": "https://dev.tecsas3.com", "tenant": "ebs-norte", ...}

# Describir las capacidades detectadas.
tecsas3 --json --no-input util agent-info

Troubleshooting

`ConfigError: base_url ... usa HTTP sin cifrar`

El CLI rechaza http:// salvo localhost, 127.0.0.1 o ::1. Tres soluciones posibles:

# 1. Usar HTTPS (preferido).
tecsas3 --base-url https://api.tecsas3.com paciente list

# 2. Desarrollo local con HTTP plano.
tecsas3 --base-url http://localhost:8000 paciente list

# 3. Proxy local con TLS terminado.
tecsas3 --base-url https://localhost:8443 paciente list --verify-tls=false

`ConfigError: Falta configuración de tenant`

Las rutas bajo /api/, /paciente/, /familia/, /agente/api/, /eps_fhir/, etc. requieren X-Tenant-Slug. Si el comando falla con exit 4, define el tenant:

# Vía flag por comando.
tecsas3 --tenant ebs-norte paciente list

# Vía configuración persistente.
tecsas3 config set tenant ebs-norte

# Vía env var (ideal para CI por entorno).
export TECSAS3_TENANT=ebs-norte

El perfil activo no es el esperado

# Verificar.
tecsas3 config show --json --no-input | jq '.profile'

# Forzar.
tecsas3 --profile prod paciente list
export TECSAS3_PROFILE=prod

Cambios en `config.toml` no se reflejan

El runtime cachea la configuración al inicio del proceso. Si editas el TOML manualmente, ejecuta un nuevo proceso del CLI. La recarga en caliente no está soportada.

# Editar.
$EDITOR ~/.tecsas3/config.toml

# Validar en un proceso nuevo.
tecsas3 config show --json --no-input

Múltiples perfiles y entornos

# Definir tres perfiles en ~/.tecsas3/config.toml.
tecsas3 --profile dev  config set base-url https://dev.tecsas3.com
tecsas3 --profile stg  config set base-url https://stg.tecsas3.com
tecsas3 --profile prod config set base-url https://api.tecsas3.com

# Uso diario.
tecsas3 --profile prod --json --no-input paciente list

Variables de entorno y TOML entran en conflicto

La precedencia es: flag > env > TOML local > TOML global. Si exportas TECSAS3_BASE_URL=https://... y a la vez lo defines en el TOML, gana la env. Para depurar, ejecuta tecsas3 config show --json y compara con tu env.

Siguientes pasos

Profundiza en los formatos de salida soportados.
Consulta los códigos de salida para scripting robusto.
Revisa la redacción PHI activa por defecto en logs.

Empezar

Conceptos

Guías

Soporte

Precedencia de configuración

Variables de entorno

Archivos TOML

`~/.tecsas3/config.toml` (global)

`./.tecsas3/config.toml` (proyecto)

HTTPS obligatorio

Sub-comandos de `tecsas3 config`

Ejemplos de uso

Verificación rápida

Troubleshooting

`ConfigError: base_url ... usa HTTP sin cifrar`

`ConfigError: Falta configuración de tenant`

El perfil activo no es el esperado

Cambios en `config.toml` no se reflejan

Múltiples perfiles y entornos

Variables de entorno y TOML entran en conflicto

Siguientes pasos

​Precedencia de configuración

​Variables de entorno

​Archivos TOML

​~/.tecsas3/config.toml (global)

​./.tecsas3/config.toml (proyecto)

​HTTPS obligatorio

​Sub-comandos de tecsas3 config

​Ejemplos de uso

​Verificación rápida

​Troubleshooting

​ConfigError: base_url ... usa HTTP sin cifrar

​ConfigError: Falta configuración de tenant

​El perfil activo no es el esperado

​Cambios en config.toml no se reflejan

​Múltiples perfiles y entornos

​Variables de entorno y TOML entran en conflicto

​Siguientes pasos

Precedencia de configuración

Variables de entorno

Archivos TOML

`~/.tecsas3/config.toml` (global)

`./.tecsas3/config.toml` (proyecto)

HTTPS obligatorio

Sub-comandos de `tecsas3 config`

Ejemplos de uso

Verificación rápida

Troubleshooting

`ConfigError: base_url ... usa HTTP sin cifrar`

`ConfigError: Falta configuración de tenant`

El perfil activo no es el esperado

Cambios en `config.toml` no se reflejan

Múltiples perfiles y entornos

Variables de entorno y TOML entran en conflicto

Siguientes pasos