NAQUADA
Open Naquada
Verifiable workflow

Local Rust bridge

Install and use the Naquada CLI

The CLI is the cross-platform bridge between your project, Codex, and Naquada Production. It authenticates users, exposes MCP, and delivers assets with verifiable receipts.

Install on macOS, Windows, or Linux

Download only a signed archive from the official channel. Every public release must include SHA-256 checksums.

Download channel not configured

The operator must set NEXT_PUBLIC_NAQUADA_CLI_DOWNLOADS_URL to the signed artifacts before publication. This page deliberately invents no binary or mirror.

Choose the archive for your operating system and architecture, extract it, then place the binary in a directory on 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

Check

Expected result: the commands print a version and help without errors.

Install from source

For contributors who already have the monorepo and stable Rust.

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

Sign in without copying a secret key

The interactive CLI uses a device code, like modern AI tools. Your password never passes through the terminal.

Terminal
naquada login
naquada whoami
  1. The CLI opens the Naquada Production page.
  2. You verify the code and approve the device in your account.
  3. The short session and refresh token are stored in the OS credential vault.
  4. naquada logout revokes the remote session and removes the local copy.

Do not create a global key for the CLI

The CLI and VS Code extension use device authorization. Global account keys are for unattended integrations, servers, and scripts.

Link the current directory

Linking creates a Naquada project context and local receipt files. It does not crawl the repository.

Terminal
naquada project link \
  --name "My project" \
  --tag my-project

naquada project status

Concrete result

  • .naquada/project.json contains the project ID and tag.
  • .naquada/config.json contains local rules only.
  • .naquada/runs/ and .naquada/assets/ exist.
  • naquada project status resolves the same production context.

Register the MCP server with Codex

This registers the current binary as an stdio MCP server for the workspace through the official codex mcp add command.

Terminal
naquada setup codex --apply

Check

Reload Codex, open its MCP server list, and verify that naquada is enabled.

Command reference

Place --json before the subcommand for stable output intended for extensions and scripts.

naquada login / logout / whoamiManage the user session.
naquada project linkCreate or attach the project context.
naquada project statusCompare local and remote linkage.
naquada run listList local receipts.
naquada run status <id>Read remote status and the local receipt.
naquada run resume <id>Resume an approved delivery.
naquada run cancel <id>Request run cancellation.
naquada mcp serveStart the stdio MCP server.
naquada setup codex --applyRegister the server with Codex.
naquada docsOpen this public documentation.
naquada doctorCheck session, project, API, and directories.

Asset delivery and recovery

Remote execution and local delivery are separate steps. The receipt makes delivery idempotent.

  • Local references are hashed and uploaded only when the plan names them.
  • An asset is staged in .naquada/assets/, checked for size and SHA-256, then moved.
  • The final path must remain inside the workspace root.
  • Without explicit overwrite, duplicate names become -02, -03, and so on.
  • After restart, run resume continues from the receipt.
  • No Git operation is ever performed.
Terminal
naquada run list
naquada run status <run-id>
naquada run resume <run-id>

Sessions, global keys, and publication keys

Naquada deliberately separates three credential types so an overly powerful key is not reused everywhere.

1

CLI / extension session

Device authorization, short renewable tokens, OS credential storage, and remote revocation on logout.

2

Global account key — nqk_acc_ prefix

For unattended automation. Select granular account, Board, and publication permissions. The secret is shown once; the key has expiration and rate limits and can be revoked immediately.

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

Publication key — ctr_prd_ or ctr_sbx_ prefix

Existing Sandbox/Production behavior is unchanged. A global key can use one only with externalizations:invoke, a matching Production-key delegation policy, and X-Naquada-Externalization-Key-Id. The publication key secret is never exposed.

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":"Hello"}}'

Recommended rotation

Create a replacement global key, deploy it, verify last use, then revoke and delete the old one. Permissions and delegation are immutable after creation.

Diagnostics and expected result

The JSON report lets an extension or a person verify every prerequisite.

Terminal
naquada --json doctor

Result

The setup is ready when ok, authenticated, projectLinked, and apiReachable are true, paths point into the current project, and gitTouched is false.