NAQUADA
Abrir Naquada
Flujo verificable

Puente local en Rust

Instalar y usar la CLI de Naquada

La CLI conecta tu proyecto y Codex con Naquada Producción. Autentica al usuario, expone MCP y entrega assets con recibos verificables.

Instalar en macOS, Windows o Linux

Descarga solo archivos firmados desde el canal oficial. Cada versión debe incluir sumas SHA-256.

Canal de descarga no configurado

El operador debe definir NEXT_PUBLIC_NAQUADA_CLI_DOWNLOADS_URL antes de publicar. Esta página no inventa binarios ni mirrors.

Elige el archivo de tu sistema y arquitectura, extráelo y coloca el binario en un directorio del PATH.

macOS

Terminal
# After downloading the macOS archive
chmod +x ./naquada
sudo install -m 0755 ./naquada /usr/local/bin/naquada

Linux

Terminal
# After downloading the Linux archive
chmod +x ./naquada
sudo install -m 0755 ./naquada /usr/local/bin/naquada

Windows PowerShell

PowerShell
$destination = "$env:LOCALAPPDATA\Naquada\bin"
New-Item -ItemType Directory -Force $destination
Copy-Item .\naquada.exe "$destination\naquada.exe"
[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";$destination",
  "User"
)
Terminal
naquada --version
naquada --help

Verificación

Resultado esperado: ambas órdenes muestran la versión y la ayuda sin errores.

Instalar desde el código fuente

Solo para contribuidores con el monorepo y Rust estable.

Cargo
cargo install --locked --path apps/naquada-cli

Iniciar sesión sin copiar una clave

La CLI interactiva usa un código de dispositivo. La contraseña nunca pasa por el terminal.

Terminal
naquada login
naquada whoami
  1. La CLI abre la página de producción.
  2. Compruebas el código y autorizas el dispositivo.
  3. La sesión corta se guarda en el almacén seguro del sistema.
  4. naquada logout revoca la sesión y elimina la copia local.

No crees una clave global para la CLI

La CLI y la extensión usan autorización por dispositivo. Las claves globales son para servidores, scripts e integraciones desatendidas.

Vincular el directorio actual

Se crea un contexto Naquada y los recibos locales necesarios. No se recorre el repositorio.

Terminal
naquada project link \
  --name "Mi proyecto" \
  --tag mi-proyecto

naquada project status

Resultado concreto

  • .naquada/project.json contiene el ID y la etiqueta.
  • .naquada/config.json contiene solo reglas locales.
  • Existen .naquada/runs/ y .naquada/assets/.
  • naquada project status encuentra el mismo contexto remoto.

Registrar el servidor MCP en Codex

Registra el binario actual como servidor MCP stdio mediante el comando oficial codex mcp add.

Terminal
naquada setup codex --apply

Verificación

Recarga Codex y verifica que naquada esté activo en la lista MCP.

Referencia de comandos

Añade --json antes del subcomando para obtener una salida estable.

naquada login / logout / whoamiGestionar la sesión.
naquada project linkCrear o vincular el contexto.
naquada project statusComparar el vínculo local y remoto.
naquada run listListar recibos locales.
naquada run status <id>Ver estado remoto y recibo.
naquada run resume <id>Reanudar una entrega aprobada.
naquada run cancel <id>Solicitar la cancelación.
naquada mcp serveIniciar el servidor MCP stdio.
naquada setup codex --applyRegistrar MCP en Codex.
naquada docsAbrir esta documentación pública.
naquada doctorComprobar sesión, proyecto y API.

Entrega y reanudación de assets

La ejecución remota y la entrega local son etapas distintas; el recibo hace la entrega idempotente.

  • Solo se suben referencias nombradas por el plan.
  • El asset pasa por .naquada/assets/, se verifica y se mueve.
  • La ruta final debe permanecer dentro del workspace.
  • Sin sobrescritura explícita se añaden -02, -03, etc.
  • run resume continúa desde el recibo tras un reinicio.
  • Nunca se ejecuta Git.
Terminal
naquada run list
naquada run status <run-id>
naquada run resume <run-id>

Sesiones, claves globales y claves de publicación

Naquada separa tres credenciales para no reutilizar una clave demasiado potente.

1

Sesión CLI / extensión

Código de dispositivo, tokens cortos, almacén seguro y revocación al cerrar sesión.

2

Clave global — prefijo nqk_acc_

Para automatización sin usuario. Tiene permisos granulares, caducidad, límite de peticiones y revocación inmediata; el secreto solo se muestra una vez.

Account API
curl https://api.naquada.tech/api/account/v1/capabilities \
  -H "Authorization: Bearer $NAQUADA_ACCOUNT_KEY"
3

Clave de publicación — ctr_prd_ o ctr_sbx_

Sandbox/Producción no cambia. Una clave global necesita externalizations:invoke, delegación a la clave Production y la cabecera X-Naquada-Externalization-Key-Id.

Delegated publication
curl "https://api.naquada.tech/api/v1/generate/my-slug?version=1" \
  -H "Authorization: Bearer $NAQUADA_ACCOUNT_KEY" \
  -H "X-Naquada-Externalization-Key-Id: <production-key-id>" \
  -H "Content-Type: application/json" \
  -d '{"inputs":{"prompt":"Hola"}}'

Rotación recomendada

Crea y despliega una clave nueva, comprueba su uso y después revoca y elimina la antigua. Los permisos son inmutables.

Diagnóstico y resultado esperado

El informe JSON permite comprobar cada requisito.

Terminal
naquada --json doctor

Resultado

Está listo cuando ok, authenticated, projectLinked y apiReachable son true y gitTouched es false.