TecsaS3 CLI

tecsas3-cli es el cliente CLI oficial del Ecosistema Salud TecsaS3 para entornos rurales de Colombia. Desde un solo binario puedes listar y crear pacientes, consultar y operar historias clínicas (HCE), exportar recursos FHIR, automatizar operaciones de IA y ejecutar pipelines declarativos sobre cualquier tenant — todo con --json --no-input para que cualquier agente de IA (mcode, pi, claude-code, opencode, hermes, openclaw, cursor, continue, codex) pueda operarlo de forma determinista.

Instalar y configurar el CLI

Instalación vía agente (recomendada)
Instalación manual

Pega este bloque en tu agente (mcode, pi, claude-code, opencode, hermes, openclaw, cursor, continue o codex) y deja que él se encargue de la instalación:

Please install tecsas3-cli (https://github.com/tecsas3/saludrural/tree/main/cli) for me in three steps:
  1. pip install tecsas3-cli
  2. tecsas3 auth login --user <USER> --password <PASSWORD> --scheme jwt
     (alternatively, export TECSAS3_TOKEN=<token> if you already have one)
  3. tecsas3 install-skill install --agent mcode
     (replace `mcode` with `pi`, `claude-code`, `opencode`, `hermes`, `openclaw`, `cursor`, `continue` or `codex`; or pass `--all` to install in every detected agent)
After install, run `tecsas3 util agent-info --json --no-input` to confirm the resources are discoverable.

El agente ejecutará los pasos, solicitará la contraseña de forma segura (o usará la variable de entorno) y dejará la skill instalada en su carpeta de skills local.

Instalar el wheel

pip install tecsas3-cli

Verifica con tecsas3 --version — debe devolver 0.4.1.

Autenticar

tecsas3 auth login --user <USER> --password <PASSWORD> --scheme jwt

Si ya tienes un token emitido por el backend, exporta la variable de entorno y omite el login:

export TECSAS3_TOKEN=<token>

El CLI solo opera contra endpoints HTTPS. La contraseña nunca se almacena en texto plano: se envía al backend, que devuelve un token JWT (o DRF legacy) y se guarda en keyring del sistema. Si keyring no está disponible, cae a ~/.tecsas3/credentials con permisos 0600. Ejecuta tecsas3 util security-check para auditar los permisos.

Instalar la skill

# Instalar para un agente específico
tecsas3 install-skill install --agent mcode

# O instalar en todos los agentes cuyo directorio de skills exista
tecsas3 install-skill --all

# Listar agentes soportados y rutas candidatas
tecsas3 install-skill --list

El comando copia SKILL.md (con frontmatter YAML 2026-spec) a rutas como ~/.minimax-code/skills/tecsas3-cli/SKILL.md, ~/.pi/skills/tecsas3-cli/SKILL.md, ~/.claude/skills/tecsas3-cli/SKILL.md, ~/.opencode/skills/tecsas3-cli/SKILL.md, ~/.hermes/skills/tecsas3-cli/SKILL.md, ~/.cursor/skills/tecsas3-cli/SKILL.md, ~/.continue/skills/tecsas3-cli/SKILL.md, ~/.codex/skills/tecsas3-cli/SKILL.md y ~/.claw/skills/tecsas3-cli/SKILL.md, según el agente. El archivo resultante se crea con permisos 0600.

Usar el CLI

Vía agente
Comandos manuales

Pega estas instrucciones en lenguaje natural a tu agente y él se encargará de mapearlas al comando correcto.

"Lista los 5 primeros pacientes del tenant activo en formato JSON."
"Busca el paciente con cédula 12345678 y devuélveme sus historias clínicas."
"Exporta el bundle FHIR completo del paciente con UUID <uuid> a la salida estándar."
"Crea un chat IA con título 'Triage rural' asociado al paciente <uuid> y déjalo listo para enviar preguntas."
"Ejecuta el reporte programado con id 7 y muéstrame el estado de la ejecución."
"Corre el pipeline en ./pipelines/triage.yml y propaga los placeholders ${step.path}."
"Genera un heatmap de ubicaciones de agentes excluyendo puntos con GPS inválido (lat=0, lon=0)."
"Tráeme el resumen del dashboard del tenant demo."

Equivalentes deterministas (todos compatibles con --json --no-input, que puedes colocar antes o después del subcomando):

# Listar pacientes del tenant activo
tecsas3 paciente list --json --no-input

# Consultar historias clínicas de un paciente por ID interno
tecsas3 hce historia-list --paciente 42 --json --no-input

# Exportar un bundle FHIR por UUID de paciente
tecsas3 fhir export-fhir-bundle --paciente <uuid> --json --no-input

# Crear un chat IA asociado a un paciente
tecsas3 ia chat-create \
  --titulo "Triage rural" \
  --paciente-uuid <uuid> \
  --tipo general \
  --json --no-input

# Ejecutar un reporte programado por su ID
tecsas3 reportes execute 7 --json --no-input

# Ejecutar un pipeline declarativo
tecsas3 pipe run pipeline.yml --json --no-input

# Ejecutar un batch de operaciones desde JSON
tecsas3 batch run archivo.json --json --no-input

# Generar heatmap de ubicaciones de agentes
tecsas3 agente heatmap --exclude-invalid --json --no-input

# Resumen del dashboard del plan/tenant activo
tecsas3 dashboard resumen --json --no-input

Dashboard del CLI

tecsas3 sin argumentos imprime la ayuda completa con todos los subcomandos. tecsas3 util agent-info (con --json --no-input para JSON puro) devuelve la autodescripción estructurada del CLI que consumen los agentes LLM: lista de recursos, acciones, parámetros, códigos de salida, golden paths y ejemplos conversacionales. Screenshot de tecsas3 util agent-info

El documento devuelto contiene cuatro bloques clave:

resources — catálogo de los 16 recursos (auth, paciente, persona, familia, agente, riesgo, hce, fhir, examen, batch, dashboard, ia, reportes, export, pipe, util) con sus acciones y endpoints REST.
golden_paths — 25 flujos verificados (buscar paciente, exportar FHIR, ejecutar pipeline, etc.) con su comando canónico y versión --json.
agent_modes — modos soportados por el CLI: human, json, no-input.
examples — pares user/agent para que el LLM aprenda el contrato conversacional sin leer documentación externa.

Úsalo como punto de entrada en skills y system prompts para que el agente descubra el CLI de forma autónoma.

Resumen de capacidades

Capacidad	Comando básico	Descripción
Pacientes	`tecsas3 paciente list`	Lista paginada con `id`, `nombre_completo`, `nivel_riesgo` y EAPB. Filtros por color de semáforo y código EAPB.
Historia clínica	`tecsas3 hce historia-list`	Historias por paciente y estado (`BOR`, `ABI`, `CER`, `ANU`). Sub-recursos: notas, diagnósticos, fórmulas, antecedentes, escalas, consentimientos.
FHIR	`tecsas3 fhir export-fhir-bundle`	Bundle FHIR R5 completo por paciente. Complementa con `fhir paciente-list`, `fhir agente-list`, `fhir eapb-list`.
IA	`tecsas3 ia chat-create`	Crea chats IA v1 o v2; envío de mensajes con `ia v2-chat-mensaje`; exports a Markdown, PDF, Word, email y FHIR.
Reportes	`tecsas3 reportes execute`	Lanza una ejecución inmediata de un reporte programado por su `id` (entero).
Pipeline	`tecsas3 pipe run pipeline.yml`	Ejecuta pasos declarativos en YAML o JSON con placeholders `${step.path}` y `${env.VAR}`, soporte de `continue_on_error`.
Batch	`tecsas3 batch run archivo.json`	Ejecuta operaciones `paciente.`, `examen.`, `agente.*` desde JSON array, JSONL u objeto `{operations:[…]}`.
Agente (mapa)	`tecsas3 agente heatmap`	Agrega ubicaciones GPS en celdas de lat/lon. Excluye (0,0) con `--exclude-invalid`. Alternativa: `agente ubicacion`.
Dashboard	`tecsas3 dashboard resumen`	Resumen del plan y tenant activos: pacientes, familias, agentes, semáforo de riesgo.

Más operaciones

Comando	Propósito	Ejemplo
`tecsas3 auth login`	Obtiene y guarda token (DRF o JWT) en keyring.	`tecsas3 auth login --user juan --password … --scheme jwt`
`tecsas3 auth whoami`	Muestra usuario y contexto activo.	`tecsas3 auth whoami --json --no-input`
`tecsas3 auth logout`	Borra tokens locales (no revoca server-side).	`tecsas3 auth logout`
`tecsas3 config show`	Muestra la configuración efectiva (sin secretos).	`tecsas3 config show --json --no-input`
`tecsas3 config set`	Setea `tenant`, `plan_id`, `tenant_org`, `timeout`, etc.	`tecsas3 config set tenant demo`
`tecsas3 install-skill install`	Instala skill para un agente específico.	`tecsas3 install-skill install --agent claude-code`
`tecsas3 install-skill all`	Instala skill en todos los agentes disponibles.	`tecsas3 install-skill --all`
`tecsas3 install-skill list`	Lista agentes soportados y rutas candidatas.	`tecsas3 install-skill --list`
`tecsas3 util schema`	Exporta el OpenAPI del backend a stdout o archivo.	`tecsas3 util schema --format yaml --out api.yaml`
`tecsas3 util security-check`	Verifica permisos `0700`/`0600` en config y credenciales.	`tecsas3 util security-check --json --no-input`
`tecsas3 util ping`	Chequea el endpoint `/health/` del backend.	`tecsas3 util ping --json --no-input`
`tecsas3 --version`	Imprime versión del CLI (`0.4.1`).	`tecsas3 --version`

Preguntas frecuentes

¿Cómo obtengo un token de acceso?

El CLI no usa API keys tradicionales: usa un token DRF (legacy) o JWT (SimpleJWT) que se obtiene con tecsas3 auth login --user <USER> --password <PASSWORD> --scheme jwt. Si ya tienes un token emitido por el backend, exporta la variable TECSAS3_TOKEN=<token> y el CLI lo usará directamente, sin pasar por el login. El token se guarda después en keyring del sistema o, como fallback, en ~/.tecsas3/credentials con permisos 0600.

Tres causas habituales, en orden de probabilidad:

El backend rechazó las credenciales — verifica con tecsas3 auth whoami y, si falla, repite tecsas3 auth login.
Estás usando --scheme token (DRF legacy) cuando el servidor solo emite JWT, o viceversa — prueba --scheme jwt (o --scheme token según el endpoint disponible).
La hora del equipo está desincronizada (NTP) y el JWT se considera expirado — sincroniza el reloj del sistema. Para inspección detallada, ejecuta con --debug para ver la traza HTTP.

¿Cómo cambio de tenant?

Tres niveles, de mayor a menor persistencia:

Global: tecsas3 config set tenant <slug> (se persiste en ~/.tecsas3/config.toml).
Por invocación: tecsas3 --tenant <slug> paciente list o variable TECSAS3_TENANT.
Multi-perfil: tecsas3 --profile prod auth login … y luego --profile prod en cada llamada para aislar entornos.

Para rutas protegidas (/api/, /paciente/, /hce/api/, /eps_fhir/, /lab/api/, /agente/api/, /ia/, /facturacion/api/, /rips/api/, /billing/api/, /gestion/api/, /familia/) el CLI inyecta automáticamente los headers X-Tenant-Slug, X-Tenant-Org-ID y X-Plan-ID. Si no se resuelve el tenant, el backend responde 403 tenant_context_required.

¿Los logs contienen PHI (información de salud protegida)?

Por defecto, el cliente HTTP aplica redacción PHI (redact_blob) antes de escribir a stderr. El flag --debug muestra método, URL, status y cuerpo (redactado) hasta 500 caracteres por línea. Para inspección profunda, usa --debug solo en entornos de desarrollo y nunca dirijas su salida a logs persistentes sin un sink que también redacte.

¿Funciona detrás de un proxy corporativo?

Sí. El cliente usa httpx y respeta las variables estándar HTTPS_PROXY, HTTP_PROXY, NO_PROXY y SSL_CERT_FILE/SSL_CERT_DIR. Para certificados corporativos autofirmados en redes controladas, desactiva la verificación TLS con tecsas3 config set verify_tls false. La conexión sigue siendo HTTPS: el CLI rechaza http:// salvo para localhost. Si tu proxy requiere autenticación NTLM o Kerberos, expórtala en HTTPS_PROXY como http://user:pass@proxy.corp:8080.

¿Cómo actualizo a la última versión?

Reinstala el wheel con pip:

pip install --upgrade tecsas3-cli

Verifica con tecsas3 --version. La versión se incluye en el header User-Agent de cada request (tecsas3-cli/0.4.1) para que el backend pueda correlacionar trazas por versión. Si usas uv o pipx, el comando equivalente es uv tool upgrade tecsas3-cli o pipx upgrade tecsas3-cli. El changelog vive en cli/CHANGELOG.md del repositorio.

Empezar

Conceptos

Guías

Soporte

TecsaS3 CLI

TecsaS3 CLI

Instalar y configurar el CLI

Usar el CLI

Dashboard del CLI

Resumen de capacidades

Preguntas frecuentes

​TecsaS3 CLI

​Instalar y configurar el CLI

​Usar el CLI

​Dashboard del CLI

​Resumen de capacidades

​Preguntas frecuentes

TecsaS3 CLI

Instalar y configurar el CLI

Usar el CLI

Dashboard del CLI

Resumen de capacidades

Preguntas frecuentes