nyx CLI reference

nyx is the command-line client for nyxory. It manages projects and apps from your terminal. Many of the same operations are also exposed to a coding agent — Claude Code, Cursor, Codex — as nyx_* MCP tools it drives to deploy on your behalf (see the MCP tools reference). Every command supports --json for scripting and CI.

Global flags

These apply to every command.

Flag	Description
--json	Emit one JSON envelope per invocation (stdout on success, stderr on error).
--context <name>	Override the active context for this invocation. Also settable via the NYX_CONTEXT environment variable.
--version	Print the CLI version.

The NYX_TOKEN environment variable supplies a bearer token in place of the OS keyring — useful for CI.

Note: wherever a command takes a <project> argument, it accepts three forms — the full namespace (nyx-abc123), the bare ID (abc123), or the human display label. An ambiguous label returns a project_ambiguous error.

nyx login

nyx login [--api <url>] [--console <url>] [--hostname <name>] [--context <name>]

Signs in via a browser using OAuth 2.0 loopback redirect (RFC 8252) and stores a long-lived API token in the OS keyring (Keychain on macOS, libsecret on Linux, Wincred on Windows), keyed by context. Sets the target context active on success.

• --api <url> — API base URL. Defaults to the target context’s stored URL, or the production API.
• --console <url> — Console base URL. Same default rule as --api.
• --hostname <name> — Name recorded for the token. Defaults to the machine’s hostname.
• --context <name> — Context to log into and activate. Defaults to the current active context, or prod on a fresh install.

Fresh installs come pre-seeded with prod and dev contexts, so nyx login and nyx login --context dev need no --api/--console.

Note: nyx login opens a browser and blocks up to 5 minutes waiting for the callback — it isn’t headless-safe. For CI or a headless machine, set the NYX_TOKEN environment variable instead (bypasses login entirely), or mint a token on a logged-in machine with nyx token create and ship it via NYX_TOKEN.

nyx setup

nyx setup [--all] [--client <list>] [--skip-login] [--no-auto-approve]

Wires every MCP-capable AI client on the machine (Claude Code, Cursor, Codex, VS Code, Claude Desktop) to the nyxory MCP endpoint (<api_url>/mcp) in one pass, signing in first if no token is stored. Each client connects directly over HTTP and performs its own OAuth — the CLI never mints or embeds a token.

• --all — wire every detected client without prompting.
• --client <a,b,...> — wire only the listed clients (claude, cursor, codex, vscode, claude-desktop), even if undetected.
• --skip-login — fail instead of starting the browser login when no token is stored.
• --no-auto-approve — don’t pre-approve nyxory tool calls in the wired clients.

Interactive by default: prompts a checklist of detected clients to wire, and asks Claude Code specifically whether to use the web or local install. Pass --all (or --client ...) together with --json or a non-TTY shell to skip every prompt; without --all in that mode the command errors with confirmation_required. Claude Desktop always needs a manual step — nyx setup prints the connectors URL to paste into claude.ai, since there’s no local config file to write.

Re-running is idempotent: it overwrites the nyxory registration in place and preserves every other MCP server already configured in each client.

nyx account

nyx account <subcommand>

Account-level subscription and resource pool. One subcommand today.

nyx account ram

nyx account ram

Shows the account-wide RAM pool: plan baseline, extra packs, and how much is already allocated across all projects. Run it before deciding whether a project’s allocation (nyx project ram) can be bumped. No flags beyond global.

Output: plan / plan ID, status, baseline RAM (or “unlimited” on Enterprise), RAM packs (2 GB each), account pool total, storage cap, add-ons, and an upgrade URL when one applies.

nyx app

nyx app <subcommand>

Read-only inspection of deployed apps. Every subcommand here only reads state — apps are created by your coding agent calling the nyx_brain MCP tool, not by this CLI.

nyx app list

nyx app list (alias: nyx app ls)

Lists apps (App custom resources, not raw Kubernetes Deployments) across every project you own. No flags beyond global.

nyx app list --json | jq '.data.items[] | select(.phase != "Available")'

nyx app get

nyx app get <project> <name>

Shows one app’s detail: phase, replica counts, image, public ingress domains. Both arguments are required.

nyx app deployments

nyx app deployments <project> <name> (alias: nyx app rollouts)

Shows rollout history, one row per ReplicaSet/revision.

nyx app logs

nyx app logs <project> <name> [--tail <n>] [--since <duration>] [--container <name>] [--pod <name>] [--grep <text>] [--previous]

Tails an app’s container logs directly, without a kubectl hop. Lines are RFC3339-timestamped; a clean message prints if no pod is running.

Flag	Default	Description
--tail	200	Max lines to return
--since	—	Only lines newer than this relative duration (e.g. 15m, 1h)
--container	pod’s first container	Which container to read
--pod	newest replica	Which pod to read
--grep	—	Case-sensitive substring filter
--previous	false	Read the previous, crashed container’s logs

nyx app verify

nyx app verify <project> <name> [--timeout <seconds>]

Probes an app’s public ingress domains with an HTTP GET and reports status + latency per host. A probe counts as “ok” below status 500. Exits non-zero if any probe is unhealthy, so it chains in CI:

nyx app verify foo bar && deploy-prod

• --timeout <seconds> — per-probe HTTP timeout. Default 10.

nyx brain

nyx brain <repo-url> [--project <project>] [--agent-briefing <text>]

Hidden command — it doesn’t show in nyx --help. This is the CLI mirror of the nyx_brain MCP tool your coding agent calls to fetch a deploy cookbook: a POST to /api/brain/deploy returns markdown guidance plus a scan of the repo and the target project’s current state. The agent reads the cookbook and drives the nyx_* primitives itself — there’s no in-pod planner and no streaming.

Note: humans normally don’t type this command directly; it exists for local debugging of what the agent sees.

• --project <project> — project to fetch the cookbook for. Falls back to the .nyxrc found by walking up from the current directory; if left empty and unresolved, the server returns a generic cookbook.
• --agent-briefing <text> — free-form context (stack, components, deploy intent, env vars). Pass - to read the briefing from stdin.

.nyxrc — drop a TOML file with project = "widget" at a repo’s root to set the default --project. A per-app .nyxrc in a monorepo shadows the top-level one.

nyx context

nyx context <subcommand>

Manages which nyxory stack (prod, dev, local-stack, or a custom one) the CLI talks to. A context bundles an API URL, a console URL, an identity, and a bearer token. Fresh installs come pre-seeded with prod (active) and dev.

nyx context list

nyx context list

Lists every configured context; the active one is marked *. No flags beyond global.

nyx context use

nyx context use <name>

Sets <name> as the active context, persisted to config.toml. Errors context_not_found if the name isn’t configured.

nyx context show

nyx context show

Prints the resolved active context — name, API URL, user email, user ID, hostname, whether a token is present. The quick answer to “which stack am I on?“

nyx context remove

nyx context remove <name> (alias: nyx context rm)

Deletes the named context from the config and its OS-keyring token entry. Idempotent — a missing keyring entry isn’t an error. If the removed context was active, the active context reverts to prod.

Note: unlike project delete, domain remove, and token delete, this command has no --yes flag and never prompts — it deletes immediately.

nyx claude

nyx claude <install|uninstall>

Wires or unwires Claude Code to the nyxory MCP via claude mcp add --transport http — a direct remote endpoint; Claude Code performs its own OAuth, no token is embedded.

nyx claude install

nyx claude install [--scope user|local] [--no-auto-approve]

• --scope — user (all projects) or local (this project only). Default user.
• --no-auto-approve — don’t pre-approve nyxory tool calls.

Requires the claude CLI on PATH (errors claude_install_failed otherwise). Also strips legacy artifacts from older nyx versions — the old @nyxory subagent file and a legacy SessionStart hook entry, both superseded by the MCP server’s own init instructions. Pre-approval writes a wildcard allow rule into Claude Code’s settings.json; destructive tools stay server-gated regardless.

nyx claude uninstall

nyx claude uninstall [--scope user|local]

• --scope — default user.

Runs claude mcp remove <name> --scope <scope>, strips the permission rules, and removes the legacy subagent file plus (user scope only) the legacy hook. “Not registered” is treated as a clean, non-error outcome.

nyx codex

nyx codex <install|uninstall>

Wires or unwires Codex CLI to the nyxory MCP by editing ~/.codex/config.toml’s [mcp_servers.nyxory] table directly — other servers, settings, and comments are preserved.

nyx codex install

nyx codex install [--no-auto-approve]

• --no-auto-approve — don’t pre-approve nyxory tool calls.

On a TTY, immediately triggers Codex’s own browser OAuth (codex mcp login), since Codex doesn’t prompt for it on its own. Off a TTY, prints the manual codex mcp login nyxory instruction instead.

nyx codex uninstall

nyx codex uninstall

No flags beyond global. Reports whether an entry was removed.

nyx cursor

nyx cursor <install|uninstall>

Wires or unwires Cursor to the nyxory MCP by editing ~/.cursor/mcp.json (or ./.cursor/mcp.json with --scope local) directly — there’s no cursor mcp add CLI to shell out to.

nyx cursor install

nyx cursor install [--scope user|local] [--no-auto-approve]

• --scope — user (~/.cursor/mcp.json, all projects) or local (./.cursor/mcp.json). Default user.
• --no-auto-approve — don’t pre-approve nyxory tool calls.

Best-effort fetches the MCP tool catalog to populate Cursor’s autoApprove list.

nyx cursor uninstall

nyx cursor uninstall [--scope user|local]

• --scope — default user.

nyx vscode

nyx vscode <install|uninstall>

Wires or unwires VS Code (GitHub Copilot agent mode) to the nyxory MCP by writing the user-profile mcp.json directly.

nyx vscode install

nyx vscode install

No command-specific flags. VS Code has no per-server approval mechanism yet, so there’s no --no-auto-approve on this command.

nyx vscode uninstall

nyx vscode uninstall

No command-specific flags.

nyx domain

nyx domain <add|list|status|remove>

Manages custom hostnames on apps (HTTPS via cert-manager and Traefik). A domain moves through RoutingPending → CertPending → Ready; in --json output, next.action tells you which state to wait for (wait_routing, wait_cert, ready, or failed).

nyx domain add

nyx domain add <hostname> --app <name> [--project <project>] [--service-name <name>] [--service-port <port>] [--path-prefix <path>]

Registers a custom hostname against an app; the response includes the CNAME (and, if applicable, an apex A record) to point DNS at. <hostname> must be a real RFC-1123 subdomain — no wildcards.

Flag	Required	Description
--app <name>	yes	App to route the hostname to
--project <project>	no	Project owning the app; needed if the app name is ambiguous across projects
--service-name <name>	no	Override which Service the Ingress targets (default: the app’s single Service, or one labeled nyxory.com/primary-service)
--service-port <port>	no	Override the Service port (default: the Service’s first port)
--path-prefix <path>	no	Ingress path prefix. Default /

nyx domain list

nyx domain list [--project <project>] [--app <name>] (alias: nyx domain ls)

Lists custom and auto-generated domains. Without filters, flattens across every project the token can see.

nyx domain status

nyx domain status <hostname> [--watch] [--timeout <duration>]

Shows a domain’s phase, conditions, DNS target, and next-action hint.

• --watch — poll every 5 seconds and exit once the domain reaches Ready (or times out / fails).
• --timeout <duration> — watch deadline (e.g. 5m, 30s). Default 10m. Ignored without --watch.

--watch blocks with a spinner but is headless-safe — it honors --json and never opens a TTY prompt. A missed deadline exits non-zero with a timeout error code.

nyx domain remove

nyx domain remove <hostname> [--yes|-y] (aliases: rm, delete)

Deletes a domain — cascades the Ingress, Certificate, and TLS Secret immediately via the operator’s finalizer.

• --yes / -y — skip the confirmation prompt.

Without --yes on a TTY, prompts for a typed yes. In a non-TTY shell or with --json and no --yes, the command exits non-zero with confirmation_required rather than proceeding or silently skipping.

nyx project

nyx project <list|add|rename|delete|state|ram>

Manages projects — the Kubernetes namespaces apps deploy into.

nyx project list

nyx project list (alias: nyx project ls)

Lists every project. No flags beyond global.

nyx project add

nyx project add <name> [--label "..."] [--no-wait]

Creates a new project. <name> becomes the display label unless --label overrides it; the server assigns a stable nyx-<id> namespace, which is the ID every other command expects.

• --label <text> — free-form display name. Defaults to the <name> argument.
• --no-wait — return immediately instead of polling (up to 60 seconds) until the project reaches phase=Ready.

Polls with a terminal spinner by default; use --no-wait or --json for scripted use — --json returns immediately with a next: poll_project hint.

nyx project rename

nyx project rename <id> <label>

Renames a project’s display label. The ID (namespace) itself is immutable. No flags beyond global.

nyx project delete

nyx project delete <id> [--yes|-y] (aliases: rm, remove)

Destructive: deletes every workload, secret, ingress, and ConfigMap in the project. Unrecoverable.

• --yes / -y — skip the confirmation prompt.

Same confirmation-gate pattern as domain remove: a TTY without --yes prompts for a typed yes; a non-TTY shell or --json without --yes exits non-zero with confirmation_required.

nyx project state

nyx project state <project>

Shows a project’s RAM allocation, current pod reservations, and remaining account-pool headroom. Check this before bumping an allocation with nyx project ram. No flags beyond global.

Fields returned: allocatedMb, reservedMb, reservedCpuMilli, floorMb, stepMb (256), poolMb (-1 = unlimited), totalAllocatedMb, remainingPoolMb (-1 = unlimited).

nyx project ram

nyx project ram <project> --mb <n>

Sets a project’s RAM allocation in MB, rounded up to the next 256 MB step. --mb 0 parks the project.

• --mb <n> — required. RAM allocation in MB.

Failure modes are structured error codes: below_reserved / below_reserved_cpu (running pods already exceed the new value — shrink workloads first, or allocate at least floorMb) and ram_pool_exhausted (the account-tier pool is full across sibling projects — shrink another project or upgrade).

nyx token

nyx token <list|create|delete>

Manages long-lived API tokens for service accounts, CI, additional machines, or rotating a leaked token. nyx login already issues one for the current machine.

nyx token list

nyx token list (alias: nyx token ls)

Lists tokens by ID, name, last-used time, and expiry. Plaintext is never returned by the API. No flags beyond global.

nyx token create

nyx token create <name> [--expires <RFC3339>]

Issues a new token. The plaintext is shown exactly once — the server stores only a SHA-256 hash, so a lost token has to be deleted and recreated.

• --expires <RFC3339> — optional expiry timestamp.

nyx token create ci-runner --json | jq -r '.data.token'

nyx token delete

nyx token delete <id> [--yes|-y] (aliases: rm, remove, revoke)

Revokes a token by ID — it stops working on the very next request.

• --yes / -y — skip the confirmation prompt.

Same confirmation-gate pattern as project delete and domain remove.

nyx uninstall

nyx uninstall [--all] [--client <list>] [--purge]

Mirror image of nyx setup — removes the nyxory MCP registration from every supported client (Claude Code, Cursor, Codex, VS Code) in one pass. Only the nyxory entry is touched. Claude Desktop has no config file nyx can safely edit; the command prints manual removal steps (Settings → Extensions/Connectors) instead.

• --all — remove from every supported client without prompting.
• --client <a,b,...> — remove only from the listed clients (claude, cursor, codex, vscode).
• --purge — also delete stored tokens (OS keyring and config-file fallback) and ~/.config/nyx itself, then print binary-removal steps for your package manager. Server-side tokens stay valid until revoked separately in the console.

Interactive by default — asks [y/N] to confirm removing from all clients — unless --all or --client is passed. A non-TTY shell or --json without either flag exits non-zero with confirmation_required.

nyx update

nyx update [--check] [--force]

Fetches the latest nyx release from the public nyxory/homebrew-tap GitHub repo, verifies its SHA-256 against checksums.txt, and replaces the running binary in place. Idempotent — a no-op if you’re already on the latest version, unless --force is set.

• --check — report the current vs. latest version without replacing the binary.
• --force — reinstall even if already on the latest version.

Refuses to run if the binary is managed by Homebrew, Scoop, or winget — pointing you to that package manager’s own upgrade command instead (error codes brew_managed / scoop_managed / winget_managed). Also refuses draft or prerelease releases (update_unstable_release).