CLI `b2g`¶

Referencia completa del CLI agente-native b2g: el grupo principal y todos sus subcomandos, con sus opciones y textos de ayuda. Se autogenera desde el grupo Click (mkdocs-click): es la misma información que b2g --help, siempre en sincronía con el código.

Salida JSON

Cada subcomando acepta --json (envelope versionado) y respeta los exit codes 0–5. Los detalles del contrato (envelope, exit codes, FSM) están en Contratos detallados.

Términos no claros

Si un término en el CLI no te queda claro, revisa el Glosario.

b2g¶

b2g — bib2graph CLI agente-native.

Transforma corpus bibliográficos en redes bibliométricas reproducibles.

El workspace activo se resuelve en este orden (ADR 0029): 1. --workspace (forma canónica) 2. Variable de entorno B2G_WORKSPACE 3. workspace.json encontrado subiendo desde el directorio actual

Si no hay ninguno, los comandos que necesitan la biblioteca emiten un error accionable (exit 1) que sugiere 'b2g init' o '--workspace'.

Ejemplo: b2g init mi-investigacion cd mi-investigacion b2g seed --equation "unequal exchange" b2g status --json

Usage:

b2g [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--version`	boolean	Show the version and exit.	`False`
`--workspace`	path	Carpeta del workspace activo. Si no se pasa, se resuelve vía B2G_WORKSPACE o buscando workspace.json hacia arriba desde el directorio actual (ADR 0029).	None
`--help`	boolean	Show this message and exit.	`False`

b2g build¶

Computa redes bibliométricas y escribe artefactos.

Sin --spec: usa Networks.quick (4-5 redes principales). Con --spec: carga el YAML y construye cada red con Networks.build.

En ambos modos transiciona a BUILT y sella networks/.corpus_hash.

Usage:

b2g build [OPTIONS]

Options:

Name	Type	Description	Default
`--out-dir`	text	Directorio base de artefactos (default: /networks/ o /networks/).	None
`--scope`	choice (`all` \| `accepted` \| `seeds`)	Filtra el corpus antes de construir las redes. 'all' = corpus completo (default); 'accepted' = semillas (is_seed=True) + papers aceptados; 'seeds' = solo semillas (is_seed=True). Si el scope deja 0 papers, termina con exit 0 y un warning accionable.	`all`
`--spec`	file	Ruta al YAML con la especificación de redes. Si se pasa, usa Networks.build por spec en lugar de Networks.quick. Sigue transicionando a BUILT y sellando corpus_hash (D1).	None
`--min-weight`	integer	Peso mínimo de arista (default 1 = sin filtro). Aristas con peso < N se descartan. Solo aplica al modo quick (sin --spec); en modo spec el YAML lleva su propio min_weight.	`1`
`--max-citing`	integer	Tope de citantes por seed en la pasada cited_by automática. Default: sin tope. Solo aplica cuando hay seeds aceptadas.	None
`--email`	text	Email para el polite pool de OpenAlex (pasada cited_by).	None
`--thesaurus`	file	Ruta al JSON del thesaurus multilingüe (formato ADR 0011). Aplica consolidacion conceptual cross-lingue sobre keywords_id ANTES de proyectar redes, y persiste el corpus actualizado. Absorbe la capacidad del verbo retirado b2g thesaurus (#164).	None
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

b2g chain¶

Expande el corpus con candidatos rankeados por information scent.

Con --preview (dry-run), solo muestra la estimación de crecimiento sin tocar la red ni el corpus. Sin --preview, transiciona el estado a FORAGED.

Usage:

b2g chain [OPTIONS]

Options:

Name	Type	Description	Default
`--direction`	choice (`backward` \| `forward` \| `both`)	Dirección del chaining.	`both`
`--depth`	integer	Profundidad del chaining (solo 1 soportado).	`1`
`--max-candidates`	integer	Tope de candidatos (sin límite por defecto).	None
`--max-citing`	integer	Presupuesto de citantes por semilla en forward chaining.	`50`
`--email`	text	Email para el polite pool de OpenAlex.	None
`--preview`	boolean	Estima el crecimiento potencial SIN fetchear ni modificar el corpus (dry-run). Backward: exacto desde references_id. Forward: exacto si el corpus tiene cited_by_id (poblado por un chain forward previo), si no, indica que se necesita fetch.	`False`
`--since`	text	Forrajeo incremental: solo trae citantes publicados desde esta fecha. Acepta fecha ISO (YYYY-MM-DD) o atajo relativo (90d, 6m, 1y). Fuerza direction=forward y transiciona a MONITORED (no a FORAGED). Incompatible con --direction backward.	None
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

b2g curate¶

Curación del corpus: dump, apply, accept, reject, filter.

Subcomandos: dump, apply, accept, reject, filter.

Ejemplos: b2g curate dump b2g curate dump --scope all b2g curate apply curacion.csv b2g curate accept --ids W1 --ids W2 b2g curate reject --ids W3 b2g curate filter --year-gte 2018 --year-lte 2024

Usage:

b2g curate [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

b2g curate accept¶

Marca papers como accepted en el corpus.

Curación TRANSVERSAL: no transiciona el CycleState. Disponible en cualquier estado del lazo (Nota 05 §4, ADR 0016 enmendado R3).

Usage:

b2g curate accept [OPTIONS]

Options:

Name	Type	Description	Default
`--ids`	text	IDs de papers a aceptar (repetible: --ids ID1 --ids ID2).	`Sentinel.UNSET`
`--by`	text	Identificador de quien decide.	`cli`
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

b2g curate apply¶

Reimporta decisiones de curación desde CSV al corpus.

CSV_FILE es el archivo CSV editado producido por b2g curate dump. Solo las columnas id y decision son requeridas; el resto se ignora (garantiza round-trip dump→apply aunque el CSV tenga columnas extra).

Decisiones aceptadas: accepted, rejected, undecided (no-op).

Idempotente: reimportar el mismo CSV produce el mismo estado final.

Curación TRANSVERSAL: no transiciona el CycleState.

Usage:

b2g curate apply [OPTIONS] CSV_FILE

Options:

Name	Type	Description	Default
`--by`	text	Identificador de quien decide (curador).	`cli`
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

b2g curate dump¶

Exporta papers a CSV para revisión offline.

Por defecto exporta solo los candidatos forrajeados (is_seed=False, status=candidate). Editá las columnas decision y note en Excel/Calc y luego reimportá con b2g curate apply.

Curación TRANSVERSAL: no transiciona el CycleState.

Usage:

b2g curate dump [OPTIONS]

Options:

Name	Type	Description	Default
`--out`	path	Ruta de salida del CSV. Override del default /exports/curacion.csv.	None
`--scope`	choice (`candidates` \| `seeds` \| `all`)	Qué papers exportar. 'candidates' (default) = forrajeados a revisar (is_seed=False, status=candidate). 'seeds' = semillas originales. 'all' = todo el corpus.	`candidates`
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

b2g curate filter¶

Aplica filtros PRISMA al corpus (marca rejected, no borra).

Tras el filtro, el estado del lazo transiciona a FILTERED.

Este es el único subcomando de curate que transiciona el CycleState (el verbo define la transición — precedente D1 de #159).

Usage:

b2g curate filter [OPTIONS]

Options:

Name	Type	Description	Default
`--year-gte`	integer	Incluir años >= este valor.	None
`--year-lte`	integer	Incluir años <= este valor.	None
`--language`	text	Códigos ISO 639-1 a incluir (repetible: --language en --language es).	`Sentinel.UNSET`
`--type`	text	Áreas de investigación a incluir (repetible).	`Sentinel.UNSET`
`--min-citations`	integer	Mínimo de citantes en cited_by_id.	None
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

b2g curate reject¶

Marca papers como rejected en el corpus.

Curación TRANSVERSAL: no transiciona el CycleState. Disponible en cualquier estado del lazo (Nota 05 §4, ADR 0016 enmendado R3).

Usage:

b2g curate reject [OPTIONS]

Options:

Name	Type	Description	Default
`--ids`	text	IDs de papers a rechazar (repetible: --ids ID1 --ids ID2).	`Sentinel.UNSET`
`--by`	text	Identificador de quien decide.	`cli`
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

b2g export¶

Serializa artefactos de build al formato pedido (GraphML o CSV).

No transiciona el CycleState.

El directorio de salida por defecto es <workspace>/exports/. Con --out-dir se puede especificar un directorio alternativo.

Usage:

b2g export [OPTIONS]

Options:

Name	Type	Description	Default
`--format`	choice (`graphml` \| `csv`)	Formato de salida.	`graphml`
`--out-dir`	text	Directorio de salida para los archivos exportados (default: /exports/ o /exports/).	None
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

b2g init¶

Inicializa una carpeta como workspace de investigación.

TARGET puede ser un nombre de carpeta nueva (se crea en el cwd) o un directorio existente (incluido '.' para el directorio actual).

Ejemplos:

b2g init mi-estudio # crea ./mi-estudio/ como workspace

b2g init . # inicializa el cwd como workspace

b2g init mi-estudio --name "Estudio de redes IED"

Usage:

b2g init [OPTIONS] [TARGET]

Options:

Name	Type	Description	Default
`--name`	text	Nombre legible de la investigación (default: nombre del directorio destino).	None
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

b2g read¶

Lee papers del corpus (read-only).

Subcomandos: list, stats, show, top.

Ejemplos: b2g read list --query "unequal exchange" b2g read list --status accepted --json b2g read stats --group-by year b2g read show --id W2741809807 b2g read show --id 10.1016/j.ecolecon.2019.01.001 b2g read top --top 5 --json b2g read top --kind cocitation --json

Usage:

b2g read [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

b2g read list¶

Lista papers del corpus con filtros opcionales.

Los filtros se combinan con AND lógico. Sin filtros devuelve todos los papers.

Campos devueltos por paper: id, title, year, curation_status, is_seed.

Usage:

b2g read list [OPTIONS]

Options:

Name	Type	Description	Default
`--query`	text	Texto a buscar en el título (substring, case-insensitive).	None
`--status`	choice (`candidate` \| `accepted` \| `rejected`)	Filtrar por curation_status exacto.	None
`--seeds`	boolean	Mostrar solo semillas (is_seed=True). Excluyente con --candidates.	`False`
`--candidates`	boolean	Mostrar solo no-semillas (is_seed=False). Excluyente con --seeds.	`False`
`--year`	integer	Filtrar por año exacto de publicación.	None
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

b2g read show¶

Muestra la fila completa de un paper.

Resuelve --id contra id, doi y source_id (en ese orden de prioridad). Devuelve ~14 campos: id, source_id, doi, title, year, abstract, is_seed, curation_status, authors_raw, authors_id, keywords_id, references_id, cited_by_id, provenance.

Usage:

b2g read show [OPTIONS]

Options:

Name	Type	Description	Default
`--id`	text	Identificador del paper: id interno, DOI o source_id. Se prueba en ese orden (ADR 0036).	`Sentinel.UNSET`
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

b2g read stats¶

Estadísticas del corpus agrupadas por una dimensión.

Dimensiones válidas: status (default), year, is_seed.

Usage:

b2g read stats [OPTIONS]

Options:

Name	Type	Description	Default
`--group-by`	choice (`status` \| `year` \| `is_seed`)	Dimensión de agrupación.	`status`
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

b2g read top¶

Muestra los nodos más centrales y los pares de co-citación con título.

Dos bloques de salida:

central — top N nodos de la red --kind, ordenados por degree_centrality descendente. Default: bibliographic_coupling (robusto en one-shot frío, no requiere enrich previo). cocitation — top N pares de co-citación por peso, SIEMPRE desde la red cocitation (requiere cited_by_id poblado: por un 'b2g chain --direction forward' previo o la pasada cited_by de 'b2g build'). Si la red está vacía → bloque vacío con reason/fix_command (honest-empty, exit 0).

No requiere 'b2g build' previo: recomputa en tiempo de lectura.

Usage:

b2g read top [OPTIONS]

Options:

Name	Type	Description	Default
`--top`, `-n`	integer	Número de nodos/pares a mostrar.	`10`
`--kind`	choice (`bibliographic_coupling` \| `cocitation` \| `author_collab` \| `institution_collab` \| `keyword_cooccurrence`)	Tipo de red para el bloque de nodos centrales.	`bibliographic_coupling`
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

b2g schema¶

Describe el contrato del envelope: JSON-schema, exit codes y versión.

Comando META (como skill): no transiciona la FSM, no resuelve workspace. Determinista y estático — mismo resultado en cualquier invocación, sin dependencia del workspace activo ni de la red.

Usage:

b2g schema [OPTIONS]

Options:

Name	Type	Description	Default
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

b2g seed¶

Siembra el corpus. Exactamente uno de los tres modos es requerido.

Modos mutuamente excluyentes: --equation '' siembra desde OpenAlex con la ecuación dada. --spec equation.yaml siembra desde OpenAlex con parámetros del YAML. --from-bib archivo.bib siembra desde un archivo BibTeX local (sin red).

Para cargar un corpus curado desde un parquet sin red, usá b2g snapshot restore.

Tras el seed, el estado del lazo transiciona a SEEDED.

Ejemplos: b2g seed --equation "unequal exchange" b2g seed --spec equation.yaml b2g seed --from-bib semillas.bib

Usage:

b2g seed [OPTIONS]

Options:

Name	Type	Description	Default
`--equation`	text	Ecuación de búsqueda bibliográfica (modo OpenAlex directo). Los términos se combinan en AND dentro de title_and_abstract.search: agregar términos REDUCE los resultados. Usá --preview para ver la query sin gastar la llamada, o --exclude para AND NOT.	None
`--spec`	path	Ruta a un YAML con la ecuación de búsqueda declarativa (equation.yaml; mutuamente excluyente con --equation y --from-bib).	None
`--from-bib`	path	Ruta a un archivo BibTeX (.bib) para sembrar sin red (mutuamente excluyente con --equation y --spec).	None
`--native`	boolean	Pasar la ecuación cruda a OpenAlex sin traducción (solo con --equation).	`False`
`--email`	text	Email para el polite pool de OpenAlex (recomendado; solo con --equation/--spec).	None
`--max-results`	integer	Tope de resultados a traer de OpenAlex, default: 200 (solo con --equation/--spec).	None
`--exclude`	text	Término a excluir del título/abstract (repetible; solo con --equation/--spec). Cada valor agrega AND NOT title_and_abstract.search:"…" al filtro.	`Sentinel.UNSET`
`--min-year`	integer	Año mínimo de publicación (solo con --equation/--spec). Genera from_publication_date:-01-01 en el filtro de OpenAlex.	None
`--max-year`	integer	Año máximo de publicación (solo con --equation/--spec). Genera to_publication_date:-12-31 en el filtro de OpenAlex.	None
`--resolve`	boolean	Tras cargar el .bib, resolver DOIs a source_id de OpenAlex (solo con --from-bib; resuelve automáticamente en la misma invocación).	`False`
`--preview`	boolean	Muestra la query que se ejecutaría en OpenAlex SIN fetchear ni tocar el corpus (dry-run; solo con --equation/--spec). Sirve para razonar la ecuación —los términos van en AND— antes de gastar la llamada.	`False`
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

b2g skill¶

Gestión de la skill de bib2graph para agentes de código.

Subcomandos: add, providers.

Ejemplos: b2g skill add b2g skill add --project b2g skill add --provider opencode b2g skill add --force b2g skill providers

Usage:

b2g skill [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

b2g skill add¶

Instala la skill de bib2graph en el directorio de skills del provider.

Por defecto usa el provider claude-code e instala en ~/.claude/skills/bib2graph/ (scope --user). Con --project instala en /.claude/skills/bib2graph/. Con --provider opencode instala en la ruta nativa de OpenCode (.opencode/skills/bib2graph/).

Es idempotente: si la versión vendida ya está instalada, no hace nada y lo reporta. Si el destino existe pero difiere, use --force para pisarlo.

Usage:

b2g skill add [OPTIONS]

Options:

Name	Type	Description	Default
`--provider`	choice (`claude-code` \| `opencode`)	Cliente destino de la instalación (ADR 0046).	`claude-code`
`--user`	text	Instala la skill en la raíz global del provider (default).	`True`
`--project`	text	Instala la skill en /.	`Sentinel.UNSET`
`--force`	boolean	Pisar el destino si ya existe.	`False`
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

b2g skill providers¶

Lista los providers soportados por skill add (ADR 0046, #193).

Comando meta e introspectable: no requiere workspace ni transiciona FSM.

Usage:

b2g skill providers [OPTIONS]

Options:

Name	Type	Description	Default
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

b2g snapshot¶

Gestión de snapshots del corpus: create y restore.

Subcomandos: create, restore.

Ejemplos: b2g snapshot create b2g snapshot create --out-dir mis_snaps/ b2g snapshot restore --from-corpus snaps/corpus.parquet

Usage:

b2g snapshot [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

b2g snapshot create¶

Exporta una foto sellada del corpus actual (parquet + manifest.json).

No transiciona el CycleState.

El directorio de salida por defecto es <workspace>/snapshots/. Con --out-dir se puede especificar un directorio alternativo.

Usage:

b2g snapshot create [OPTIONS]

Options:

Name	Type	Description	Default
`--out-dir`	text	Directorio destino del snapshot (default: /snapshots/ o /snapshots/).	None
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

b2g snapshot restore¶

Rehidrata el corpus desde un parquet curado sin tocar la red.

Carga el parquet con el schema canónico de bib2graph, hace merge con el corpus existente y transiciona el lazo a FILTERED (el corpus ya fue curado; build y networks pueden correr a continuación).

Preserva las columnas de curación del parquet (curation_status, is_seed).

Ejemplos: b2g snapshot restore --from-corpus snapshots/corpus.parquet b2g snapshot restore --from-corpus corpus_curado.parquet --json

Usage:

b2g snapshot restore [OPTIONS]

Options:

Name	Type	Description	Default
`--from-corpus`	path	Ruta al parquet con el corpus curado a importar sin red (producido por b2g snapshot create).	`Sentinel.UNSET`
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

b2g status¶

Muestra el estado del lazo (CycleState) y conteos de curación.

No transiciona el CycleState.

El mapa del lazo incluye: - Estado actual y transiciones disponibles (incluyendo reseed). - accept/reject como acciones siempre-disponibles (curación transversal). - Contador de ronda. - ADR 0029: workspace resuelto (root y fuente de resolución).

Usage:

b2g status [OPTIONS]

Options:

Name	Type	Description	Default
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

b2g validate¶

Valida el schema y consistencia del store.

Exit 0: válido. Exit 2: datos inválidos. Exit 5: store corrupto.

Usage:

b2g validate [OPTIONS]

Options:

Name	Type	Description	Default
`--json`	boolean	Salida JSON estructurada (también activado por B2G_JSON=1).	`False`
`--help`	boolean	Show this message and exit.	`False`

CLI b2g¶

b2g¶

b2g build¶

b2g chain¶

b2g curate¶

b2g curate accept¶

b2g curate apply¶

b2g curate dump¶

b2g curate filter¶

b2g curate reject¶

b2g export¶

b2g init¶

b2g read¶

b2g read list¶

b2g read show¶

b2g read stats¶

b2g read top¶

b2g schema¶

b2g seed¶

b2g skill¶

b2g skill add¶

b2g skill providers¶

b2g snapshot¶

b2g snapshot create¶

b2g snapshot restore¶

b2g status¶

b2g validate¶

CLI `b2g`¶