Quick start
From nothing to a signed-in Nexus in three commands.
Install Nova
Nova is an npm package. Install it globally so nova works from any folder.
npm install -g @getnexus/nova
Prefer not to install anything? Run any command with npx @getnexus/nova instead, for example npx @getnexus/nova check.
Install Nexus
Nova downloads the latest Windows installer, verifies it and launches it.
nova install
Sign in
Optional, and only needed for the AI Assistant. Your browser opens, you approve with Google or GitHub, and both Nova and the Nexus app are signed in.
nova login
Later, nova update brings you to the newest version, and nova doctor is the first thing to run if something looks off.
Requirements
- Operating system
- Windows 10 or 11, 64-bit. On ARM64 PCs Nova installs the x64 build, which runs under emulation.
- Node.js
- Version 20 or newer, with npm.
- Internet
- Needed to find releases, download installers and sign in.
- Other systems
- Nova is published for Windows only, because Nexus is Windows-only for now, so npm won't install it on macOS or Linux.
Commands
Run nova --help for the list, or nova <command> --help for one command.
Install & update
Get Nexus onto your PC and keep it current.
Downloads the latest Nexus installer for Windows, verifies it and launches it.
nova install [--passive] [--silent]
- --passive
- Show installer progress but require no interaction. Nova waits for the installer to finish.
- --silent
- Install with no UI at all. Nova waits and reports success or the installer exit code.
- Without a flag, the normal installer window opens and Windows may show a permission (UAC) prompt.
- If Nexus is running, Nova reminds you to close it so the installer can replace its files.
Compares your installed version with the latest release and installs only if the release is newer.
nova update [-f | --force] [--passive] [--silent]
- -f, --force
- Reinstall even if you are already up to date.
- --passive
- Show installer progress, no interaction needed.
- --silent
- Install with no UI at all.
- If Nova cannot detect an installed version, it installs the latest release.
Shows the latest published version, when it was released, and what you have installed.
nova check
Example output:
Latest release: 6.6.4
Installed version: 6.6.3
An update is available. Run `nova update`.
Account
Sign in to Nexus Cloud, the service behind the AI Assistant, and see your allowance.
Signs you in (or up) with Google or GitHub, then signs the installed Nexus app in too.
nova login [-p <google|github>] [--no-browser]
- -p, --provider <provider>
- google or github. Defaults to google.
- --no-browser
- Print the sign-in link instead of opening your browser.
- Requires Nexus to be installed. Run nova install first if it is not.
- See "How sign-in works" below for what happens at each step.
Revokes this CLI's session and removes the saved credentials. If the session was shared with the Nexus app, the app is signed out too.
nova logout
Prints the email of the signed-in account and when it was created.
nova whoami
Shows your Nexus Cloud AI usage: tokens used in the current rolling 5-hour window, when it resets, and tokens used today.
nova usage
- If the service is running in a reduced mode, Nova says so, because limits are lower while it is.
Diagnostics & links
Figure out what is happening, or jump to the right page.
Runs a series of checks on Node.js, your platform, the release feed, Nexus Cloud, the Nexus install and your sign-in.
nova doctor
- Exits with code 1 if any required check fails. Being signed in is optional.
Example output:
✓ Node.js: v22.11.0 (need >= 20)
✓ Platform: Windows 11 (10.0.26100), x64
✓ Release feed: latest is 6.6.4
✓ Nexus Cloud: 92 ms
✓ Nexus installed: 6.6.4
✓ Signed in: you@example.com
✓ Shared with Nexus app: yes
Checks whether Nexus Cloud is healthy and how fast it answers.
nova status [-o | --open]
- -o, --open
- Also open the status page in your browser.
- Exits with code 1 when Nexus Cloud is not operational.
Opens the Nexus downloads and release notes on GitHub.
nova releases
Opens the Nexus website.
nova website
nova version
also: -v, --versionPrints the installed Nova version.
nova version
How sign-in works
nova login signs you in without ever asking for a password in the terminal.
Nova checks Nexus is installed
Sign-in is offered only when the desktop app is on this PC, since the app is what you are signing in to.
A sign-in session starts
Nova creates a random secret on your PC and sends Nexus Cloud only a hash of it. The secret itself stays with Nova and is what later proves the result is meant for you.
Compare the confirmation code
Nova prints a code like A1B2-C3D4 and opens your browser. After you authorize with Google or GitHub, the page asks you to confirm. Only continue if it shows the same code. This stops anyone from tricking you into approving a sign-in you didn't start.
Nova collects the session
Nova waits for up to 10 minutes. You can cancel any time with Ctrl+C.
The app is signed in too
Nova saves its own session, then writes the same one to Windows Credential Manager, where Nexus reads its key. If Nexus is running, restart it to pick up the sign-in.
nova login --provider github --no-browser
Scripts & automation
Nova is built to be run by people and by scripts.
Unattended installs
Use --silent for no UI at all, or --passive to show progress without any prompts. In both cases Nova waits for the installer and returns its result.
nova install --silent
nova update --silent
Exit codes
0 means the command succeeded.1 means it failed, with the reason printed to the error stream. nova status also returns 1 when Nexus Cloud isn't operational, and nova doctor when a required check fails.
# PowerShell
nova status
if ($LASTEXITCODE -ne 0) { Write-Host "Nexus Cloud is having issues" }
Environment
- GITHUB_TOKEN
- Optional. Used for GitHub API requests if Nova ever has to fall back from the release feed, which avoids anonymous rate limits.
Security
What Nova does, and does not do, on your machine.
HTTPS only, GitHub only. Nova downloads installers only from GitHub hosts over HTTPS, and re-checks the address after any redirect.
Checksum verification. The installer's SHA-256 is compared with the digest GitHub publishes for that file. If a release has no published checksum, Nova tells you it couldn't verify the file.
No passwords. Sign-in happens on Google or GitHub. Nova never sees your password for either.
Secure endpoint. Your session key is only ever sent to Nexus Cloud over HTTPS. Nova refuses to run against a non-HTTPS endpoint.
Handed to the app safely. The key is written to Windows Credential Manager, where the Nexus app reads it. It is passed to that step through the environment, never on a command line where other programs could see it.
Where the session lives. Nova keeps its own session in %APPDATA%\nova\credentials.json. Run nova logout to revoke the session on the server and delete that file.
No analytics. Nova has no telemetry. Its requests carry a user-agent with the Nova version, which is how any HTTP client identifies itself.
Your notes are not involved. Nova never opens your Nexus database. For what the Assistant sends to Nexus Cloud, see the Privacy Policy.
Troubleshooting
Start with nova doctor. It tells you which part of your setup is unhappy.
'nova' is not recognized as a command
Nova has to be installed globally to be available everywhere. Run npm install -g @getnexus/nova, then open a new terminal window. You can also run it without installing: npx @getnexus/nova check.
"Nexus isn't installed on this computer" when I run nova login
Sign-in is only offered once the Nexus desktop app is on the PC. Run nova install first, then nova login. Run nova doctor to see whether Nova can detect your install.
Nova is signed in but the Nexus app is not
If Nexus was running during sign-in, restart it so it picks up the new session. nova doctor shows whether the session was shared with the app. If it wasn't, sign in from inside the Nexus app instead.
GitHub rate limit reached
Nova normally reads the same release feed the app updater uses, which has no API limit. When it has to fall back to the GitHub API, GitHub can throttle anonymous requests. Set a GITHUB_TOKEN environment variable and try again, or wait a while.
Checksum mismatch
The downloaded installer didn't match the checksum published for the release, so Nova refused to run it. Try again. If it keeps happening, don't run the file and email support@nexusworkspace.net.
Windows says "Windows protected your PC"
That is Windows SmartScreen, which appears for installers without a paid code-signing certificate. See the FAQ for the steps to continue safely.
Sign-in timed out
Nova waits up to 10 minutes for you to finish in the browser. Run nova login again. If no browser opens, use nova login --no-browser and open the printed link yourself.
The installer can’t replace files
Close Nexus completely (check the system tray) and run the command again.
FAQ
Do I need Nova to use Nexus?
No. Nova is optional. You can download Nexus from the website and Nexus updates itself. Nova is for people who prefer the terminal, or want to script installs and updates.
Is Nova free?
Yes. Nova is free, as is the Nexus desktop app. The cloud Assistant has a usage allowance, which you can check with nova usage.
Does Nova read my notes?
No. Nova never opens your Nexus database. It installs and updates the app, handles sign-in, and reads your account details and usage from Nexus Cloud.
Does it work on macOS or Linux?
Not yet. Nexus is available for Windows 10 and 11 only, and Nova is published for Windows only.
How is nova update different from the in-app updater?
They read the same release feed. The in-app updater runs automatically while Nexus is open. nova update is for when you want to check or install from a terminal, or inside a script.
How do I remove Nova?
Run npm uninstall -g @getnexus/nova. This removes only the CLI. Nexus and your notes are not touched. Run nova logout first if you want to revoke its session.
Still stuck?
Email support@nexusworkspace.net and include the output of nova doctor. You can also check whether Nexus Cloud is up on the status page.