​
Preguntas frecuentes

Respuestas concisas a las preguntas más habituales sobre el Ecosistema Salud TecsaS3, el CLI tecsas3-cli y su integración con agentes de IA. Si tu pregunta no aparece aquí, revisa la guía de troubleshooting o abre un issue en GitHub.

​
General

​
¿Qué es TecsaS3?

TecsaS3 es una plataforma de salud rural para Colombia, construida sobre Django + HL7 FHIR R4, multi-tenant, con HCE (Historia Clínica Electrónica), pipelines de IA y reporting RIPS/FEV. Reúne pacientes, familias, agentes comunitarios, riesgo, agenda, facturación y epidemiología en un solo backend operativo.

​
¿Qué es tecsas3-cli?

tecsas3-cli es el cliente oficial de línea de comandos del ecosistema TecsaS3. Expone 16 recursos (auth, util, paciente, persona, familia, agente, riesgo, hce, fhir, examen, batch, dashboard, ia, reportes, export, pipe) sobre el mismo backend que consume la web, con salida JSON determinista (--json --no-input) lista para agentes de IA.

​
¿Es gratis?

El CLI es open source bajo licencia MIT. El uso del backend TecsaS3 (planes, tenant, pacientes, FHIR) está sujeto al contrato comercial firmado con Tecsa S3. Los entornos dev.tecsas3.com y de evaluación son gratuitos con cuotas limitadas — consulta con soporte@tecsas3.com.

​
¿Qué licencia tiene?

tecsas3-cli se distribuye bajo MIT License (cli/LICENSE). La skill portable incluida es MIT también. El backend TecsaS3 es software propietario; consulta los términos específicos de tu despliegue.

​
Instalación

​
¿Qué versión de Python necesito?

Python ≥ 3.11. La versión 3.12 también está soportada y es la recomendada para nuevos proyectos. El paquete declara requires-python = ">=3.11" y se prueba en CPython 3.11 y 3.12 en CI.

​
¿Funciona en Windows, macOS y Linux?

Sí. El CLI es multiplataforma; los wheels se publican para manylinux, musllinux, macos y windows en PyPI. La única dependencia de plataforma es keyring, que se adapta al Credential Manager nativo de cada sistema. En Windows sin Credential Manager, el CLI cae a archivo con permisos 0600.

​
¿Puedo instalarlo en un entorno virtual?

Sí, y es la opción recomendada. pip, uv, poetry y conda funcionan; el CLI no requiere nada fuera del árbol de dependencias declarado en pyproject.toml. La suite de tests incluye tests/test_smoke.py que valida 17 puntos de entrada en un venv limpio.

​
Multi-tenant

​
¿Cómo cambio de tenant sin re-autenticar?

Crea un perfil por tenant y usa auth use para alternar:
Los headers X-Tenant-Slug, X-Tenant-Org-ID y X-Plan-ID se derivan del perfil activo en cada request.

​
¿Qué pasa si mi tenant está deshabilitado?

El backend responde con 403 tenant_disabled. El CLI muestra el mensaje y aborta con código de salida 5. Contacta al admin del tenant para rehabilitar el acceso; no hay bypass local.

​
¿Los datos cruzan tenants?

No. Cada request viaja con X-Tenant-Slug y se filtra server-side a nivel ORM (PlanFilteredManager y middleware de aislamiento). El CLI nunca concatena datos de varios tenants en una misma respuesta, y los pipelines tampoco pueden referenciar un step de otro tenant. Consulta docs/ARQUITECTURA_PLAN_DATA_ISOLATION.md para los detalles del modelo.

​
Seguridad y PHI

​
¿Los tokens se guardan en texto plano?

Por defecto, no. El CLI usa keyring (Keychain en macOS, Credential Manager en Windows, Secret Service en Linux) cuando está disponible. En sistemas sin keyring cae a ~/.tecsas3/credentials con permisos 0600. Verifica con tecsas3 util security-check.

​
¿Qué campos se redactan?

Identificadores personales (nombres, apellidos, documento, teléfono, email, dirección, IDs de historia clínica) se redactan por defecto en las salidas a terminal. La redacción es opt-out por comando con --no-redact, no opt-in. Los logs persistentes del backend mantienen la PHI completa bajo control de auditoría; el CLI nunca la escribe a stderr ni a archivos de log locales.

​
¿HTTPS es obligatorio?

Sí, en producción. El CLI rechaza http:// salvo localhost. En CI o desarrollo local puedes usar http://localhost:8000 o configurar un proxy TLS. Para entornos air-gapped, contacta a soporte para emitir un certificado interno.

​
¿El CLI loguea PHI?

No. El CLI no escribe logs persistentes por defecto. Los flags --verbose y --debug van a stderr con redacción PHI activa. Si rediriges la salida a un archivo, recuerda auditarlo bajo las mismas políticas que el backend.

​
Agentes de IA

​
¿Qué agentes soporta?

La skill portable de tecsas3-cli se publica en 9 destinos: mcode (MiniMax Code), pi, claude-code, opencode, hermes, openclaw, cursor, continue y codex. La lista y las rutas candidatas se listan con:

​
¿Cómo instalo la skill en mi agente?

El instalador copia la skill al directorio estándar de cada agente (~/.claude/skills/, ~/.pi/skills/, ~/.minimax-code/skills/, etc.) y nunca pisa archivos existentes sin --force.

​
¿Funciona con pi, mcode, claude-code?

Sí. La skill está escrita en Markdown plano con frontmatter YAML 2026-spec, sin componentes específicos de ningún agente. La verificación empírica (17/17 checks) está documentada en docs/COMPATIBILIDAD_AGENTES_2026.md dentro del repositorio.

​
¿La skill se actualiza automáticamente?

No. La skill se copia al directorio del agente y queda versionada con el CLI. Al actualizar el paquete con pip install -U tecsas3-cli, vuelve a correr tecsas3 install-skill --all para refrescar. En CI puedes añadir ese comando al job de release.

​
Pipelines

​
¿Qué es un pipeline?

Un pipeline es un workflow declarativo en YAML que encadena varios comandos del CLI pasándose datos entre steps vía placeholders. Vive en un archivo versionado y se ejecuta con tecsas3 pipe run pipeline.yml. Es la forma canónica de orquestar automatizaciones multi-tenant reproducibles.

​
¿Cómo paso datos entre steps?

Con placeholders ${steps.<nombre>.<campo>} en los args de un step. Por defecto, cada step expone stdout, stderr, success, exit_code y la salida JSON parseada si aplica:
También puedes usar variables de entorno con ${env.MI_VAR} y anidar accesos con ${steps.listar.data.results[0].id_paciente}.

​
¿Puedo hacer un pipeline que continúe ante errores?

Sí, con on_error: continue por step o continue_on_error: true a nivel de pipeline. El step que falla se marca con success: false y los siguientes se ejecutan igualmente. La salida agrega un campo errors por step y un summary final con los totales.