Norexus CLI (nrx) is the developer operating layer for Norexus. It routes prompts to installed local CLIs (Codex, Claude, Gemini CLI, GitHub Copilot, Antigravity, Hermes), manages local stack orchestration, auth sessions, MCP servers, and developer utilities — all from one terminal-first interface.

CLI-to-CLI only: no desktop apps, no required API keys for basic usage.

v0.1.0 — Developer Preview. Requires a Norexus account and GitHub repository access. Contact jack@norexus.app for access or licensing.

Install

npm install -g github:JacquesPerrin/norexus.cli
nrx --version

Or link locally for development:

git clone https://github.com/JacquesPerrin/norexus.cli norexus.cli
cd norexus.cli
npm install
npm link
hash -r
which nrx
nrx --version

Login

nrx login

Your browser opens https://auth.norexus.app/cli/<code>. Sign in and approve. The CLI polls and stores a session automatically.

nrx whoami     # verify session
nrx stripe status

No environment variables, database passwords, or Supabase keys are required on your machine.

If the CLI reports that Auth is not ready, the service is temporarily unavailable — try again shortly or contact Norexus support.

Norexus Auth CLI login (users)

Commands

nrx
nrx --theme mono
nrx --theme noir
nrx --banner full
nrx dashboard
nrx --no-header
nrx --version
nrx chat
nrx chat --run
nrx chat --simple
nrx chat --tool claude
nrx chat --tool hermes
nrx chat --mcp shadcn --mcp supabase
nrx ask "fix the login bug"
nrx route "plan the repo architecture"
nrx doctor
nrx dev-up
nrx stack up
nrx stack status
nrx stack down
nrx multitask --task "pnpm dev" --optional --task "stripe listen"
nrx dev:stack
nrx ping
nrx account
nrx login
nrx logout
nrx env
nrx env prod
nrx app list
nrx app open hotel
nrx mcp list
nrx mcp presets
nrx mcp add-preset shadcn
nrx mcp auto
nrx mcp status
nrx stripe status
nrx stripe login
nrx stripe listen
nrx stripe trigger checkout.session.completed
nrx stripe open

Multitask (nrx multitask)

Run several shell commands in parallel from your current working directory. Each line of child stdout/stderr is prefixed with [taskName] so logs stay readable.

Task syntax

• --task "<shell command>" — runs in a login shell ($SHELL -lc on macOS/Linux). Tasks are required by default (non-zero exit fails the command after shutdown).
• --task "name::command" — sets a short name used in the prefix. Only the first :: splits name and command (so URLs and single : stay inside the command).
• --optional — marks the next --task when placed immediately before --task. If the next token is not --task, it marks the previous task (the one you just defined with --task "<...>").

Interrupts

• First Ctrl+C sends SIGINT to all children, waits for them to exit, then prints a summary (succeeded vs failed, including which required tasks failed).
• Second Ctrl+C within about two seconds SIGKILLs stragglers (local dev escape hatch).

Examples

nrx multitask --task "run platform dev" --task "run auth dev" --task "stripe listen"
nrx multitask --optional --task "stripe listen" --task "pnpm dev"
nrx multitask --task "api::cd apps/api && npm run dev" --task "web::pnpm dev"

Preset: nrx dev:stack

Runs the same multitask runner with repo paths resolved from the Norexus workspace (parent of norexus.cli by default, or NOREXUS_WORKSPACE_ROOT if set):

1. Platform — NOREXUS.MONO-main/personal/web, port 1001 (package.json dev script when present, otherwise same Next dev invocation as nrx stack).
2. Auth — NOREXUS.AUTH-main, port 1003 (same discovery).
3. Hotels — NOREXUS.HOTEL-main, port 1006, only if that folder has a package.json.
4. Stripe — stripe listen with the same default --forward-to as nrx stripe listen when the Stripe CLI is on PATH; otherwise skipped with a log line.
5. Supabase — one-shot supabase status in the workspace root when the Supabase CLI is on PATH; always optional (failure does not fail dev:stack).

This preset is local development only; it does not open shells against remote production.

Stripe CLI (wrapper)

nrx stripe forwards to the Stripe CLI binary on your PATH (stripe). nrx stripe status runs stripe whoami (account identity). Use this for local webhook development against apps that expose POST /api/stripe/webhook (typical Next.js route), including work under the Norexus AI LLC Stripe business profile—log into the intended account with stripe login first.

Install the Stripe CLI if which stripe fails; the wrapper prints a short install link.

Commands:

nrx stripe status
nrx stripe login
nrx stripe listen
nrx stripe listen --forward-to http://127.0.0.1:3000/api/stripe/webhook
nrx stripe trigger checkout.session.completed
nrx stripe open

When --forward-to is omitted, nrx stripe listen defaults to:

http://localhost:3000/api/stripe/webhook

All other flags and arguments are passed through to stripe listen. The wrapper does not print or persist secret keys; avoid piping Stripe CLI output into logs.

Example env placeholders for application repos (not required for the CLI itself) live in this package as .env.example.

Header And Theme

The active terminal header is Node-based and lives in ui/header.js. The older Python ui/header.py file is not used by the linked nrx command.

The default command header is compact and monochrome:

nrx

The full dashboard is a Norexus control pane with Account, Environment, Norexus Apps, and Router Status sections:

nrx --banner full
nrx dashboard

Inside chat, the full dashboard is shown once at startup. Use /dashboard to render it again on demand.

config.json supports:

{
  "showHeader": true,
  "theme": "mono",
  "defaultMode": "dry-run"
}

Themes:

mono
noir
gold
pistachio
amber

Examples:

nrx --theme mono
nrx --theme gold doctor
nrx --no-header ping
NO_COLOR=1 nrx

CLI authentication (Auth HTTP API)

Normal user setup does not require NOREXUS_SUPABASE_* or any Supabase anon key on your machine. The CLI talks to Norexus Auth over HTTPS (https://auth.norexus.app by default): POST /api/cli/start, GET /api/cli/poll, POST /api/cli/revoke, GET /api/cli/whoami, and POST /api/cli/audit. Pairing and bearer tokens are enforced in the Auth project database (see NOREXUS.AUTH-main/supabase/migrations/).

User setup (no Supabase env on the workstation)

Variable	Purpose
(none required)	Production login uses the default Auth origin below.
NOREXUS_AUTH_URL	Dev only. Point the CLI at a local Auth app (e.g. http://localhost:1003).
NOREXUS_CLI_SESSION_PATH	Optional. Override session JSON path (default ~/.config/norexus/cli-session.json, or %APPDATA%\\Norexus\\cli-session.json on Windows).

Default Auth base: https://auth.norexus.app. Override with NOREXUS_AUTH_URL only (no other env aliases).

Local Auth development (Auth app + Supabase; not on the CLI workstation)

Developers run Auth locally with Supabase env on the Auth process only — nrx login does not use a DB password or service role on your laptop. Apply schema from the Auth repo:

• NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY — browser session + /cli page.
• SUPABASE_SERVICE_ROLE_KEY — server only for /api/cli/* routes (mint bearer, poll, revoke, audit).

Apply migrations from NOREXUS.AUTH-main (supabase db push). CLI bearer support: 20260513120000_cli_http_bearer_poll.sql (extends 20260512120000_cli_device_session_audit.sql).

Commands

• nrx login — Calls Auth POST /api/cli/start, prints a user code, opens {authBase}/cli/<user_code> (path-based verification URL) in your browser, then polls GET /api/cli/poll until the device is approved. The CLI stores a short-lived bearer-style session token (plus user id, email, role, expiry metadata) in the session file with mode 0600 (and tries 0700 on the parent config directory on Unix). Scope: developer/product access for privileged local commands — not ops tier controls or production shells.
• nrx whoami — Prints session fields from disk. Pass --live to verify the token with GET /api/cli/whoami on Auth.
• nrx logout — Calls POST /api/cli/revoke when a sessionToken is present (server revoke + audit), then deletes the local session file.

Privileged commands (require login)

These fail with a clear message until nrx login has completed successfully:

nrx dev-up, nrx stack …, nrx env prod, nrx multitask …, nrx dev:stack

nrx stripe … does not require a Norexus CLI session; it only shells out to the Stripe CLI on your PATH (use stripe login for Stripe’s own auth).

Valid sessions emit a server-side cli_audit_events row via POST /api/cli/audit when possible, and append a local line to logs/cli_privileged.jsonl.

auth.norexus.app/cli blockers

• Auth app: pairing UI lives at /cli/<user_code> (legacy /cli?user_code= redirects there). Unsigned users hit /login?redirect=/cli/<user_code> (safe internal path).
• Database: RPCs (nrx_claim_cli_device, nrx_cli_user_approve_device, etc.) exist only after migrations are applied to the Auth Supabase project (supabase db push from NOREXUS.AUTH-main — no DB password on CLI workstations).

---

Platform State (scaffold)

Norexus platform scaffold state is stored locally in:

config/norexus.json

This is scaffold-only. It does not implement real authentication, launch apps, or require API keys.

Local scaffold (see config/norexus.json) only affects nrx account when no CLI session exists. After nrx login, nrx account reflects the Auth-backed CLI session instead.

nrx account

To sign out of the paired CLI session (server revoke + delete session file) and reset the scaffold account row in config/norexus.json, use nrx logout (or /logout inside nrx chat).

Environment mode commands:

nrx env
nrx env dev
nrx env prod

nrx env prints the current Norexus platform mode. dev and prod persist to config/norexus.json.

App shortcut commands:

nrx app list
nrx app open ai
nrx app open platform
nrx app open auth
nrx app open hotel
nrx app open vault
nrx app open audit
nrx app open memory
nrx app open network
nrx app open api

For now, app shortcuts only return scaffold messages. Route targets will be added later.

Local Development Stack

nrx dev-up
nrx stack up
nrx stack status
nrx stack down

nrx dev-up starts the local Norexus showcase stack, seeds mock demo data, and opens the core apps in browser tabs. It sets NOREXUS_DEV_SHOWCASE=true for local development only.

Ports:

Platform   platform.norexus.localhost:1001
AI         ai.norexus.localhost:1002
Auth       auth.norexus.localhost:1003
Vault      vault.norexus.localhost:1004
Audit      audit.norexus.localhost:1005
Hotels     hotels.norexus.localhost:1006
Relations  relations.norexus.localhost:1007
API        api.norexus.localhost:1008
CLI        cli.norexus.localhost:1009

The showcase bypass is guarded to localhost-style hostnames, disabled in production and Vercel environments, and writes local audit events under logs/stack/.

Chat

nrx chat

Chat shows the header once, prints a short welcome, keeps one compact status line, then routes normal messages automatically.

Fallback mode for basic terminals:

nrx chat --simple

Run mode and forced tools:

nrx chat --run
nrx chat --dry-run
nrx chat --tool claude

Attach MCP context:

nrx chat --mcp shadcn --mcp supabase

Plain prompt example:

nrx> fix the Supabase auth bug

Selected: Codex
Confidence: 95%
Mode: dry-run
Command: codex "..."

Shell commands are blocked by default for safety:

nrx> cd ..
This looks like a shell command. Run it in your terminal, or use /shell if enabled.

/shell <command> is intentionally non-executing unless shell support is added later.

Slash commands are grouped in /help:

Core:     /help /commands /exit /clear
Routing:  /tool /mode /last /rerun /theme
Account:  /login /logout /account
Env:      /env /env dev /env prod
Tools:    /ping /doctor /tools
MCP:      /mcp /attach /detach /attachments
Logs:     /logs /history
Apps:     /ai /platform /auth /hotel /vault /audit /memory /network /api

All slash commands:

/help
/commands
/dashboard
/exit
/clear
/shell
/tool
/mode
/last
/rerun
/theme
/env
/login
/logout
/account
/tools
/doctor
/ping
/mcp
/attach
/detach
/attachments
/logs
/history
/ai
/platform
/auth
/hotel
/vault
/audit
/memory
/network
/api

Norexus App shortcuts are scaffolded for now. They do not launch apps or route to AI yet:

nrx> /vault
Opening vault is scaffolded. Route target will be added later.

Local scaffold auth and environment mode are also available inside chat:

nrx> /login
Logged in with local scaffold auth as local-dev.
nrx> /env prod
Environment mode set to prod.
nrx> /account
Status    : logged_in
nrx> /hotel
Opening hotel is scaffolded. Route target will be added later.

Autocomplete behavior:

• Type / to show the visible command menu.
• Type /p to filter to /ping.
• Type /mc to filter to /mcp.
• Type /m to show /mcp and /memory.
• Type /me to filter to /memory.
• Type /au to show /auth and /audit.
• Use arrow up/down to move through suggestions.
• Press Tab to complete the selected command.
• Press Enter on a partial slash command to run the selected match.
• Exact commands such as /mcp run directly and stop showing suggestions.

Autocomplete also covers tool names, MCP server names, themes, and common flags:

--run
--dry-run
--tool
--mcp
--json
--verbose
--no-header
--theme

Routing

nrx ask, nrx route, and plain chat messages default to dry-run mode unless config.json sets "defaultMode": "run" or you pass --run.

Routing currently uses local keyword scoring:

• Coding/debugging tasks route to Codex.
• Repo-wide architecture and planning route to Claude.
• Quick CLI/local command tasks route to Gemini CLI.
• GitHub-specific workflows route to GitHub Copilot.
• Autonomous, tool-heavy, MCP-heavy, browser/file/research/delegation, and orchestration tasks route to Hermes when available.
• Unknown/general prompts stay with Norexus Router.

MCP

MCP servers are stored locally in:

config/mcp.json

Commands:

nrx mcp list
nrx mcp presets
nrx mcp add <name> <command>
nrx mcp add-preset supabase
nrx mcp add-preset shadcn
nrx mcp add-preset vercel
nrx mcp add-preset git
nrx mcp add-preset notion
nrx mcp auto
nrx mcp status
nrx mcp remove <name>

Built-in presets:

• git: enabled, npx @modelcontextprotocol/server-git
• github: enabled, npx @modelcontextprotocol/server-github — requires GITHUB_TOKEN
• shadcn: enabled, npx shadcn@latest mcp
• supabase: needsConfig — requires project credentials/config
• vercel: needsConfig — requires Vercel login/token
• notion: needsConfig — requires NOTION_API_KEY (Notion integration token)

Project-aware suggestions:

• .git suggests git.
• .github suggests github.
• components.json or shadcn dependencies suggest shadcn.
• supabase/ directory or SUPABASE_URL env suggests supabase.
• vercel.json, .vercel, or next dependency suggests vercel.
• NOTION_API_KEY in env or env file suggests notion.

Use:

nrx mcp auto

MCP is attachment context only for now. Norexus does not execute MCP servers yet.

In chat, /mcp shows attached MCP servers, available configured MCP servers, and suggested MCP servers. Use /mcp --verbose to include config-file discovery.

Doctor And Ping

nrx doctor
nrx ping
nrx ping --json
nrx ping --verbose

Doctor checks Node, npm, Codex, Claude, Gemini, gh, Antigravity, and Hermes. Ping runs lightweight health checks for Claude, Gemini CLI, Codex, gh copilot, Antigravity, and Hermes with a 5 second timeout per tool. Hermes detection uses hermes --version, falling back to hermes-agent --version.

Logs And History

Routes:

logs/routes.jsonl

Chat prompts:

logs/chat_history.jsonl

Inside chat:

/logs
/history
/last
/rerun

Troubleshooting

Refresh the global command after changes:

cd /path/to/norexus.cli
npm link
hash -r
which nrx
nrx --version

If the header color is hard to read:

nrx --theme mono
NO_COLOR=1 nrx

If a tool is missing:

which codex
which claude
which gemini
which gh
which antigravity
which hermes
which hermes-agent

If --run fails, inspect the dry-run command first:

nrx route "your prompt here"

Development

npm test
node ./bin/nrx.js doctor

---

Platform operator and developer tooling

This section is not relevant to CLI users. If you downloaded and installed nrx, start with nrx login — no steps below are required.

Diagnosing Auth readiness (nrx doctor --dev)

Detailed migration diagnostics are available to platform operators via server logs on the Auth deployment (GET /api/cli/health returns full detail outside production or with the internal admin token).

Applying CLI migrations (operator, one-time per Auth Supabase project)

Database migrations live in NOREXUS.AUTH-main. Apply them once before deploying auth.norexus.app:

cd ../NOREXUS.AUTH-main
npm run apply-cli-migrations

This requires DATABASE_URL or SUPABASE_DB_URL pointing at the Auth project database (Supabase Dashboard → Database → URI). CLI users never need this.

Approving a device (automation / recovery, operators only)

Most users approve in the browser on /cli/<user_code>. For automation or recovery, an owner can approve a claimed device using service role credentials (never commit secrets):

cd norexus.cli
NOREXUS_OWNER_EMAIL='owner@your-domain.example' \
SUPABASE_URL='https://YOUR_PROJECT.supabase.co' \
SUPABASE_SERVICE_ROLE_KEY='YOUR_SERVICE_ROLE_KEY' \
NOREXUS_CLI_ROLE=owner \
npm run approve-cli -- [--device=<uuid>]

Pass a device UUID via --device=<uuid> to approve a specific row, or omit to approve the latest claimed device for that user.

---

License

Proprietary — Copyright © 2025 Norexus AI LLC. All rights reserved.

Use requires a valid license issued by Norexus AI LLC. No redistribution, sublicensing, or modification without written permission. See LICENSE.

Licensing inquiries: jack@norexus.app