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

---

REST API

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

uvicorn api:app --reload --port 8000

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.