El CLI tecsas3-cli emite datos en cuatro formatos intercambiables. Cada uno apunta a un consumidor distinto: humanos en terminal, agentes de IA, depuración operativa y pipelines ETL. La selección por comando se hace con --format (o el atajo --json) y se puede fijar como default con TECSAS3_OUTPUT_FORMAT.
Todos los formatos pasan por el mismo emisor unificado (Output en cli/src/tecsas3_cli/output.py) y respetan la capa de redacción PHI cuando aplica a logs stderr.
Tabla comparativa
Flags relevantes
Ejemplos con un mismo comando
El siguiente bloque muestra el mismo comando (paciente list) emitiendo en cada uno de los cuatro formatos. Los datos son ilustrativos.
Para integrar el CLI con un agente de IA (claude-code, opencode, mcode, pi, hermes) o con un script bash, usa siempre --json --no-input. La combinación garantiza salida determinista, sin prompts, sin timestamps del cliente, y apta para jq o subprocess.check_output.
table — usa rich.Table con expand=False y show_lines=False. Cuando el resultado está vacío imprime Sin resultados. en gris. Las columnas se sugieren con un orden preferente (id_paciente, uuid, nombre, nivel_riesgo, creado, …) y caen a las primeras 5 claves si no hay coincidencia.json — se serializa con ensure_ascii=False y default=str (cualquier Decimal, UUID o datetime se convierte a string estable). No se emiten timestamps del cliente: cualquier created_at viene del backend. Los errores se emiten en {"error": {...}} para que el agente los parsee.yaml — usa ruamel.yaml.YAML(typ="safe") para máxima portabilidad. Recomendado para diffs en code review de pipelines declarativos.csv — volcado plano con csv.writer y columnas explícitas si se pasan vía API del recurso. Sin headers extras ni comillas inteligentes.
Cancelación de efectos colaterales
Los formatos json, yaml y csv suprimen los mensajes info para no contaminar el stream estructurado. Los success y error se redirigen a stderr con la forma adecuada en cada formato:
- En
json, un success se emite como {"status": "ok", "message": "..."} en stdout.
- En
table, un success se imprime como OK <msg> en verde.
- En todos los formatos, un
error va a stderr con código, mensaje, hint y request_id cuando aplica.
Variables de entorno
Buenas prácticas
- Para CI/CD:
TECSAS3_OUTPUT_FORMAT=json NO_COLOR=1 tecsas3 ... | jq ....
- Para pipes largos:
--json --no-input en cada comando encadenado; un solo jq final agrega y resume.
- Para depuración puntual:
--format yaml da legibilidad sin perder estructura.
- Para exportación masiva:
--format csv con > pacientes.csv y re-importar con pandas.read_csv o duckdb.read_csv.
Troubleshooting
Sin resultados. aparece con datos en jq
Si el endpoint devuelve { "count": 5, "results": [...] } pero el CLI imprime Sin resultados., casi siempre es porque el Output no detectó la clave results. El emisor unificado espera la forma { results: [...] } o una lista directa.
Colores rotos en tmux / SSH
JSON con caracteres escapados (\u00e1)
El emisor usa ensure_ascii=False, así que á, ñ, ü se emiten tal cual. Si una pipeline downstream no las soporta, convierte con jq -r o iconv:
CSV con encoding inconsistente
El writer usa el encoding por defecto de la locale. Si lo importas en Excel o pandas y ves caracteres rotos:
Output.success se mezcla con el payload JSON
success se imprime en stdout cuando el formato es json, lo que rompe parsers downstream. Si necesitas separar, redirige los success a stderr:
Tabla con columnas truncadas en terminal estrecha
rich recorta columnas a la derecha cuando el ancho se agota. Si necesitas ver todo:
Patrones avanzados
Streaming NDJSON para pipelines largos
Si el recurso soporta paginación y quieres evitar cargar todo en memoria, encadena varios comandos con jq:
Para verdadero streaming, usa el endpoint server-side con ?stream=1 si está disponible y consume con httpx o curl --no-buffer.
Normalización de timestamps
--json no emite timestamps del cliente, pero el backend sí. Si necesitas comparar tiempos entre llamadas, parsea con date -d o python -c "from datetime import datetime; ...".
Composición con xargs y parallel
Redirección segura para audit
Para logs de auditoría, redirige stdout a un archivo con permisos 0600 y stderr a otro:
Siguientes pasos
