sudocode add-ref - sudocode

Syntax

sudocode add-ref <entity-id> <reference-id> [options]

Or via entity-specific commands:

sudocode spec add-ref <entity-id> <reference-id> [options]
sudocode issue add-ref <entity-id> <reference-id> [options]

Description

The add-ref command inserts an inline cross-reference into a spec or issue’s markdown content using Obsidian-style [[ID]] syntax. This is useful for:

Adding references programmatically via CLI or scripts
Precisely controlling reference placement
Optionally creating relationships alongside references
Maintaining clean, version-controlled markdown

When you add a reference:

The markdown file is updated with [[REFERENCE-ID]] syntax
The content is synced to the database
Changes are exported to JSONL
An optional typed relationship can be created simultaneously

You can also add references manually by editing markdown files directly. The add-ref command is for programmatic insertion.

Arguments

entity-id

string

required

The entity to add the reference toExample: SPEC-001 or ISSUE-001This is where the reference will be inserted (the markdown file that will be modified).

reference-id

string

required

The entity being referencedExample: ISSUE-042 or SPEC-010This is what you’re referencing (the ID that will appear in [[ID]] syntax).

Options

-l, --line

number

Insert at specific line numberExample: --line 15The reference is inserted at (or after/before) this line number. Use --position to control before/after.Note: You must specify either --line or --text, but not both.

-t, --text

string

Search for text to insert nearExample: --text "Requirements:"Searches for this text in the content and inserts the reference near it. Use --position to control before/after.Note: You must specify either --line or --text, but not both.

--position

string

default:"after"

Position relative to line or textExample: --position before or --position afterControls whether the reference is inserted before or after the specified line/text.

--display

string

Custom display text for the linkExample: --display "OAuth Implementation"Creates a reference with custom text: [[ISSUE-042|OAuth Implementation]]Without this, the reference is just [[ISSUE-042]].

--type

string

Create a typed relationship alongside the referenceExample: --type implementsAutomatically creates a relationship of the specified type when adding the reference. Valid types: blocks, implements, depends-on, references, related, discovered-from.

--format

string

default:"inline"

Format style: inline or newlineExample: --format newline

inline - Adds reference on the same line as the insertion point
newline - Adds reference on a new line

Examples

Insert by Line Number

Add reference at line 15:

sudocode add-ref SPEC-001 ISSUE-042 --line 15

Expected output

✓ Added reference to SPEC-001
  Reference: [[ISSUE-042]]
  Location: line 15 (after)
  Format: inline

Before (line 15):

This is some content.

After (line 15):

This is some content. [[ISSUE-042]]

Insert by Text Search

Add reference after “Requirements:” heading:

sudocode add-ref SPEC-001 ISSUE-042 --text "Requirements:" --position after

Expected output

✓ Added reference to SPEC-001
  Reference: [[ISSUE-042]]
  Location: after "Requirements:"
  Format: inline

Before:

## Requirements:
This section lists requirements.

After:

## Requirements:
[[ISSUE-042]] This section lists requirements.

Insert with Custom Display Text

Add reference with readable text:

sudocode add-ref SPEC-001 ISSUE-042 \
  --line 20 \
  --display "OAuth Implementation"

Expected output

✓ Added reference to SPEC-001
  Reference: [[ISSUE-042|OAuth Implementation]]
  Location: line 20 (after)
  Format: inline

Creates: [[ISSUE-042|OAuth Implementation]]

Insert with Relationship Type

Add reference and create typed relationship:

sudocode add-ref SPEC-001 ISSUE-042 \
  --text "Implementation" \
  --type implements

Expected output

✓ Added reference to SPEC-001
  Reference: [[ISSUE-042]]
  Type: implements
  Location: after "Implementation"
  Format: inline

This both:

Adds [[ISSUE-042]] to the markdown
Creates an implements relationship between ISSUE-042 and SPEC-001

Insert on New Line

Add reference on its own line:

sudocode add-ref SPEC-001 ISSUE-042 \
  --line 10 \
  --format newline

Expected output

✓ Added reference to SPEC-001
  Reference: [[ISSUE-042]]
  Location: line 10 (after)
  Format: newline

Before:

Some content on line 10.

After:

Some content on line 10.
[[ISSUE-042]]

Insert Before Text

Add reference before a specific location:

sudocode add-ref SPEC-001 ISSUE-042 \
  --text "## Design Decisions" \
  --position before

Expected output

✓ Added reference to SPEC-001
  Reference: [[ISSUE-042]]
  Location: after "## Design Decisions"
  Format: inline

Before:

## Design Decisions
Content here.

After:

[[ISSUE-042]]
## Design Decisions
Content here.

Complete Example

Add reference with all options:

sudocode add-ref SPEC-001 ISSUE-042 \
  --line 25 \
  --display "See OAuth implementation" \
  --type implements \
  --format newline \
  --position after

Expected output

✓ Added reference to SPEC-001
  Reference: [[ISSUE-042|See OAuth implementation]]
  Type: implements
  Location: line 25 (after)
  Format: newline

JSON Output

Get machine-readable output:

sudocode --json add-ref SPEC-001 ISSUE-042 --line 15

JSON output

{
  "entity_id": "SPEC-001",
  "reference_id": "ISSUE-042",
  "location": "line 15",
  "success": true
}

Reference Syntax

The command creates Obsidian-style wiki links:

Basic Reference

--line 10

Creates: [[ISSUE-042]]

With Display Text

--line 10 --display "OAuth Implementation"

Creates: [[ISSUE-042|OAuth Implementation]]

With Relationship Type

--line 10 --type implements

Creates: [[ISSUE-042]] AND creates implements relationship

The relationship type is not visible in the markdown - it creates a separate relationship in the database.

Line vs Text Insertion

Using —line (Precise Positioning)

sudocode add-ref SPEC-001 ISSUE-042 --line 15

Advantages:

Exact positioning
No ambiguity
Fast execution

Disadvantages:

Line numbers change as content is edited
Need to know exact line number

Using —text (Content-Based Positioning)

sudocode add-ref SPEC-001 ISSUE-042 --text "Requirements:"

Advantages:

Based on stable content
More maintainable
Better for headings/sections

Disadvantages:

Requires exact text match
May fail if text changes

You must specify either --line or --text, but not both. Specifying both will result in an error.

Common Workflows

Adding Implementation References to Spec

Create issues from spec

sudocode issue create "Implement login"
sudocode issue create "Implement registration"

Add references to spec

sudocode add-ref SPEC-001 ISSUE-001 \
  --text "Requirements:" \
  --type implements

sudocode add-ref SPEC-001 ISSUE-002 \
  --text "Requirements:" \
  --type implements

Verify in spec

sudocode spec show SPEC-001

Building Linked Specifications

Create parent spec

sudocode spec create "Authentication System"

Create child specs

sudocode spec create "OAuth 2.0 Flow" --parent SPEC-001
sudocode spec create "Session Management" --parent SPEC-001

Add cross-references

sudocode add-ref SPEC-001 SPEC-002 \
  --text "OAuth" \
  --display "See OAuth spec" \
  --type references

sudocode add-ref SPEC-001 SPEC-003 \
  --text "Session" \
  --display "See Session spec" \
  --type references

Scripted Reference Addition

Add references programmatically:

# Add all open issues to a spec's implementation section
for issue_id in $(sudocode --json issue list --status open | jq -r '.[] | .id'); do
  sudocode add-ref SPEC-001 "$issue_id" \
    --text "## Implementation" \
    --type implements \
    --format newline
done

Manual Alternative

You can also add references manually by editing markdown files:

# Edit the file directly
vim .sudocode/specs/authentication-system.md

Add references using Obsidian syntax:

## Requirements

1. Support OAuth 2.0 [[ISSUE-001]]
2. Session management [[ISSUE-002]]

See also [[SPEC-010]] for API patterns.

Then sync changes:

sudocode sync

Manual editing gives you full control over placement and formatting. Use add-ref for programmatic automation.

Difference from `link` Command

add-ref

Inline references in markdown

Modifies markdown content
Visible as [[ID]] in files
Can include display text
Optional relationship creation
Good for documentation

link

Database relationships

Creates typed relationship
Not visible in markdown
Required relationship type
Bidirectional tracking
Good for dependency modeling

When to use each:

add-ref: When you want the reference visible in markdown for human readers
link: When you want to model dependencies and relationships for graph queries

Best practice: Use both together:

sudocode add-ref SPEC-001 ISSUE-001 --text "## Implementation" --type implements

This adds the reference to markdown AND creates the relationship in the database.

Common Questions

Can I add multiple references at once?

No, add-ref processes one reference at a time. For bulk additions, use shell scripting:

for issue in ISSUE-001 ISSUE-002 ISSUE-003; do
  sudocode add-ref SPEC-001 "$issue" --line 10 --format newline
done

What if the text I'm searching for doesn't exist?

The command will error with “Text not found”. Ensure the search text exactly matches what’s in the file (case-sensitive).

Can I remove a reference?

There’s no remove-ref command. To remove references:

Edit the markdown file directly
Remove the [[ID]] syntax
Run sudocode sync

Does this work with archived entities?

Yes, you can add references to archived specs or issues, though they’ll be hidden from default listings.

What happens if I add the same reference twice?

The command will add the reference each time you run it. You can end up with duplicate references in the markdown. Always check before adding.

Can I use this with non-existent entities?

No, both entity_id and reference_id must exist in the database. The command validates existence before adding the reference.

Troubleshooting

Error: Either --line or --text must be specified

Cause: You didn’t provide a location for insertionSolution: Specify one location method:

sudocode add-ref SPEC-001 ISSUE-001 --line 15
# OR
sudocode add-ref SPEC-001 ISSUE-001 --text "Requirements:"

Error: Cannot specify both --line and --text

Cause: You provided both location methodsSolution: Choose only one:

# Use line only
sudocode add-ref SPEC-001 ISSUE-001 --line 15

# OR use text only
sudocode add-ref SPEC-001 ISSUE-001 --text "Requirements:"

Error: Entity not found

Cause: The entity_id doesn’t existSolution: Verify the ID:

sudocode spec list
sudocode issue list

Error: File not found

Cause: The markdown file doesn’t exist for the entitySolution: Sync to create markdown files:

sudocode sync

Error: Text not found

Cause: The search text doesn’t exist in the fileSolution:

Check for exact match (case-sensitive)
View the file to verify text:
sudocode spec show SPEC-001
Use different search text or switch to --line

Error: Invalid line number

Cause: Line number is less than 1 or not a numberSolution: Use a valid positive integer:

sudocode add-ref SPEC-001 ISSUE-001 --line 10

Error: Line number out of bounds

Cause: The line number is greater than the number of lines in the fileSolution: Check the file length:

wc -l .sudocode/specs/authentication-system.md

Use a valid line number within range.

link

Create typed relationships

spec show

View spec content

issue show

View issue content

sync

Sync markdown files

Next Steps

Create entities

sudocode spec create "My Feature"
sudocode issue create "Implement X"

Add references

sudocode add-ref SPEC-001 ISSUE-001 --line 10 --type implements

View the result

sudocode spec show SPEC-001
# or view markdown file
cat .sudocode/specs/my-feature.md

Verify relationships

sudocode spec show SPEC-001
# Check "Incoming Relationships" section

Cross-References in Markdown

Learn more about using Obsidian-style links in sudocode

​Syntax

​Description

​Arguments

​Options

​Examples

​Insert by Line Number

​Insert by Text Search

​Insert with Custom Display Text

​Insert with Relationship Type

​Insert on New Line

​Insert Before Text

​Complete Example

​JSON Output

​Reference Syntax

​Basic Reference

​With Display Text

​With Relationship Type

​Line vs Text Insertion

​Using —line (Precise Positioning)

​Using —text (Content-Based Positioning)

​Common Workflows

​Adding Implementation References to Spec

​Building Linked Specifications

​Scripted Reference Addition

​Manual Alternative

​Difference from link Command

add-ref

link

​Common Questions

​Troubleshooting

​Related Commands

link

spec show

issue show

sync

​Next Steps

Cross-References in Markdown

Syntax

Description

Arguments

Options

Examples

Insert by Line Number

Insert by Text Search

Insert with Custom Display Text

Insert with Relationship Type

Insert on New Line

Insert Before Text

Complete Example

JSON Output

Reference Syntax

Basic Reference

With Display Text

With Relationship Type

Line vs Text Insertion

Using —line (Precise Positioning)

Using —text (Content-Based Positioning)

Common Workflows

Adding Implementation References to Spec

Building Linked Specifications

Scripted Reference Addition

Manual Alternative

Difference from `link` Command

Common Questions

Troubleshooting

Related Commands

Next Steps