Authentication

Both login methods end in the same place: an nrp_ API key in ~/.config/neuralrepo/config.json, sent as an X-API-Key header on every request.

Method	Best for	Command	Plan required
Browser	Interactive use on a workstation	nrepo login	Any — including free
API key	CI, scripts, headless machines	nrepo login --api-key	Pro, to create the key

Browser login

nrepo login

1. The CLI starts a one-shot HTTP server on a random local port between 49152 and 65535 and prints the sign-in URL:

   Starting local auth server...
   
   Open this URL to log in:
   
     https://neuralrepo.com/auth/cli?callback=http%3A%2F%2Flocalhost%3A51234%2Fcallback
   
   Waiting for authentication...

2. It also tries to open that URL for you (open on macOS, start on Windows, xdg-open elsewhere). If nothing opens, paste the printed URL yourself.

3. You sign in with GitHub. NeuralRepo matches the account by your GitHub verified primary email, so this works whether or not you originally signed up through GitHub.

4. The server redirects back to the local callback with a freshly minted key. The CLI saves it and prints:

   ✔ Logged in as Alice (pro)

Caution

The local server gives up after 120 seconds. If the browser sign-in takes longer than that, the CLI fails with Login timed out after 120 seconds — re-run nrepo login rather than finishing the browser flow, because the callback has nowhere left to land.

Two consequences of that flow are worth knowing:

• nrepo login mints a real API key, not a session token. It is labelled CLI (auto-generated) and appears in nrepo key list alongside keys you made yourself.
• No plan check runs on that path. Browser login works on the free plan even though creating a key from the dashboard or with nrepo key create is a Pro feature.

nrepo login always authenticates through GitHub — it sends no provider preference, and the endpoint’s default is GitHub. Google sign-in is not part of this flow at all.

API key login

--api-key is a bare flag. It prompts; it does not take the key as an argument.

Interactive

nrepo login --api-key
# Enter your API key: nrp_...
# ✔ Logged in as Alice (pro)

Piped

echo "$NEURALREPO_API_KEY" | nrepo login --api-key

The prompt reads a single line from stdin, so piping and here-strings both work.

The key is verified against GET /user/me before it is saved. A bad key fails with Invalid API key. Generate one at https://neuralrepo.com/settings and exit status 1.

Keys use the format nrp_ followed by 64 hexadecimal characters. Create one with nrepo key create or in Settings ▸ API Keys on the web dashboard; both require Pro.

Tip

Signed in with Google or a magic link, on the free plan? Browser login still works — GitHub matches you by verified primary email. If you have no GitHub account at all, you need Pro to mint a key, because that is the only other way in.

Configuration file

~/.config/neuralrepo/config.json

Field	Description
api_url	API base URL. Defaults to https://neuralrepo.com/api/v1 when absent
api_key	The nrp_ key, in plain text
user_id	Your account identifier, recorded at login
auth_method	browser or api-key — recorded at login and never read again

Caution

The file is plain text with no special permissions. Treat it like an SSH private key: never commit it, never bake it into an image.

Output format

Every command prints human-readable output by default, on both login methods. Pass --json for machine-parseable output, and --human to force text back on if something upstream in your tooling sets --json. --human wins when both are given.

Caution

nrepo login --api-key finishes by printing “Output defaults to JSON. Use --human for human-readable output.” That line is wrong, and has been since the flag was added: auth_method is written to the config file and never read, so output is human-readable until you pass --json. Script accordingly.

Headless and CI

export NREPO_NO_UPDATE_CHECK=1
echo "$NEURALREPO_API_KEY" | nrepo login --api-key
nrepo push "Nightly build failed on $(git rev-parse --short HEAD)" \
  --body "$(tail -50 build.log)" --tag ci --json

Give CI its own key so you can revoke it independently, and check the exit status: every failure exits 1, and with --json the error is a single JSON object on stderr.

Logging out

nrepo logout
# Logged out.

Caution

nrepo logout overwrites the local config file with {}. It does not revoke the key on the server — anyone holding a copy can still use it. To invalidate it, run nrepo key revoke first, or delete the key in the web dashboard.

Next Steps

nrepo login / logout / whoami The full flag and output reference for the three authentication commands.

nrepo key Create, list, and revoke the API keys the CLI authenticates with.

Troubleshooting What an expired session, a Pro gate, and a network failure look like on the terminal.

API authentication The same key, used directly against the REST API from any language.