CLI

Olivares AI se distribuye como un único binario estático de Go, controlplane. El mismo artefacto es el motor, la consola web embebida (servida en el mismo origen que la API) y el colector de borde — el rol que obtienes lo elige el subcomando que ejecutas. No hay descargas separadas de «servidor» y «agente».

Esta página documenta los comandos y flags confirmados en el binario actual. No es exhaustiva y la superficie es anterior a la 1.0: los subcomandos, flags y valores por defecto pueden cambiar. En caso de duda, ejecuta controlplane <command> --help contra el build exacto que desplegaste y trátalo como la fuente autoritativa. Para saber cómo obtener y ejecutar el binario, consulta Self-host; para los ajustes que residen en el entorno en lugar de en flags, consulta Configuración.

Resumen de comandos

controlplane <command> [flags]

El comando raíz agrupa, entre otros:

Las secciones siguientes cubren los comandos a los que los operadores recurren primero. keys, license y evals son reales pero especializados; ejecútalos con --help para conocer sus superficies de flags.

controlplane serve

Ejecuta el control plane: el servidor HTTP (la API REST más la consola embebida) y el servidor gRPC. Tres propiedades son valores por defecto, no opciones que haya que activar:

• TLS está activado por defecto. Sin certificado suministrado, el motor genera un certificado autofirmado en el directorio de datos y registra su huella SHA-256; los clientes deben confiar en ella o fijarla (pin). El servidor gRPC falla cerrado — fuera de --insecure se niega a arrancar en texto plano en lugar de degradar silenciosamente.
• Loopback por defecto. Ambos listeners enlazan a 127.0.0.1. Exponer el control plane más allá del host local es un cambio deliberado: configuras un bind que no sea loopback y lo pones detrás de tu propio ingress. El control plane se ejecuta en tu infraestructura y puede estar air-gapped.
• Sin credenciales por defecto. En una instalación nueva sin usuarios, el motor acuña un token de configuración de un solo uso (prefijo olst_) y lo imprime solo por stdout (nunca en los logs). Arrancas (bootstrap) el primer administrador enviando ese token a POST /v1/setup y luego inicias sesión.

controlplane serve
# Lee el token de configuración olst_ de un solo uso desde el stdout de este proceso.

Flags útiles

SQLite (Go puro, un solo nodo) encaja en instalaciones air-gapped de un solo nodo. Seleccionar postgres es lo que se hace en despliegues multi-tenant o de escalado horizontal, donde la seguridad a nivel de fila (row-level security) es el respaldo del tenant. Hay flags adicionales para la residencia y los roles de Postgres (--admin-dsn, --region, --known-regions, --allow-privileged-db-role) — consulta su --help y Configuración.

--insecure sirve HTTP y gRPC en texto plano, así que los bearer tokens viajan en claro. Nunca lo uses en ninguna dirección accesible más allá del host local.

--seed-demo es solo para demos

--seed-demo aprovisiona un estate sintético y fabricado junto con un administrador de demo cuya contraseña es pública (vive en el árbol de fuentes). Existe para hacer que la consola y los tests end-to-end se rendericen contra datos con forma real. Como la credencial es pública, serve se niega a arrancar con --seed-demo en cualquier bind que no sea loopback y sale con un error que te indica que enlaces a 127.0.0.1.

Trátalo como desechable: usa un directorio de datos descartable y nunca lo apuntes a datos que te importen. Una instalación real es serve sin --seed-demo, donde el motor acuña un token de configuración de un solo uso y creas tu propio administrador. Consulta Quickstart para el recorrido de la demo.

controlplane collector

Ejecuta el binario como colector de borde para la topología distribuida. Un colector carga los connectors de origen configurados localmente y empuja sus observaciones a un core remoto sobre gRPC. No abre ningún listener entrante — disca hacia fuera, no acepta conexiones, así que un colector que falla nunca queda en el data path de ningún agente.

controlplane collector --core-addr host:port [flags]

--core-addr es obligatorio. El colector se autentica ante el core con un bearer token que porta un principal de ingesta (--token-file, o $OLIVARES_INGEST_TOKEN) y — cuando el core impone TLS mutuo — un certificado de cliente de colector (--client-cert, --client-key, con --ca para fijar un cert de core autofirmado). Tanto serve como collector cablean sus connectors desde la misma configuración; un origen sin configurar avisa honestamente en lugar de hacer fallar el proceso. La configuración de orígenes se cubre en Conectar un origen.

controlplane version

Imprime la versión, el commit, la fecha de build, el OS/arch y el runtime de Go, además del modo FIPS 140-3 de este binario (un modo, no una declaración de validación).

controlplane version

La cadena de versión se inyecta en tiempo de build; un build desde un árbol de trabajo sin tag reporta una versión de desarrollo. No trates la cadena como procedencia — verifica las releases con los artefactos firmados. Consulta Verificar una release.

controlplane openapi

Imprime el documento OpenAPI 3.1 del motor por stdout, con indentación determinista para que la salida produzca diffs limpios, sin un servidor en ejecución.

controlplane openapi > openapi.json

Este es el mismo contrato que el motor sirve en GET /openapi.json. La superficie REST servida cubre las rutas core; algunas rutas de módulo son accesibles pero deliberadamente no forman parte del documento servido.

controlplane audit y dr

El ledger de evidencias tiene dos grupos de comandos sin conexión:

• audit opera sobre el ledger de solo anexado (append-only): verify para la cadena de hashes de un tenant y sus checkpoints firmados, checkpoint para escribir uno nuevo, export a un formato SIEM (cef/syslog/otlp) y archive export / archive verify para el archivo inmutable que se re-verifica sin conexión. audit verify y audit archive verify imprimen un informe JSON y salen con 0 por defecto; pasa --strict para salir con código distinto de cero ante un fallo de comprobación de integridad, de modo que cron o CI puedan condicionarse a ello. Los pins de clave externos (--pubkey, --event-pubkey) reemplazan las claves consultivas del propio equipo (on-box) para una comprobación resistente a atacantes.
• dr es un backup / restore con continuidad del ledger garantizada, más verify (un simulacro de DR no destructivo) e inspect. A diferencia de un volcado de base de datos crudo, captura las claves de firma bajo tu clave de cifrado de claves (key-encryption key), registra los extremos (tips) de cadena por tenant y re-verifica toda la cadena al restaurar. restore y verify salen con código distinto de cero a menos que el ledger restaurado esté en verde.

Estos comandos respaldan el modelo de verificación descrito en Gobernanza y Verificar una release.

Estabilidad

Anterior a la 1.0, en desarrollo activo. Los comandos y flags anteriores están confirmados en el binario actual, pero la superficie completa aún está evolucionando. Ejecuta controlplane <command> --help contra tu build y trátalo como autoritativo por encima de cualquier documento. Para lo que está implementado hoy frente a lo planificado, consulta Honestidad y límites.