> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sudocode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# sudocode add-ref

> Add inline Obsidian-style cross-references (`[[ID]]`) to spec or issue markdown files

## Syntax

```bash theme={null}
sudocode add-ref <entity-id> <reference-id> [options]
```

Or via entity-specific commands:

```bash theme={null}
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

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

## Arguments

<ParamField path="entity-id" type="string" required>
  The entity to add the reference to

  **Example:** `SPEC-001` or `ISSUE-001`

  This is where the reference will be inserted (the markdown file that will be modified).
</ParamField>

<ParamField path="reference-id" type="string" required>
  The entity being referenced

  **Example:** `ISSUE-042` or `SPEC-010`

  This is what you're referencing (the ID that will appear in `[[ID]]` syntax).
</ParamField>

## Options

<ParamField path="-l, --line" type="number">
  Insert at specific line number

  **Example:** `--line 15`

  The 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.
</ParamField>

<ParamField path="-t, --text" type="string">
  Search for text to insert near

  **Example:** `--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.
</ParamField>

<ParamField path="--position" type="string" default="after">
  Position relative to line or text

  **Example:** `--position before` or `--position after`

  Controls whether the reference is inserted before or after the specified line/text.
</ParamField>

<ParamField path="--display" type="string">
  Custom display text for the link

  **Example:** `--display "OAuth Implementation"`

  Creates a reference with custom text: `[[ISSUE-042|OAuth Implementation]]`

  Without this, the reference is just `[[ISSUE-042]]`.
</ParamField>

<ParamField path="--type" type="string">
  Create a typed relationship alongside the reference

  **Example:** `--type implements`

  Automatically creates a relationship of the specified type when adding the reference. Valid types: blocks, implements, depends-on, references, related, discovered-from.
</ParamField>

<ParamField path="--format" type="string" default="inline">
  Format style: inline or newline

  **Example:** `--format newline`

  * `inline` - Adds reference on the same line as the insertion point
  * `newline` - Adds reference on a new line
</ParamField>

## Examples

### Insert by Line Number

Add reference at line 15:

```bash theme={null}
sudocode add-ref SPEC-001 ISSUE-042 --line 15
```

<Accordion title="Expected output">
  ```
  ✓ Added reference to SPEC-001
    Reference: [[ISSUE-042]]
    Location: line 15 (after)
    Format: inline
  ```
</Accordion>

**Before (line 15):**

```markdown theme={null}
This is some content.
```

**After (line 15):**

```markdown theme={null}
This is some content. [[ISSUE-042]]
```

### Insert by Text Search

Add reference after "Requirements:" heading:

```bash theme={null}
sudocode add-ref SPEC-001 ISSUE-042 --text "Requirements:" --position after
```

<Accordion title="Expected output">
  ```
  ✓ Added reference to SPEC-001
    Reference: [[ISSUE-042]]
    Location: after "Requirements:"
    Format: inline
  ```
</Accordion>

**Before:**

```markdown theme={null}
## Requirements:
This section lists requirements.
```

**After:**

```markdown theme={null}
## Requirements:
[[ISSUE-042]] This section lists requirements.
```

### Insert with Custom Display Text

Add reference with readable text:

```bash theme={null}
sudocode add-ref SPEC-001 ISSUE-042 \
  --line 20 \
  --display "OAuth Implementation"
```

<Accordion title="Expected output">
  ```
  ✓ Added reference to SPEC-001
    Reference: [[ISSUE-042|OAuth Implementation]]
    Location: line 20 (after)
    Format: inline
  ```
</Accordion>

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

### Insert with Relationship Type

Add reference and create typed relationship:

```bash theme={null}
sudocode add-ref SPEC-001 ISSUE-042 \
  --text "Implementation" \
  --type implements
```

<Accordion title="Expected output">
  ```
  ✓ Added reference to SPEC-001
    Reference: [[ISSUE-042]]
    Type: implements
    Location: after "Implementation"
    Format: inline
  ```
</Accordion>

This both:

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

### Insert on New Line

Add reference on its own line:

```bash theme={null}
sudocode add-ref SPEC-001 ISSUE-042 \
  --line 10 \
  --format newline
```

<Accordion title="Expected output">
  ```
  ✓ Added reference to SPEC-001
    Reference: [[ISSUE-042]]
    Location: line 10 (after)
    Format: newline
  ```
</Accordion>

**Before:**

```markdown theme={null}
Some content on line 10.
```

**After:**

```markdown theme={null}
Some content on line 10.
[[ISSUE-042]]
```

### Insert Before Text

Add reference before a specific location:

```bash theme={null}
sudocode add-ref SPEC-001 ISSUE-042 \
  --text "## Design Decisions" \
  --position before
```

<Accordion title="Expected output">
  ```
  ✓ Added reference to SPEC-001
    Reference: [[ISSUE-042]]
    Location: after "## Design Decisions"
    Format: inline
  ```
</Accordion>

**Before:**

```markdown theme={null}
## Design Decisions
Content here.
```

**After:**

```markdown theme={null}
[[ISSUE-042]]
## Design Decisions
Content here.
```

### Complete Example

Add reference with all options:

```bash theme={null}
sudocode add-ref SPEC-001 ISSUE-042 \
  --line 25 \
  --display "See OAuth implementation" \
  --type implements \
  --format newline \
  --position after
```

<Accordion title="Expected output">
  ```
  ✓ Added reference to SPEC-001
    Reference: [[ISSUE-042|See OAuth implementation]]
    Type: implements
    Location: line 25 (after)
    Format: newline
  ```
</Accordion>

### JSON Output

Get machine-readable output:

```bash theme={null}
sudocode --json add-ref SPEC-001 ISSUE-042 --line 15
```

<Accordion title="JSON output">
  ```json theme={null}
  {
    "entity_id": "SPEC-001",
    "reference_id": "ISSUE-042",
    "location": "line 15",
    "success": true
  }
  ```
</Accordion>

## Reference Syntax

The command creates Obsidian-style wiki links:

### Basic Reference

```bash theme={null}
--line 10
```

Creates: `[[ISSUE-042]]`

### With Display Text

```bash theme={null}
--line 10 --display "OAuth Implementation"
```

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

### With Relationship Type

```bash theme={null}
--line 10 --type implements
```

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

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

## Line vs Text Insertion

### Using --line (Precise Positioning)

```bash theme={null}
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)

```bash theme={null}
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

<Warning>
  You must specify either `--line` or `--text`, but not both. Specifying both will result in an error.
</Warning>

## Common Workflows

### Adding Implementation References to Spec

<Steps>
  <Step title="Create issues from spec">
    ```bash theme={null}
    sudocode issue create "Implement login"
    sudocode issue create "Implement registration"
    ```
  </Step>

  <Step title="Add references to spec">
    ```bash theme={null}
    sudocode add-ref SPEC-001 ISSUE-001 \
      --text "Requirements:" \
      --type implements

    sudocode add-ref SPEC-001 ISSUE-002 \
      --text "Requirements:" \
      --type implements
    ```
  </Step>

  <Step title="Verify in spec">
    ```bash theme={null}
    sudocode spec show SPEC-001
    ```
  </Step>
</Steps>

### Building Linked Specifications

<Steps>
  <Step title="Create parent spec">
    ```bash theme={null}
    sudocode spec create "Authentication System"
    ```
  </Step>

  <Step title="Create child specs">
    ```bash theme={null}
    sudocode spec create "OAuth 2.0 Flow" --parent SPEC-001
    sudocode spec create "Session Management" --parent SPEC-001
    ```
  </Step>

  <Step title="Add cross-references">
    ```bash theme={null}
    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
    ```
  </Step>
</Steps>

### Scripted Reference Addition

Add references programmatically:

```bash theme={null}
# 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:

```bash theme={null}
# Edit the file directly
vim .sudocode/specs/authentication-system.md
```

Add references using Obsidian syntax:

```markdown theme={null}
## Requirements

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

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

Then sync changes:

```bash theme={null}
sudocode sync
```

<Info>
  Manual editing gives you full control over placement and formatting. Use `add-ref` for programmatic automation.
</Info>

## Difference from `link` Command

<CardGroup cols={2}>
  <Card title="add-ref" icon="at">
    **Inline references in markdown**

    * Modifies markdown content
    * Visible as `[[ID]]` in files
    * Can include display text
    * Optional relationship creation
    * Good for documentation
  </Card>

  <Card title="link" icon="link">
    **Database relationships**

    * Creates typed relationship
    * Not visible in markdown
    * Required relationship type
    * Bidirectional tracking
    * Good for dependency modeling
  </Card>
</CardGroup>

**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:

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="Can I add multiple references at once?">
    No, `add-ref` processes one reference at a time. For bulk additions, use shell scripting:

    ```bash theme={null}
    for issue in ISSUE-001 ISSUE-002 ISSUE-003; do
      sudocode add-ref SPEC-001 "$issue" --line 10 --format newline
    done
    ```
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="Can I remove a reference?">
    There's no `remove-ref` command. To remove references:

    1. Edit the markdown file directly
    2. Remove the `[[ID]]` syntax
    3. Run `sudocode sync`
  </Accordion>

  <Accordion title="Does this work with archived entities?">
    Yes, you can add references to archived specs or issues, though they'll be hidden from default listings.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error: Either --line or --text must be specified">
    **Cause:** You didn't provide a location for insertion

    **Solution:**
    Specify one location method:

    ```bash theme={null}
    sudocode add-ref SPEC-001 ISSUE-001 --line 15
    # OR
    sudocode add-ref SPEC-001 ISSUE-001 --text "Requirements:"
    ```
  </Accordion>

  <Accordion title="Error: Cannot specify both --line and --text">
    **Cause:** You provided both location methods

    **Solution:**
    Choose only one:

    ```bash theme={null}
    # 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:"
    ```
  </Accordion>

  <Accordion title="Error: Entity not found">
    **Cause:** The entity\_id doesn't exist

    **Solution:**
    Verify the ID:

    ```bash theme={null}
    sudocode spec list
    sudocode issue list
    ```
  </Accordion>

  <Accordion title="Error: File not found">
    **Cause:** The markdown file doesn't exist for the entity

    **Solution:**
    Sync to create markdown files:

    ```bash theme={null}
    sudocode sync
    ```
  </Accordion>

  <Accordion title="Error: Text not found">
    **Cause:** The search text doesn't exist in the file

    **Solution:**

    * Check for exact match (case-sensitive)
    * View the file to verify text:
      ```bash theme={null}
      sudocode spec show SPEC-001
      ```
    * Use different search text or switch to `--line`
  </Accordion>

  <Accordion title="Error: Invalid line number">
    **Cause:** Line number is less than 1 or not a number

    **Solution:**
    Use a valid positive integer:

    ```bash theme={null}
    sudocode add-ref SPEC-001 ISSUE-001 --line 10
    ```
  </Accordion>

  <Accordion title="Error: Line number out of bounds">
    **Cause:** The line number is greater than the number of lines in the file

    **Solution:**
    Check the file length:

    ```bash theme={null}
    wc -l .sudocode/specs/authentication-system.md
    ```

    Use a valid line number within range.
  </Accordion>
</AccordionGroup>

## Related Commands

<CardGroup cols={3}>
  <Card title="link" icon="link" href="/cli/link">
    Create typed relationships
  </Card>

  <Card title="spec show" icon="eye" href="/cli/spec-show">
    View spec content
  </Card>

  <Card title="issue show" icon="eye" href="/cli/issue-show">
    View issue content
  </Card>

  <Card title="sync" icon="arrows-rotate" href="/cli/sync">
    Sync markdown files
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Create entities">
    ```bash theme={null}
    sudocode spec create "My Feature"
    sudocode issue create "Implement X"
    ```
  </Step>

  <Step title="Add references">
    ```bash theme={null}
    sudocode add-ref SPEC-001 ISSUE-001 --line 10 --type implements
    ```
  </Step>

  <Step title="View the result">
    ```bash theme={null}
    sudocode spec show SPEC-001
    # or view markdown file
    cat .sudocode/specs/my-feature.md
    ```
  </Step>

  <Step title="Verify relationships">
    ```bash theme={null}
    sudocode spec show SPEC-001
    # Check "Incoming Relationships" section
    ```
  </Step>
</Steps>

<Card title="Cross-References in Markdown" icon="book" href="/concepts/specs">
  Learn more about using Obsidian-style links in sudocode
</Card>