Manual de Uso — Sherlock CLI¶

Comando: sherlock Entry point: sherlock_docs.interfaces.cli:main (registrado en pyproject.toml) Requisito: pip install -e . desde el directorio raíz del proyecto

Instalación¶

# Desde el directorio raíz del proyecto
pip install -e .

# Verificar instalación
sherlock --help

Si se usa un virtualenv, asegurarse de tenerlo activado.

Opciones Globales¶

sherlock [--db RUTA] <subcomando> [opciones]

Opción	Descripción	Default
`--db RUTA`	Ruta a la base de datos SQLite	`data/database/sherlock.db`

Subcomandos¶

`list` — Listar documentos¶

sherlock list [--limit N] [--status ESTADO] [--source imported] [--from FECHA] [--to FECHA]

Opción	Descripción	Default
`--limit N`	Máximo de resultados	20
`--status`	Filtrar por estado: `pending`, `processing`, `processed`, `validated`, `error`	todos
`--source imported`	Solo documentos importados desde Excel	todos
`--from FECHA`	Fecha inicio (YYYY-MM-DD), requiere `--to`	—
`--to FECHA`	Fecha fin (YYYY-MM-DD), requiere `--from`	—

Ejemplos:

# Últimos 10 documentos
sherlock list --limit 10

# Solo importados
sherlock list --source imported --limit 50

# Solo validados
sherlock list --status validated

# Rango de fechas (usa created_at = fecha de reparto para importados)
sherlock list --from 2022-07-01 --to 2022-08-01

Output:

ID                                     | RADICADO             | ACCIONANTE                | ESTADO       | CREADO
-----------------------------------------------------------------------------------------------------------------------------
e91032d9-ddc8-42f4-8271-5f733b6a526c   | 05088400300320220... | JULIO CÉSAR LEDESMA RE... | validated    | 2022-07-28 00:00
33210d12-b780-469e-8773-53b986e62c0c   | 05088400300320220... | JULIO CESAR AVENDAÑO P... | validated    | 2022-07-26 00:00

Total: 2 documento(s)

La columna CREADO muestra la fecha de reparto para documentos importados (no la fecha de importación).

`get` — Ver detalle de un documento¶

sherlock get <id>
sherlock get --radicado <radicado>
sherlock get --cedula <cedula>

Argumento	Descripción
`<id>`	UUID del documento
`--radicado`	Buscar por radicado exacto
`--cedula`	Buscar por cédula (si hay varios, muestra tabla)

Ejemplos:

# Por ID
sherlock get e91032d9-ddc8-42f4-8271-5f733b6a526c

# Por radicado
sherlock get --radicado 05088400300320220069600

# Por cédula
sherlock get --cedula 71762368

Output:

  ID                     : e91032d9-ddc8-42f4-8271-5f733b6a526c
  Archivo                : import_05088400300320220069600.xlsx
  Ruta                   : [imported]
  Tipo                   : tutela
  Estado                 : validated
  Confianza OCR          : 0.00
  ...
  Accionante             : JULIO CÉSAR LEDESMA RENDÓN
  Accionado              : Administración del proyecto Tierra Linda...
  Radicado               : 05088400300320220069600
  Juzgado                : JUZGADO 1 CIVIL CIRCUITO BELLO
  Fecha documento        : 2022-07-28
  Cédula                 : 71762368
  Correo                 : juliozh@hotmail.com
  ...
  Creado                 : 2022-07-28 00:00:00
  Importado              : 2026-03-04 15:48:37
  Actualizado            : 2026-03-04 15:48:37

Nota sobre fechas en documentos importados: - Creado = fecha de reparto del Excel (columna FECHA/HORA), que es la fecha operativamente relevante - Importado = fecha/hora en que se ejecutó la importación (solo aparece en documentos importados) - Para documentos procesados por OCR/NER, "Creado" es la fecha de procesamiento e "Importado" muestra "(no)"

`search` — Búsqueda full-text (FTS5)¶

sherlock search <texto> [--limit N]

Opción	Descripción	Default
`<texto>`	Texto a buscar (nombre, radicado, contenido, etc.)	—
`--limit N`	Máximo de resultados	10

Ejemplos:

# Buscar por nombre
sherlock search "LEDESMA"

# Buscar por contenido
sherlock search "tutela" --limit 5

# Buscar por radicado parcial
sherlock search "050884003"

La búsqueda usa FTS5 de SQLite, que indexa: radicado, demandante, demandado, juzgado, observaciones, contenido OCR, cédula, correo y etiquetas.

`delete` — Eliminar un documento¶

sherlock delete <id> [--force]
sherlock delete --radicado <radicado> [--force]

Opción	Descripción
`<id>`	UUID del documento
`--radicado`	Buscar por radicado
`--force`	Eliminar sin pedir confirmación

Ejemplos:

# Con confirmación interactiva
sherlock delete e91032d9-ddc8-42f4-8271-5f733b6a526c

# Sin confirmación
sherlock delete e91032d9-ddc8-42f4-8271-5f733b6a526c --force

# Por radicado
sherlock delete --radicado 05088400300320220069600 --force

Sin --force, el CLI muestra los datos del documento y pide confirmación:

Documento: e91032d9-ddc8-42f4-8271-5f733b6a526c
  Radicado: 05088400300320220069600
  Accionante: JULIO CÉSAR LEDESMA RENDÓN
¿Eliminar este documento? [s/N]:

`delete-batch` — Eliminación masiva¶

sherlock delete-batch [--source imported] [--radicado-prefix PREFIJO] [--force]

Opción	Descripción
`--source imported`	Solo documentos importados desde Excel
`--radicado-prefix`	Solo documentos cuyo radicado empiece con el prefijo
`--force`	Eliminar sin pedir confirmación

Ejemplos:

# Eliminar TODOS los importados (con confirmación)
sherlock delete-batch --source imported

# Eliminar importados con prefijo IMPORT- sin confirmación
sherlock delete-batch --source imported --radicado-prefix IMPORT- --force

# Eliminar todos los que empiecen con "050884003"
sherlock delete-batch --radicado-prefix 050884003 --force

Sin --force, muestra los primeros 10 documentos y pide confirmación antes de proceder.

`update` — Actualizar un campo¶

sherlock update <id> <campo> <valor>

Argumento	Descripción
`<id>`	UUID del documento
`<campo>`	Nombre del campo a actualizar
`<valor>`	Nuevo valor

Campos válidos:

Campo	Descripción
`demandante`	Nombre del accionante
`demandado`	Nombre del accionado
`radicado`	Número de radicado
`juzgado`	Juzgado de reparto
`fecha_documento`	Fecha del documento
`numero_acta`	Número de acta
`observaciones`	Texto libre
`etiquetas`	JSON array de etiquetas
`direccion_demandante`	Dirección del accionante
`direccion_demandado`	Dirección del accionado
`correo`	Email del accionante
`cedula`	CC/CE/NIT del accionante

Ejemplos:

# Corregir nombre del accionante
sherlock update e91032d9-ddc8-42f4-8271-5f733b6a526c demandante "JULIO CÉSAR LEDESMA RENDÓN"

# Actualizar juzgado
sherlock update e91032d9-ddc8-42f4-8271-5f733b6a526c juzgado "JUZGADO 3 CIVIL MUNICIPAL BELLO"

# Agregar observaciones
sherlock update e91032d9-ddc8-42f4-8271-5f733b6a526c observaciones "Revisado por operador"

`import` — Importar desde Excel¶

sherlock import <archivo.xlsx> [--update-existing] [--skip-empty-radicado]

Opción	Descripción	Default
`<archivo.xlsx>`	Ruta al archivo Excel (formato CSJ)	—
`--update-existing`	Actualizar documentos existentes si el radicado ya existe	No
`--skip-empty-radicado`	Omitir filas sin radicado	Sí

El archivo Excel debe tener las columnas del formato CSJ: CORREO, CEDULA, ACCIONANTE, ACCIONADO, RADICADO, FECHA/HORA, SECUENCIA, SECUENCIAANTERIOR, JUZGADO, OBSERVACIONES, COORDENADA

Manejo de fechas al importar: - La columna FECHA/HORA se usa como created_at del documento (fecha de reparto) - Esto permite que la GUI, filtros por rango y ordenamiento usen la fecha real del proceso judicial - Se registra además imported_at con la fecha/hora de importación (auditoría) - Formatos de fecha soportados: YYYY-MM-DD, DD/MM/YYYY, DD-MM-YYYY, YYYY/MM/DD - Si la fecha es inválida o vacía, se usa la fecha actual como fallback

Sanitización automática: - CEDULA: se eliminan puntos, espacios y caracteres no numéricos (ej: 1.234.567 → 1234567) - Fechas inválidas se descartan con un warning en los logs

Ejemplos:

# Importar (solo crea nuevos, omite existentes)
sherlock import datos/indice_2026.xlsx

# Importar actualizando existentes
sherlock import datos/indice_2026.xlsx --update-existing

Output:

Importación completada:
  Total filas:  391
  Creados:      385
  Actualizados: 0
  Omitidos:     4
  Errores:      2

Detalle de errores:
  Fila 156: Radicado vacío
  Fila 290: Error al procesar fecha

`export` — Exportar a Excel¶

sherlock export <archivo.xlsx> [--from FECHA] [--to FECHA]

Opción	Descripción	Default
`<archivo.xlsx>`	Ruta de salida	—
`--from FECHA`	Fecha inicio (YYYY-MM-DD)	sin filtro
`--to FECHA`	Fecha fin (YYYY-MM-DD)	sin filtro

Ejemplos:

# Exportar todos los documentos
sherlock export salida.xlsx

# Exportar por rango de fechas
sherlock export marzo_2026.xlsx --from 2026-03-01 --to 2026-03-31

Output:

Exportación completada:
  Registros: 423
  Archivo:   salida.xlsx

El Excel generado sigue el formato oficial del Consejo Superior de la Judicatura (CSJ).

`stats` — Estadísticas¶

sherlock stats

Sin argumentos. Muestra resumen del repositorio.

Output:

Estadísticas Sherlock-docs
========================================
  Total documentos: 423

  Por estado:
    processed   : 32
    validated   : 391

  Por origen:
    procesados  : 32
    importados  : 391

  Tiempos promedio (ms):
    avg_ocr_ms  : 14523
    avg_ner_ms  : 1742
    avg_dedup_ms: 39
    avg_total_ms: 16425
    total_documents: 32

`count` — Contar documentos¶

sherlock count

Imprime solo el número total de documentos (útil para scripts):

`find` — Buscar por correo o accionante¶

sherlock find --email <correo>
sherlock find --plaintiff <nombre>

Opción	Descripción
`--email`	Buscar por correo electrónico (coincidencia exacta, case-insensitive)
`--plaintiff`	Buscar por nombre de accionante (coincidencia parcial, case-insensitive)

Las opciones son mutuamente excluyentes (se debe usar una u otra).

Ejemplos:

# Buscar por correo
sherlock find --email juliozh@hotmail.com

# Buscar por nombre parcial del accionante
sherlock find --plaintiff "LEDESMA"

Output:

Documentos con accionante 'LEDESMA':

ID                                     | RADICADO             | ACCIONANTE                | ESTADO       | CREADO
-----------------------------------------------------------------------------------------------------------------------------
e91032d9-ddc8-42f4-8271-5f733b6a526c   | 05088400300320220... | JULIO CÉSAR LEDESMA RE... | validated    | 2022-07-28 00:00

Total: 1 documento(s)

Futuro endpoint API: GET /api/documents?email=x / GET /api/documents?plaintiff=x

`corrections` — Ver correcciones de un documento¶

sherlock corrections <doc_id>

Argumento	Descripción
`<doc_id>`	UUID del documento

Muestra todas las correcciones realizadas por operadores sobre las entidades extraídas por NER.

Ejemplo:

sherlock corrections e91032d9-ddc8-42f4-8271-5f733b6a526c

Output:

Correcciones para documento e91032d9-ddc8-42f4-8271-5f733b6a526c:

CAMPO                | ORIGINAL                       | CORREGIDO                      | FECHA
------------------------------------------------------------------------------------------------------------
demandante           | JULIO CESAR LEDESMA            | JULIO CÉSAR LEDESMA RENDÓN     | 2026-03-03 14:22
juzgado              | (vacío)                        | JUZGADO 1 CIVIL CIRCUITO BELLO | 2026-03-03 14:23

Total: 2 corrección(es)

Futuro endpoint API: GET /api/documents/{id}/corrections

`correction-stats` — Estadísticas de correcciones NER¶

sherlock correction-stats

Sin argumentos. Muestra cuántas correcciones se han hecho por campo y la precisión estimada de NER.

Output:

Estadísticas de Correcciones
========================================
  Total correcciones: 136

  Por campo:
    tipo_documento      : 25
    correo              : 20
    demandado           : 20
    juzgado             : 18
    numero_acta         : 18
    radicado            : 18
    demandante          : 7
    cedula              : 6

  Precisión estimada por campo:
    demandado           : 37.5%
    demandante          : 78.1%
    juzgado             : 43.8%
    radicado            : 43.8%

La precisión se calcula como 1 - (correcciones / total_documentos) por campo. Valores bajos indican que NER necesita mejora en ese campo.

Futuro endpoint API: GET /api/stats/corrections

`stats-daily` — Estadísticas diarias de procesamiento¶

sherlock stats-daily [--days N]

Opción	Descripción	Default
`--days N`	Número de días a incluir	7

Ejemplo:

sherlock stats-daily --days 3

Output:

Estadísticas diarias (últimos 3 días)
============================================================

  Hoy (2026-03-04):
    Documentos procesados: 5
    Tiempo promedio:       8234 ms

  FECHA        | DOCS   | OCR (ms)   | NER (ms)   | TOTAL (ms)
  ----------------------------------------------------------
  2026-03-04   | 5      | 6120       | 1534       | 8234
  2026-03-03   | 14     | 7458       | 1938       | 9573
  2026-03-02   | 6      | 11810      | 965        | 12926

Futuro endpoint API: GET /api/stats/daily?days=7

`metrics` — Métricas de procesamiento de un documento¶

sherlock metrics <doc_id>

Argumento	Descripción
`<doc_id>`	UUID del documento

Muestra los tiempos de cada etapa del pipeline para un documento específico.

Ejemplo:

sherlock metrics e91032d9-ddc8-42f4-8271-5f733b6a526c

Output:

Métricas de procesamiento — e91032d9-ddc8-42f4-8271-5f733b6a526c

  Motor OCR           : tesseract
  OCR (ms)            : 14523
  NER (ms)            : 1742
  Dedup (ms)          : 39
  Total (ms)          : 16425
  Páginas             : 8
  Tamaño (bytes)      : 1245678

Futuro endpoint API: GET /api/documents/{id}/metrics

`update-status` — Actualizar estado de un documento¶

sherlock update-status <id> <estado>

Argumento	Descripción
`<id>`	UUID del documento
`<estado>`	Nuevo estado

Estados válidos:

Estado	Descripción
`pending`	Pendiente de procesamiento
`processing`	En procesamiento
`processed`	Procesado (OCR + NER completados)
`validated`	Validado por operador
`error`	Error en procesamiento

Ejemplo:

sherlock update-status e91032d9-ddc8-42f4-8271-5f733b6a526c validated

Output:

Estado actualizado a 'validated' para documento e91032d9-ddc8-42f4-8271-5f733b6a526c.

Futuro endpoint API: PATCH /api/documents/{id}/status

`health` — Verificar estado de servicios¶

sherlock health

Sin argumentos. Verifica que los servicios principales estén disponibles.

Output:

Estado de servicios Sherlock-docs

  BD (SQLite)  : OK (423 documentos)
  OCR          : OK
  NER (SpaCy)  : OK

Si un servicio no está disponible:

Estado de servicios Sherlock-docs

  BD (SQLite)  : OK (423 documentos)
  OCR          : NO DISPONIBLE
  NER (SpaCy)  : ERROR (es_core_news_lg model not found)

Nota: Este comando carga los modelos OCR y NER (puede tardar unos segundos la primera vez).

Futuro endpoint API: GET /api/health

`extract-acta` — Extraer datos de acta de reparto¶

sherlock extract-acta <archivo.pdf>

Argumento	Descripción
`<archivo.pdf>`	Ruta al PDF del acta de reparto (formato TYBA)

Extrae campos estructurados del acta de reparto sin necesidad de pasar por el pipeline completo.

Ejemplo:

sherlock extract-acta acta_reparto_2026.pdf

Output:

Datos extraídos del acta de reparto:

  Radicado            : 05088400300320260012300
  Juzgado             : JUZGADO 3 CIVIL MUNICIPAL BELLO
  Número acta         : 0001234
  Clase proceso       : TUTELA
  Demandante          : JUAN PÉREZ GÓMEZ
  Cédula demandante   : 71762368
  Demandado           : EPS SURA
  Fecha reparto       : 2026-03-04 08:30:00

Si no se pueden extraer campos obligatorios:

No se pudieron extraer datos del acta.
  Texto extraído (1234 chars), pero sin campos obligatorios.

Futuro endpoint API: POST /api/extract/acta

`process` — Procesar documento PDF¶

sherlock process <archivo.pdf> [--type TIPO] [--verbose]

Opción	Descripción	Default
`<archivo.pdf>`	Ruta al archivo PDF	—
`--type`	Tipo de documento: `tutela`, `habeas_corpus`, `otro`	`tutela`
`--verbose`, `-v`	Mostrar log del pipeline en tiempo real	No

Ejecuta el pipeline completo: OCR → NER → Detección de duplicados → Guardado en BD.

Ejemplo:

# Procesamiento estándar
sherlock process documento.pdf

# Con tipo específico y log detallado
sherlock process tutela_urgente.pdf --type tutela --verbose

Output:

Procesando: documento.pdf (tipo: tutela)
--------------------------------------------------

  ID:             a1b2c3d4-e5f6-7890-abcd-ef1234567890
  Motor OCR:      tesseract
  Confianza OCR:  0.87
  Tiempo total:   16425 ms

  Entidades extraídas:
    Accionante      : JUAN PÉREZ GÓMEZ
    Accionado       : EPS SURA
    Radicado        : 05088400300320260012300
    Juzgado         : JUZGADO 3 CIVIL MUNICIPAL BELLO
    Fecha           : 2026-03-04
    Cédula          : 71762368
    Correo          : juan@email.com

  Medida provisional detectada: urgente, inmediato

  Candidatos duplicados: 1
    - e91032d9-ddc8-42f4-8271-5f733b6a526c (score: 0.82, high)

Si el documento es un duplicado exacto (gate pre-OCR):

Procesando: documento.pdf (tipo: tutela)
--------------------------------------------------

  DUPLICADO de: e91032d9-ddc8-42f4-8271-5f733b6a526c
  Acción recomendada: block

Con --verbose, se muestran los logs del pipeline:

  [INFO] Iniciando procesamiento: documento.pdf
  [INFO] OCR completado: 8 páginas, confianza=0.87, tiempo=14523ms
  [INFO] NER completado: 7 entidades extraídas
  [INFO] Dedup: 1 candidato encontrado (score=0.82)

Futuro endpoint API: POST /api/documents/process

`audit-report` — Reporte de auditoría (GOB-11)¶

sherlock audit-report [--action ACCION] [--user USUARIO] [--from FECHA] [--to FECHA] [--limit N] [--format text|csv] [--summary]

Opción	Descripción	Default
`--action`	Filtrar por tipo de acción (ver tabla abajo)	todas
`--user`	Filtrar por nombre de usuario	todos
`--from FECHA`	Fecha inicio (YYYY-MM-DD)	sin filtro
`--to FECHA`	Fecha fin (YYYY-MM-DD)	sin filtro
`--limit N`	Máximo de eventos	100
`--format`	Formato de salida: `text` (tabla) o `csv`	`text`
`--summary`	Mostrar resumen estadístico en lugar de lista	No

Acciones auditables:

Acción	Descripción
`document_processed`	Documento procesado (OCR + NER)
`document_corrected`	Entidades corregidas por operador
`document_validated`	Documento validado
`document_deleted`	Documento eliminado
`document_viewed`	Documento consultado
`document_searched`	Búsqueda ejecutada
`documents_exported`	Exportación a Excel
`documents_imported`	Importación desde Excel
`duplicate_detected`	Duplicado detectado
`login`	Inicio de sesión
`logout`	Cierre de sesión

Ejemplos:

# Últimos 100 eventos (por defecto)
sherlock audit-report

# Filtrar por acción
sherlock audit-report --action document_processed --limit 50

# Filtrar por usuario y rango de fechas
sherlock audit-report --user operador1 --from 2026-03-01 --to 2026-03-06

# Exportar a CSV
sherlock audit-report --format csv > auditoria_marzo.csv

# Exportar filtrado a CSV
sherlock audit-report --action document_corrected --from 2026-03-01 --format csv > correcciones.csv

# Resumen estadístico
sherlock audit-report --summary

Output (texto):

FECHA                  | USUARIO         | ACCIÓN                    | RECURSO    | ID RECURSO
------------------------------------------------------------------------------------------------------------------------
2026-03-06T09:00:00    | operador1       | documents_exported        | export     |
2026-03-05T11:00:00    | operador2       | document_corrected        | document   | a1b2c3d4-e5f6-7890-abcd-ef1234567890
2026-03-05T10:00:00    | operador1       | document_processed        | document   | a1b2c3d4-e5f6-7890-abcd-ef1234567890

Total: 3 evento(s)

Output (CSV):

timestamp,user_id,action,resource_type,resource_id,details
2026-03-06T09:00:00,operador1,documents_exported,export,,
2026-03-05T11:00:00,operador2,document_corrected,document,a1b2c3d4,...,"{""fields"":[""demandante""]}"
2026-03-05T10:00:00,operador1,document_processed,document,a1b2c3d4,...,

Output (resumen):

Resumen de auditoría

  Total eventos: 150

  Por acción:
    document_processed       : 85
    document_corrected       : 42
    documents_exported       : 12
    documents_imported       : 8
    document_validated       : 3

  Por usuario:
    operador1                : 95
    operador2                : 45
    system                   : 10

Futuro endpoint API: GET /api/audit?action=x&user=y&from=z&to=w

Flujos de Trabajo Comunes¶

Limpiar una importación fallida¶

# Ver qué se importó
sherlock list --source imported --limit 5

# Eliminar todo lo importado
sherlock delete-batch --source imported --force

# Re-importar con correcciones
sherlock import indice_corregido.xlsx

Verificar un documento específico¶

# Buscar por cédula
sherlock get --cedula 71762368

# O buscar por nombre
sherlock search "LEDESMA" --limit 5

# Ver detalle completo
sherlock get e91032d9-ddc8-42f4-8271-5f733b6a526c

Corregir datos de un documento¶

# Ver estado actual
sherlock get e91032d9-ddc8-42f4-8271-5f733b6a526c

# Corregir campo
sherlock update e91032d9-ddc8-42f4-8271-5f733b6a526c demandante "NOMBRE CORRECTO"

# Verificar corrección
sherlock get e91032d9-ddc8-42f4-8271-5f733b6a526c

# Ver historial de correcciones
sherlock corrections e91032d9-ddc8-42f4-8271-5f733b6a526c

Procesar un documento nuevo desde terminal¶

# Procesar con tipo por defecto (tutela)
sherlock process tutela_nueva.pdf

# Procesar con log detallado
sherlock process tutela_nueva.pdf --verbose

# Verificar resultado
sherlock get --radicado 05088400300320260012300

Extraer datos de acta de reparto¶

# Extraer campos del acta
sherlock extract-acta acta_reparto.pdf

# Si los datos son correctos, procesar el documento asociado
sherlock process documento_asociado.pdf

Monitorear precisión de NER¶

# Ver estadísticas de correcciones
sherlock correction-stats

# Ver correcciones de un documento específico
sherlock corrections <doc_id>

# Campos con baja precisión necesitan más patrones o training data

Verificar salud del sistema¶

# Comprobar que todos los servicios estén disponibles
sherlock health

# Ver actividad de los últimos 7 días
sherlock stats-daily

# Métricas detalladas de un documento
sherlock metrics <doc_id>

Buscar documentos de un accionante recurrente¶

# Por correo
sherlock find --email juliozh@hotmail.com

# Por nombre (búsqueda parcial)
sherlock find --plaintiff "LEDESMA"

# Por cédula (búsqueda exacta)
sherlock get --cedula 71762368

Exportar para reporte¶

# Exportar documentos de la última semana
sherlock export reporte_semanal.xlsx --from 2026-02-25 --to 2026-03-04

# Verificar estadísticas generales
sherlock stats

Auditar actividad del sistema¶

# Ver resumen de actividad
sherlock audit-report --summary

# Actividad del último día
sherlock audit-report --from 2026-03-06 --to 2026-03-06

# Correcciones de un operador específico
sherlock audit-report --action document_corrected --user operador1

# Generar reporte CSV para comité de gobernanza
sherlock audit-report --from 2026-03-01 --to 2026-03-31 --format csv > auditoria_marzo.csv

Usar con otra base de datos¶

# Apuntar a BD de producción (backup)
sherlock --db /ruta/backup/sherlock.db stats

# Listar desde BD de pruebas
sherlock --db data/database/sherlock_test.db list

Códigos de Salida¶

Código	Significado
`0`	Éxito
`1`	Error (documento no encontrado, campo inválido, etc.)
`130`	Interrumpido por el usuario (Ctrl+C)

Referencia Rápida — 21 Comandos¶

Comando	Descripción
`list`	Listar documentos con filtros
`get`	Ver detalle de un documento
`search`	Búsqueda full-text FTS5
`find`	Buscar por correo o accionante
`delete`	Eliminar un documento
`delete-batch`	Eliminación masiva
`update`	Actualizar un campo
`update-status`	Cambiar estado de un documento
`import`	Importar desde Excel
`export`	Exportar a Excel
`process`	Procesar PDF (OCR + NER + duplicados)
`extract-acta`	Extraer datos de acta de reparto
`audit-report`	Reporte de auditoría (GOB-11)
`corrections`	Ver correcciones de un documento
`correction-stats`	Estadísticas de correcciones NER
`stats`	Estadísticas generales
`stats-daily`	Estadísticas diarias de procesamiento
`metrics`	Métricas de procesamiento por documento
`count`	Contar total de documentos
`health`	Verificar estado de servicios

Mapeo CLI → Futuro API¶

CLI	Endpoint API futuro
`sherlock process <pdf>`	`POST /api/documents/process`
`sherlock find --email`	`GET /api/documents?email=x`
`sherlock find --plaintiff`	`GET /api/documents?plaintiff=x`
`sherlock corrections <id>`	`GET /api/documents/{id}/corrections`
`sherlock correction-stats`	`GET /api/stats/corrections`
`sherlock stats-daily`	`GET /api/stats/daily?days=7`
`sherlock metrics <id>`	`GET /api/documents/{id}/metrics`
`sherlock update-status <id>`	`PATCH /api/documents/{id}/status`
`sherlock health`	`GET /api/health`
`sherlock extract-acta <pdf>`	`POST /api/extract/acta`
`sherlock audit-report`	`GET /api/audit`

Notas Técnicas¶

Sin dependencias nuevas: usa argparse (stdlib). openpyxl solo se requiere para import/export (ya instalado).
Reutiliza infraestructura existente: ServiceContainer, SQLiteDocumentRepository, ImportExcelUseCase, ExportExcelUseCase, ProcessDocumentUseCase, acta_reparto_extractor.
Logging silenciado: el CLI suprime los logs del proyecto para mantener output limpio. Los logs siguen escribiéndose al archivo logs/sherlock_YYYY-MM-DD.log. El comando process acepta --verbose para habilitar logs en consola.
Confirmación interactiva: delete y delete-batch piden confirmación a menos que se use --force.
Fechas en importados: created_at = fecha de reparto (del Excel), imported_at = cuándo se importó. Esto permite que --from/--to, la columna CREADO y la GUI muestren la fecha operativamente relevante.
Encoding: el output usa la codificación del terminal. En Windows, caracteres especiales (tildes, eñe) dependen del code page activo (chcp 65001 para UTF-8).
Health check: sherlock health carga los modelos OCR y NER, lo que puede tardar varios segundos la primera vez. Es el equivalente al futuro GET /api/health.

Manual de Uso — Sherlock CLI¶

Instalación¶

Opciones Globales¶

Subcomandos¶

list — Listar documentos¶

get — Ver detalle de un documento¶

search — Búsqueda full-text (FTS5)¶

delete — Eliminar un documento¶

delete-batch — Eliminación masiva¶

update — Actualizar un campo¶

import — Importar desde Excel¶

export — Exportar a Excel¶

stats — Estadísticas¶

count — Contar documentos¶

find — Buscar por correo o accionante¶

corrections — Ver correcciones de un documento¶

correction-stats — Estadísticas de correcciones NER¶

stats-daily — Estadísticas diarias de procesamiento¶

metrics — Métricas de procesamiento de un documento¶

update-status — Actualizar estado de un documento¶

health — Verificar estado de servicios¶

extract-acta — Extraer datos de acta de reparto¶

process — Procesar documento PDF¶

audit-report — Reporte de auditoría (GOB-11)¶

Flujos de Trabajo Comunes¶

Limpiar una importación fallida¶

Verificar un documento específico¶

Corregir datos de un documento¶

Procesar un documento nuevo desde terminal¶

Extraer datos de acta de reparto¶

Monitorear precisión de NER¶

Verificar salud del sistema¶

Buscar documentos de un accionante recurrente¶

Exportar para reporte¶

Auditar actividad del sistema¶

Usar con otra base de datos¶

Códigos de Salida¶

Referencia Rápida — 21 Comandos¶

Mapeo CLI → Futuro API¶

Notas Técnicas¶

`list` — Listar documentos¶

`get` — Ver detalle de un documento¶

`search` — Búsqueda full-text (FTS5)¶

`delete` — Eliminar un documento¶

`delete-batch` — Eliminación masiva¶

`update` — Actualizar un campo¶

`import` — Importar desde Excel¶

`export` — Exportar a Excel¶

`stats` — Estadísticas¶

`count` — Contar documentos¶

`find` — Buscar por correo o accionante¶

`corrections` — Ver correcciones de un documento¶

`correction-stats` — Estadísticas de correcciones NER¶

`stats-daily` — Estadísticas diarias de procesamiento¶

`metrics` — Métricas de procesamiento de un documento¶

`update-status` — Actualizar estado de un documento¶

`health` — Verificar estado de servicios¶

`extract-acta` — Extraer datos de acta de reparto¶

`process` — Procesar documento PDF¶

`audit-report` — Reporte de auditoría (GOB-11)¶