---
id: 0017
title: CLI `gx` para hablar con el endpoint local
status: pending
priority: medium
created: 2026-05-01
depends_on: [0012]
---

## Objetivo

Cliente CLI fino, instalable en `~/.local/bin/gx`, que habla con el
endpoint HTTP local de `graph_explorer` (issue 0012). Permite ingesta y
consulta desde terminal o scripts sin abrir la app.

## Comandos

- `gx add <type> <name> [--metadata k=v ...]` — crea entidad.
- `gx rel <from_id> <kind> <to_id>` — crea relacion.
- `gx ingest <file>` — manda archivo al endpoint, abre preview en TUI.
- `gx from-url <url>` — fetch + extract.
- `gx search "query"` — devuelve hits del grafo activo (json o tabla).
- `gx neighbors <id> [--depth N]`.
- `gx open <id>` — abre el grafo y enfoca el nodo en `graph_explorer`.

## Decisiones

- Implementar como sub-comando del `fn` CLI existente (`fn gx ...`) o
  binario aparte? Probablemente sub-comando para reusar config y auth.
- Output JSON por defecto si stdout no es TTY (componible con jq).
- Tabla legible si stdout es TTY.

## Definicion de hecho

- `gx add person "Juan Perez"` añade el nodo en el grafo en vivo.
- `gx ingest articulo.pdf` lanza preview interactivo en terminal y commit.
- `gx neighbors <id> --depth 2 --format json | jq` funciona en pipeline.
- Errores de conexion al endpoint se reportan claros (no stack traces).