Troubleshooting

Start here when a command fails, returns the wrong thing, or does nothing at all.

Caution

Two of these bite hardest. <id> is not the #N you see in listings, and neither nrepo rm nor nrepo merge asks for confirmation — both act the moment you press Enter, and neither can be undone.

The <id> argument is not the number you see

Every listing prints ideas as #42. Every command takes an <id>. They are usually different numbers, because the display number is a counter per account while the ID is unique across the whole database. Only the first account created ever sees them line up.

Passing a display number therefore gives you one of two wrong answers:

nrepo log
# #42 exploring  ⬡ Rewrite auth flow

nrepo show 42
# API error (404): Idea not found      ← 42 is someone else's ID, or no one's
# ...or it prints a completely different idea of yours

Three reliable ways to get a real ID:

# 1. From --json, which carries both
nrepo log --limit 10 --json | jq -r '.[] | "\(.id)\t#\(.number)\t\(.title)"'

# 2. From the web app's URL — neuralrepo.com/ideas/391 → 391
# 3. From the command that created the idea
ID=$(nrepo push "New idea" --json | jq -r '.id')

The CLI’s own output mixes the two conventions, so read #N carefully:

Where	#N means
nrepo log, search, show, status, duplicate list	Display number
nrepo move --ids, nrepo tag add/remove, nrepo rm --json	The ID you passed
nrepo branch first line	Source ID, then the new idea’s number
nrepo duplicate list	Both are numbers; the detection ID is not shown at all

Error output and exit codes

Every failure exits with status 1; success exits 0. Errors go to stderr, so they never contaminate a --json pipeline on stdout.

Situation	Human message	--json code
Not logged in	Not logged in. Run `nrepo login` to authenticate.	auth_required
Key revoked or invalid	Authentication expired. Run `nrepo login` to re-authenticate.	http_401
Feature needs Pro	This feature requires a Pro plan. Upgrade at https://neuralrepo.com/settings	http_403
Any other API failure	API error (404): Idea not found	http_404
No network / DNS / TLS	Network error: <detail>. Check your internet connection and try again.	network_error
Anything else	Raw error	unknown

With --json, the error is one object on stderr:

{ "error": "Idea not found", "code": "http_404", "status": 404 }

if ! OUT=$(nrepo show 391 --json 2>err.json); then
  jq -r '.code' err.json
fi

A few commands validate before calling the API and print a plain message with no code — an unparseable ID, an unknown status, an empty --ids list, or nrepo edit with neither --title nor --body (that one does carry "code": "no_input").

Which commands need Pro

Command	Free-plan behaviour
nrepo link, nrepo unlink, nrepo link --batch	403 — creating and deleting relations is Pro
nrepo key create	403 — key creation is Pro
nrepo duplicate list / dismiss / merge	Always empty: the duplicates endpoint returns no rows below Pro
nrepo search	Works, but only 10 semantic searches a month; after that you get keyword results
nrepo push	Works up to 50 active ideas, then 403 idea_limit_reached
Everything else	Unrestricted

nrepo login itself has no plan check, so the CLI is fully usable on the free plan — it is the individual features above that are gated. nrepo links (reading relations) is not gated either, so system-created connections stay visible.

Bulk operations are not atomic

nrepo move --ids, nrepo tag add, nrepo tag remove, and nrepo link --batch all process their input one entry at a time and report per-entry results. A failure in the middle does not roll back what came before.

Operation	Cap per call	On partial failure
move --ids, tag add/remove	50 IDs	✓/✗ per idea, then N moved, M errors
link --batch	50 links	✓/✗ per link, then N created, M errors

Check the counts, or .errors in --json, rather than the exit status — a batch where every entry failed still exits 0, because the request itself succeeded.

Commands that look like they did nothing

Symptom	Cause
nrepo tag with no arguments prints nothing	The bare form requires both an ID and at least one tag; with neither it exits 0 silently. Use nrepo tag --help.
nrepo search returns no results for words you know are there	Semantic search does not fall back to keyword in the CLI, and a just-captured idea has no embedding yet. See nrepo search.
nrepo links on a fresh branch shows nothing	The parent relation is created by the background queue a second or two later.
nrepo graph --depth 4 shows only three levels	The text tree stops at the second hop. The deeper nodes are in --json.
nrepo duplicate list is always empty	Duplicate detection is Pro-only.
A merged idea vanished from nrepo log	Merging archives the absorbed idea, and archived ideas are excluded from every listing.

Login problems

Symptom	What to do
Login timed out after 120 seconds	The local callback server closed. Re-run nrepo login rather than finishing the browser page.
Browser never opens	The URL is printed in the terminal — paste it manually.
No GitHub account	Browser login is GitHub-only. Use nrepo login --api-key with a key from the dashboard (Pro).
Signed in, but every command says “Not logged in”	Check that ~/.config/neuralrepo/config.json exists and contains an api_key; nrepo logout replaces the file with {}.
Commands work on your machine, not in CI	CI needs its own key: echo "$KEY" | nrepo login --api-key.

Noise in scripted output

The weekly version check prints its notice to stderr, before the command’s own output, so nrepo log --json | jq . is unaffected. To silence it entirely — and skip the outbound call to the npm registry — set NREPO_NO_UPDATE_CHECK=1.

Next Steps

Authentication Both login flows in full, and what each one writes to disk.

Plans & Pricing Every free-plan cap, and what Pro changes on each surface.

API errors The status codes and error bodies behind the CLI's messages.

Installation Version checks, the PATH problem, and the bundled Claude Code skill.