nrepo link / unlink / links

nrepo link <source-id> <target-id> [options]
nrepo link --batch                          # read a JSON array from stdin
nrepo unlink <source-id> <target-id> [options]
nrepo links <id> [options]

Caution

Creating and deleting relations is a Pro feature. On the free plan nrepo link and nrepo unlink fail with This feature requires a Pro plan. Upgrade at https://neuralrepo.com/settings. Reading them with nrepo links works on any plan, so system-created relations — duplicates, connections, branch parents — are still visible.

nrepo link

Flag	Type	Default	Description
--type <type>	string	related	One of related, blocks, inspires, supersedes, parent.
--note <note>	string	(none)	A note on the relation. Truncated to 500 characters.
--force	boolean	false	Bypass cycle detection — for supersedes only, see below.
--batch	boolean	false	Bulk mode: read a JSON array of links from stdin.
--json	boolean	false	Output as JSON.
--human	boolean	—	Force human-readable output. Wins over --json.

# A plain association
nrepo link 391 402

# A dependency, with a note
nrepo link 391 402 --type blocks --note "Dark mode depends on the theme system"

✓ Linked #391 → #402 (blocks)
  Note: Dark mode depends on the theme system

duplicate is not accepted here even though it is a real relation type — only duplicate detection creates those:

Invalid type "duplicate". Must be one of: related, parent, blocks, inspires, supersedes

Relation types

Type	Meaning	Direction
related	General association	Symmetrical in display
blocks	Source blocks progress on the target	Directed
inspires	Source inspired the target	Directed
supersedes	Source replaces the target	Directed
parent	Source is a child/variant of the target	Directed
duplicate	Two captures of the same idea	Created only by duplicate detection

Cycle detection

Cycles are checked only for the three types where a loop would be meaningless. The check walks existing relations of the same type outward from the target, up to 50 hops.

Type	Checked	--force
blocks	Yes — hard	Ignored. The link is refused whatever you pass.
parent	Yes — hard	Ignored. The link is refused whatever you pass.
supersedes	Yes — soft	Bypasses the check.
related, inspires	No	Not applicable.

This would create a circular blocking chain: #391 → #402 → #391

Caution

On a refused parent cycle the CLI adds “Use --force to bypass this check.” Re-running with --force fails identically — parent cycles are hard-blocked server-side and only supersedes can be forced. Restructure the chain instead.

An existing relation between the same pair in the same direction also fails, with Relation already exists. In --json mode that error is reported with "code": "cycle_detected" even though no cycle was involved — match on the message, not the code.

Bulk mode

--batch reads a JSON array from stdin, so you can create many relations in one request:

echo '[
  {"source_idea_id": 391, "target_idea_id": 402, "relation_type": "blocks", "note": "theme first"},
  {"source_idea_id": 391, "target_idea_id": 417}
]' | nrepo link --batch

✓ Linked #391 → #402 (blocks)
✗ #391 → #417: Target idea 417 not found

1 created, 1 errors

Detail	Value
Links per call	50 maximum
Fields	source_idea_id and target_idea_id required; relation_type defaults to related; note optional
Atomicity	None — one result per link, failures do not roll back the rest
Cycles	Reported as a per-link error, not as a command failure

Empty input, an empty array, or invalid JSON exits 1 with a message before anything is sent.

nrepo unlink

nrepo unlink 391 402
# ✓ Unlinked #391 ↔ #402

Finds the relation between the two ideas in either direction and deletes it. If there are several between the same pair, it removes the first one it finds — outgoing before incoming. With no relation at all:

No link found between #391 and #402. Run nrepo links 391 to see existing links.

nrepo links

Flag	Type	Default	Description
--type <type>	string	(all)	Show only this relation type.
--json	boolean	false	Output as JSON.
--human	boolean	—	Force human-readable output. Wins over --json.

nrepo links 391

Links for #42 "Rewrite auth flow":

  Blocks →
    #43  Add dark mode and a theme picker [exploring] — theme first

  Related ↔
    #18  Session cookie cleanup [captured]

  Child of ←
    #7  Auth overhaul epic [shipped]

Relations are grouped by type and direction, and each type is labelled from the perspective of the idea you asked about — Blocks outgoing versus Blocked by incoming, Parent of versus Child of. related and duplicate are symmetrical, so they are listed once rather than twice.

--json returns { "outgoing": [...], "incoming": [...] }, each entry carrying the relation’s own id, its type, note, score, and the other idea’s idea_id, idea_number, idea_title, and idea_status.

Next Steps

nrepo graph Follow these relations outward several hops instead of one.

Idea Relations What each type means, and which relations the system creates on its own.

nrepo branch Create a parent relation as a side effect of forking an idea.

Mind Map See the same graph laid out visually in the web app.