CLI Reference

BCN Extractor incluye una CLI unificada en bcn_cli.py, organizada en grupos de comandos. Todos los subcomandos soportan --help.

python bcn_cli.py --help
python bcn_cli.py normas --help
python bcn_cli.py metadata --help
python bcn_cli.py instituciones --help

Flag global

--debug — Activar logs internos

python bcn_cli.py --debug normas sync 17

Muestra los logs internos del cliente HTTP (requests, caché, reintentos). Sin el flag, solo se muestran warnings relevantes (como normas con ID inválido).

---

normas — Gestión de normas

normas list — Listar normas de una institución

python bcn_cli.py normas list <id_institucion> [--limit N] [--verbose]

Lista las normas disponibles en la BCN para una institución específica. No descarga ni almacena nada, solo consulta el servicio web directamente.

Argumento	Tipo	Descripción
id_institucion	int	ID de la institución en la BCN
--limit, -n	int	Máximo de normas a mostrar
--output, -o	path	Guardar lista como JSON
--verbose, -v	flag	Mostrar fecha de publicación

python bcn_cli.py normas list 17 --limit 20
python bcn_cli.py normas list 17 --output normas.json

---

normas get — Descargar una norma específica

python bcn_cli.py normas get <id> [--md PATH] [--xml PATH] [--full]

Descarga una norma específica desde la BCN.

Argumento	Tipo	Descripción
id	int	ID de la norma
--md, -m	path	Guardar como Markdown en la ruta indicada
--xml, -x	path	Guardar XML original en la ruta indicada
--full, -f	flag	Descargar texto completo (sin flag solo descarga metadatos)

python bcn_cli.py normas get 206396 --md salida.md
python bcn_cli.py normas get 206396 --full --xml backup.xml

---

normas sync — Sincronizar normas a la base de datos

python bcn_cli.py normas sync <id_institucion> [--limit N] [--force]

Descarga las normas de una institución y las sincroniza en PostgreSQL. Detecta cambios via hash MD5 para evitar upserts innecesarios. Cada vez que una norma cambia, la versión anterior queda archivada automáticamente en normas_versiones.

Argumento	Tipo	Descripción
id_institucion	int	ID de la institución
--limit, -n	int	Máximo de normas a procesar
--force	flag	Forzar re-descarga aunque no haya cambios

# Sincronizar las primeras 10 normas
python bcn_cli.py normas sync 17 --limit 10

# Forzar re-descarga completa
python bcn_cli.py normas sync 17 --force

Tip

La primera vez que sincronizas una institución puede tomar varios minutos si tiene muchas normas. Usa --limit para empezar con un subset.

Note

Usa --force si necesitas repoblar la metadata de normas ya sincronizadas con una versión anterior del extractor. El flag re-procesa todas las normas independientemente de si el XML cambió.

---

normas search — Buscar normas por texto

python bcn_cli.py normas search "<query>" [--limit N]

Búsqueda full-text en español sobre los títulos y contenido de las normas almacenadas localmente.

Argumento	Tipo	Descripción
query	str	Texto a buscar
--limit, -n	int	Máximo de resultados (default: 20)

python bcn_cli.py normas search "medio ambiente"
python bcn_cli.py normas search "decreto supremo" --limit 5

---

normas metadata — Ver metadata de una norma

python bcn_cli.py normas metadata <id>

Muestra la metadata estructurada de una norma específica: materias, organismos y flags como derogado o es_tratado. La metadata se almacena en la tabla EAV normas_metadata y se pobla automáticamente durante el sync.

Argumento	Tipo	Descripción
id	int	ID de la norma

python bcn_cli.py normas metadata 206396

---

normas by-metadata — Buscar normas por clave de metadata

python bcn_cli.py normas by-metadata <clave> <valor> [--limit N] [--offset N]

Filtra normas por una clave y valor de metadata. Usa los índices de normas_metadata para búsquedas eficientes.

Argumento	Tipo	Descripción
clave	str	Clave de metadata (ej: materia, organismo)
valor	str	Valor a buscar (búsqueda parcial)
--limit, -n	int	Máximo de resultados (default: 20)
--offset	int	Desplazamiento para paginación (default: 0)

python bcn_cli.py normas by-metadata materia "medio ambiente"
python bcn_cli.py normas by-metadata organismo "ministerio de salud" --limit 10
python bcn_cli.py normas by-metadata materia "transporte" --limit 20 --offset 20

---

metadata — Gestión de metadata

metadata claves — Listar claves disponibles

python bcn_cli.py metadata claves

Lista todas las claves de metadata registradas en normas_metadata. Útil para saber qué valores puedes usar con normas by-metadata.

python bcn_cli.py metadata claves

---

metadata stats — Estadísticas de metadata

python bcn_cli.py metadata stats

Muestra el total de entradas en normas_metadata, cuántas normas tienen metadata registrada, y el desglose por clave.

python bcn_cli.py metadata stats

---

instituciones — Gestión de instituciones

instituciones list — Listar instituciones

python bcn_cli.py instituciones list [--search TEXTO] [--limit N]

Argumento	Tipo	Descripción
--search, -s	str	Filtrar por nombre
--limit, -n	int	Máximo de resultados

python bcn_cli.py instituciones list
python bcn_cli.py instituciones list --search "ministerio"

---

instituciones get — Ver detalle de una institución

python bcn_cli.py instituciones get <id>

python bcn_cli.py instituciones get 1041

---

instituciones load — Cargar desde CSV

python bcn_cli.py instituciones load <archivo.csv> [--mode update|append|replace]

Carga un CSV con instituciones en la base de datos. El repositorio incluye data/instituciones.csv con las 700+ instituciones de la BCN.

Argumento	Tipo	Descripción
csv_path	path	Ruta al archivo CSV
--mode, -m	str	Modo de carga: update (default), append, replace

python bcn_cli.py instituciones load data/instituciones.csv
python bcn_cli.py instituciones load data/instituciones.csv --mode replace

---

Comandos de sistema

init — Inicializar la base de datos

python bcn_cli.py init [--csv PATH]

Inicializa el esquema de la base de datos (incluyendo las tablas normas_metadata y normas_versiones) y carga instituciones desde el CSV incluido.

python bcn_cli.py init
python bcn_cli.py init --csv data/instituciones.csv

---

stats — Estadísticas del sistema

python bcn_cli.py stats [--errors]

Muestra un resumen del estado de la base de datos: normas por tipo y estado, instituciones, operaciones recientes y versiones archivadas.

Argumento	Tipo	Descripción
--errors, -e	flag	Incluir errores recientes en el output

python bcn_cli.py stats
python bcn_cli.py stats --errors

---

cache stats / cache clear — Gestionar caché

python bcn_cli.py cache stats
python bcn_cli.py cache clear [--force]

# Ver info del caché
python bcn_cli.py cache stats

# Limpiar (pide confirmación)
python bcn_cli.py cache clear

# Limpiar sin confirmación
python bcn_cli.py cache clear --force

---

nlp — Análisis NLP de normas

El grupo nlp ejecuta el pipeline de análisis sobre normas ya sincronizadas. Usa el XML en caché, por lo que no genera tráfico adicional a la BCN. Todos los resultados se almacenan en las tablas normas_referencias, normas_entidades y normas_obligaciones.

python bcn_cli.py nlp --help

---

nlp analizar — Analizar una norma

python bcn_cli.py nlp analizar <id> [--forzar] [--llm]

Extrae referencias normativas, entidades nombradas y obligaciones de una norma específica.

Argumento	Tipo	Descripción
id	int	ID de la norma a analizar
--forzar, -f	flag	Re-analizar aunque ya exista análisis previo
--llm	flag	Usar Ollama/gemma4 para NER en lugar del modelo estadístico (experimental)

python bcn_cli.py nlp analizar 206396
python bcn_cli.py nlp analizar 206396 --forzar
python bcn_cli.py nlp analizar 206396 --llm

Caution

El flag --llm es experimental. Requiere Ollama instalado y el modelo gemma4 disponible. Las referencias normativas y las obligaciones siguen usando reglas en ambos modos.

---

nlp analizar-institucion — Analizar en batch

python bcn_cli.py nlp analizar-institucion <id_institucion> [--limit N] [--forzar] [--llm]

Analiza todas las normas sincronizadas de una institución. Las que ya tienen análisis se saltan automáticamente a menos que se use --forzar.

Argumento	Tipo	Descripción
id_institucion	int	ID de la institución
--limit, -n	int	Máximo de normas a procesar
--forzar, -f	flag	Re-analizar normas que ya tienen análisis
--llm	flag	Usar Ollama/gemma4 para NER en todo el batch (experimental)

python bcn_cli.py nlp analizar-institucion 17
python bcn_cli.py nlp analizar-institucion 17 --limit 50
python bcn_cli.py nlp analizar-institucion 17 --forzar

---

nlp resolver — Resolver referencias pendientes

python bcn_cli.py nlp resolver [id]

Intenta vincular referencias normativas marcadas como no resueltas (resolvida = false) contra las normas disponibles en la base de datos local. Las referencias que apuntan a normas de instituciones aún no sincronizadas quedan pendientes hasta que se sincronicen.

Argumento	Tipo	Descripción
id	int	(Opcional) ID de norma específica. Sin argumento, procesa todas las pendientes.

# Resolver todas las pendientes
python bcn_cli.py nlp resolver

# Resolver solo las de una norma
python bcn_cli.py nlp resolver 206396

---

nlp referencias — Ver referencias extraídas

python bcn_cli.py nlp referencias <id> [--resueltas]

Muestra las referencias normativas salientes de una norma: qué otras leyes o decretos cita, con tipo, número, año, organismo y si la norma referenciada existe en la DB local.

Argumento	Tipo	Descripción
id	int	ID de la norma
--resueltas, -r	flag	Mostrar solo las referencias resueltas contra la DB

python bcn_cli.py nlp referencias 206396
python bcn_cli.py nlp referencias 206396 --resueltas

---

nlp entidades — Ver entidades nombradas

python bcn_cli.py nlp entidades <id> [--tipo TIPO]

Lista las entidades nombradas detectadas por el modelo NER, agrupadas y deduplicadas por (texto, tipo). Ordenadas por frecuencia de mención.

Argumento	Tipo	Descripción
id	int	ID de la norma
--tipo, -t	str	Filtrar por tipo: organismo, persona, lugar, fecha

python bcn_cli.py nlp entidades 206396
python bcn_cli.py nlp entidades 206396 --tipo organismo
python bcn_cli.py nlp entidades 206396 --tipo persona

---

nlp obligaciones — Ver obligaciones y plazos

python bcn_cli.py nlp obligaciones <id> [--con-plazo]

Muestra las oraciones con verbos de obligación o permisión detectadas en la norma (deberá, podrá, se prohíbe, etc.), con el sujeto gramatical y el plazo cuando están presentes.

Argumento	Tipo	Descripción
id	int	ID de la norma
--con-plazo, -p	flag	Mostrar solo obligaciones que tienen plazo detectado

python bcn_cli.py nlp obligaciones 206396
python bcn_cli.py nlp obligaciones 206396 --con-plazo

---

nlp eliminar — Borrar análisis NLP

python bcn_cli.py nlp eliminar <id> [--solo TABLA] [--si]

Elimina el análisis NLP de una norma, de forma completa o parcial por tabla. Muestra un resumen de cuántas filas se borrarán y pide confirmación antes de proceder.

Argumento	Tipo	Descripción
id	int	ID de la norma
--solo, -s	str	Tabla a borrar: referencias, entidades, obligaciones. Se puede repetir. Sin este flag se borra el análisis completo.
--si, -y	flag	Confirmar automáticamente sin preguntar

# Borrar análisis completo (pide confirmación)
python bcn_cli.py nlp eliminar 206396

# Borrar solo entidades
python bcn_cli.py nlp eliminar 206396 --solo entidades

# Borrar entidades y referencias a la vez
python bcn_cli.py nlp eliminar 206396 --solo entidades --solo referencias

# Sin confirmación interactiva
python bcn_cli.py nlp eliminar 206396 --si

Caution

El borrado es irreversible. Usa --solo para borrar por partes si solo quieres re-analizar una tabla específica en lugar de todo el análisis.

---

nlp stats — Estadísticas globales NLP

python bcn_cli.py nlp stats

Muestra el total de normas analizadas, referencias extraídas (resueltas vs pendientes), entidades y obligaciones registradas en la base de datos.

---

REST API

Además de la CLI, puedes levantar la API REST:

fastapi dev api/main.py

La documentación interactiva estará disponible en:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Ver la referencia completa de la API para el detalle de los endpoints.