Link Update and Validation

How to validate, fix, and update links in your installed Knowledge Base content.

Automatically validate, fix, and update links in your installed Knowledge Base content when your project structure changes or links become broken.

Quick Start

# Validate and convert all links to relative paths (default)
pair update-link
 
# Preview changes without modifying files
pair update-link --dry-run
 
# Convert all links to absolute paths
pair update-link --absolute
 
# Get detailed logging
pair update-link --log-level debug

Use Cases

1. Project Structure Changes

When you move or rename directories:

# Update KB links after restructuring project
pair update-link
 
# Check what would change first
pair update-link --dry-run

2. Repository Migration

After moving your project to a different location:

# Convert to absolute paths for new location
pair update-link --absolute
 
# Or normalize to relative paths
pair update-link --relative

3. Link Validation

Check for broken links in installed KB:

# Validate and fix broken links
pair update-link --verbose

4. Path Normalization

Standardize link formats across KB:

# Convert all to relative paths (default)
pair update-link
 
# Convert all to absolute paths
pair update-link --absolute

Command Reference

Basic Syntax

pair update-link [options]

Options

Option	Description	Default
`--relative`	Convert all links to relative paths	Implicit default
`--absolute`	Convert all links to absolute paths	-
`--dry-run`	Preview changes without modifying files	`false`
`--log-level <level>`	Set logging level (trace, debug, info, warn, error). Use `--log-level debug` for detailed logs	`info`

Examples

Default behavior (relative paths):

pair update-link

Explicit relative conversion:

pair update-link --relative

Convert to absolute paths:

pair update-link --absolute

Preview without changes:

pair update-link --dry-run
# or combine with path mode
pair update-link --absolute --dry-run

Detailed logging:

pair update-link --verbose

How It Works

Processing Workflow

Detection: Locates installed KB content in .pair/ directory
Validation: Checks all markdown links against current file system
Fixing: Repairs broken links where possible
Adjustment: Updates paths for moved projects
Conversion: Applies relative/absolute path transformation
Summary: Reports all changes and remaining issues

Link Types Supported

Relative paths: ./docs/file.md, ../guide.md
Absolute paths: /absolute/path/to/file.md
External URLs: https://example.com (skipped)
Mailto links: mailto:email@example.com (skipped)
Anchors: #section-title (preserved)

File Safety

Backup: Automatic backup before modifications (.pair/backups/)
Atomic writes: Prevents partial updates
Rollback: Automatic restore on critical errors
Dry-run: Preview changes safely

Output Format

Summary Report

Link Update Summary:

Total links processed: 127
Files modified: 23

Links by category:
  broken to fixed: 5
  relative to absolute: 45
  absolute to relative: 67
  path adjusted: 10

Remaining issues:
  File: docs/guide.md (line 42)
  Error: Target file not found: /missing/file.md

Dry-Run Output

DRY RUN MODE - No files will be modified

[... processing summary ...]

Tip: Remove --dry-run to apply changes

Common Scenarios

After Installing KB Content

# Install KB first
pair install
 
# Then update links for your project structure
pair update-link

Moving Project Directory

# Project moved from /old/path to /new/path
cd /new/path/to/project
 
# Update links for new location
pair update-link

Checking Link Health

# Run dry-run with debug-level logging
pair update-link --dry-run --log-level debug
 
# Review output for broken links
# Fix issues manually if needed
# Run actual update
pair update-link

Standardizing Link Format

# Convert mixed link formats to relative
pair update-link --relative
 
# Or convert to absolute for portability
pair update-link --absolute

Troubleshooting

"No KB installed" Error

Problem: Command reports no Knowledge Base found.

Solution:

# Install KB first
pair install
 
# Then run update-link
pair update-link

Permission Errors

Problem: Cannot write to files.

Solution:

# Check file permissions
ls -la .pair/
 
# Fix permissions if needed
chmod -R u+w .pair/
 
# Run command again
pair update-link

Broken Links Remain

Problem: Some links still broken after update.

Solution:

# Use verbose mode to see details
pair update-link --verbose
 
# Check reported errors in output
# Manually fix links that cannot be auto-resolved
# Re-run command
pair update-link

Root Detection Fails

Problem: Cannot determine project root.

Solution:

# Ensure you're in a git repository
git rev-parse --show-toplevel
 
# Or have package.json in root
ls -la package.json
 
# Or have .pair directory
ls -la .pair/
 
# Run from project root
cd /path/to/project-root
pair update-link

Integration with Other Commands

Complete Workflow

# 1. Install KB content
pair install
 
# 2. Validate and update links
pair update-link --dry-run
 
# 3. Apply link updates
pair update-link
 
# 4. Update KB content to latest version
pair update
 
# 5. Re-validate links after update
pair update-link

CI/CD Integration

# Example GitHub Actions workflow
- name: Install pair CLI
  run: npm install -g @foomakers/pair-cli
 
- name: Install KB
  run: pair install
 
- name: Validate links
  run: pair update-link --dry-run
 
- name: Update links
  run: pair update-link

Best Practices

Use dry-run first: Always preview changes with --dry-run
Commit before updating: Create a checkpoint before running
Choose consistent format: Stick to relative or absolute across project
Run after structural changes: Update links when moving files/folders
Check verbose output: Use --verbose to understand changes
Validate in CI: Add link validation to your CI pipeline

Link Update and Validation

On this page