CLI Reference

July 16, 2026 · View on GitHub

Complete reference for all rela commands.

Global Options

These options work with any command:

Option	Description
`-p, --project`	Project directory (default: auto-detect from cwd, or `RELA_PROJECT`)
`-o, --output`	Output format: `table` (default) or `json`
`-v, --verbose`	Enable verbose output
`-q, --quiet`	Suppress non-essential output
`-h, --help`	Show help for any command

Environment Variables

Variable	Description
`RELA_PROJECT`	Default project directory when `--project` flag is not specified

Project Configuration

Project-level settings are stored in .rela/config.yaml. This file is optional; defaults are used when it doesn't exist.

formatting:
  line_width: 80 # Maximum line width for paragraph wrapping (default: 80)

Setting	Description	Default
`formatting.line_width`	Maximum line width for paragraph wrapping	80

Commands

rela init

Initialize a new rela project.

rela init
rela init -p /path/to/project

Creates:

metamodel.yaml - Default configuration
entities/ - Entity storage directory
relations/ - Relation storage directory
.rela/ - Cache directory (added to .gitignore if present)

rela apps new

Scaffold a new custom data-entry app (see the data-entry guide's "Custom apps" section).

rela apps new my-dashboard

Creates apps/<id>/index.html — a working starter that links the bridge SDK (_rela.js) and the optional theme (_rela.css), reads data via rela.list(...), and renders a result. Edit it, then open /app/<id> in the data-entry server. The <id> must match ^[a-z0-9_-]{1,64}$ and becomes the folder name and route; it errors if the app already exists.

rela create

Create a new entity.

rela create <type> [flags]

Arguments:

type - Entity type (e.g., requirement, decision, solution, component)

Flags:

Flag	Description
`-s, --status`	Entity status (default: `draft`)
`-p, --priority`	Entity priority
`--id`	Custom entity ID (required for string ID types, auto-generated for sequential)
`-P, --property`	Set a property (format: key=value, can be repeated)
`-b, --body`	Markdown body content for the entity
`-B, --body-file`	Read body content from file (use `-` for stdin)

Set the title (and any other property) with -P, e.g. -P title="...".

Removed: create no longer has a -t, --title flag. It used to write into the entity type's display property, which is not always title (a project may name it naam/label or set display_property). If you relied on --title writing into a non-title display property, set that property directly: -P <yourprop>="...". (rela update -t is unaffected — it always wrote the literal title property.)

Templates:

If a template exists at templates/entities/<type>.md, its frontmatter values are used as defaults and its content is applied to the new entity. CLI flags override template defaults. See rela template for creating templates.

ID Types:

Entity types can have either sequential or string IDs (configured in metamodel.yaml):

Sequential (default): IDs are auto-generated (REQ-001, REQ-002, etc.)
String: IDs must be provided with --id flag

# Sequential ID type (auto-generated)
rela create requirement -P title="System must scale to 1000 users"
# Creates REQ-001

# String ID type (requires --id)
rela create component --id auth-service -P title="Authentication Service"
# Creates auth-service

Examples:

# Create with auto-generated ID (sequential types)
rela create requirement -P title="System must scale to 1000 users"

# Use type alias
rela create req -P title="Short form works too"

# With status and priority
rela create requirement -P title="Security audit" --status proposed --priority high

# With custom ID (works for both sequential and string types)
rela create requirement -P title="Custom ID" --id REQ-CUSTOM-001

# String ID type (--id is required)
rela create component --id user-service -P title="User Service"

# With custom properties
rela create control -P title="Access Control" -P "iso27001=A.5.15" -P "owner=Security Team"

# With body content
rela create requirement -P title="Auth feature" --body "## Description\n\nUser authentication."

rela list

List entities with optional filtering.

rela list [type] [flags]

Arguments:

type - Entity type to filter by (optional, shows all if omitted)

Flags:

Flag	Description
`--where`	Filter by property (repeatable for AND logic)
`--sort`	Sort by property (or `id`, `modified`)
`--desc`	Sort descending

Filter Operators:

The --where flag supports multiple comparison operators:

Operator	Description	Example
`=`	Exact match (supports `*` glob)	`--where "status=draft"`
`!=`	Not equal	`--where "status!=done"`
`<`	Less than (date/integer)	`--where "due_date<2025-03-01"`
`<=`	Less than or equal	`--where "priority<=2"`
`>`	Greater than	`--where "risk_score>5"`
`>=`	Greater than or equal	`--where "valid_until>=2025-01-01"`
`=~`	Regex match	`--where "title=~^Auth"`
`~`	Fuzzy match	`--where "title~authentcation"`

Glob Patterns:

Use * in equality matches for wildcard matching:

rela list control --where "iso27001=A.9.*"    # Matches A.9.1, A.9.2.1, etc.
rela list --where "title=User*"               # Titles starting with "User"

Fuzzy Matching:

The ~ operator performs fuzzy (typo-tolerant) matching:

rela list --where "title~authentcation"       # Finds "authentication" despite typo

Examples:

# List all entities
rela list

# List by type (plural or singular)
rela list requirements
rela list requirement
rela list req

# Filter by property value
rela list control --where "status=implemented"

# Multiple filters (AND logic)
rela list control --where "status=implemented" --where "applicability=applicable"

# Date comparison
rela list evidence --where "valid_until<2025-02-01"

# Integer comparison
rela list risk --where "risk_score>=5"

# Sort by property
rela list control --sort iso27001
rela list evidence --sort valid_until --desc

# JSON output
rela list -o json

rela show

Display detailed information about an entity.

rela show <id>

Arguments:

id - Entity ID to show

Shows the entity's properties plus all incoming and outgoing relations.

Examples:

rela show REQ-001
rela show DEC-042 -o json

rela update

Update an entity's properties.

rela update <id> [flags]

Arguments:

id - Entity ID to update

Flags:

Flag	Description
`-t, --title`	New title
`-s, --status`	New status
`-p, --priority`	New priority
`-d, --description`	New description

At least one flag is required.

Examples:

# Update status
rela update REQ-001 --status accepted

# Update multiple fields
rela update DEC-042 --title "Revised title" --status proposed

# Update description
rela update SOL-001 --description "Detailed implementation notes"

rela delete

Delete an entity.

rela delete <id> [flags]

Arguments:

id - Entity ID to delete

Flags:

Flag	Description
`-f, --force`	Skip confirmation prompt
`--cascade`	Also delete related links

Without --cascade, deletion fails if the entity has relations.

Examples:

# Interactive confirmation
rela delete REQ-001

# Skip confirmation
rela delete REQ-001 --force

# Delete entity and all its relations
rela delete REQ-001 --cascade

rela history

Show an entity's version history, or print a past version's snapshot for piping to a diff tool. PostgreSQL build only — content versioning is a PostgreSQL-backend capability (filesystem projects use git for the same purpose); on other builds this reports that the backend does not support history.

rela history <id> [--version N]

Arguments:

id - Entity ID (may name a live or an already-deleted entity)

Flags:

--version N - Print the full snapshot for version ordinal N (as JSON) instead of the timeline, so it can be piped to an external diff tool

Each timeline row shows the version number, timestamp, operation (create/update/rename/delete), and the principal (user + tool) that made the change. Reading a deleted entity's history requires the history:read permission (see the ACL guide).

Examples:

rela history TKT-42                       # the version timeline
rela history TKT-42 --version 3           # print version 3's snapshot

# Diff two versions with any external tool (Unix-style):
diff <(rela history TKT-42 --version 3) <(rela history TKT-42 --version 5)

rela restore

Restore an entity's content and properties to a past version. PostgreSQL build only. The restore is applied as a normal write — authorized, validated, audited, and itself recorded as a new version (history is never rewritten). If the entity was deleted, it is re-created.

rela restore <id> <version>

Arguments:

id - Entity ID to restore
version - The version ordinal to restore to (see rela history <id>)

Only entity content and properties are restored; the entity's relations as-of that version are versioned separately (see rela relation-history).

Examples:

rela restore TKT-42 3

rela relation-history

Show a relation's version history, or print a past version's snapshot for piping to a diff tool. A relation is addressed by its three-part key. PostgreSQL build only (filesystem projects use git). Relations carry their own properties and markdown body, versioned with the same time-machine model as entities.

rela relation-history <from> <type> <to> [--version N]

Arguments:

from - Source entity ID (the relation's from)
type - Relation type (e.g. blocks)
to - Target entity ID (the relation's to)

Flags:

--version N - Print the full snapshot for version ordinal N (as JSON) for piping to an external diff tool, instead of the timeline

Each row shows the version, timestamp, operation (create/update/rename/delete), and principal. A rename row shows the pre-rename endpoints so a renamed edge's history reads as one continuous timeline. Reading a relation's history requires read access to both endpoints (a deleted relation requires history:read).

Examples:

rela relation-history TKT-42 blocks TKT-99

# Diff two versions with any external tool (Unix-style):
diff <(rela relation-history TKT-42 blocks TKT-99 --version 2) \
     <(rela relation-history TKT-42 blocks TKT-99 --version 4)

rela relation-restore

Restore a relation's content and properties to a past version. PostgreSQL build only. Applied as a normal write (authorized, validated, audited, re-versioned). If the relation was deleted it is re-created — which fails with a conflict if an endpoint entity no longer exists.

rela relation-restore <from> <type> <to> <version>

Arguments:

from / type / to - The relation's three-part key
version - The version ordinal to restore to (see rela relation-history)

Examples:

rela relation-restore TKT-42 blocks TKT-99 2

rela history-purge

Hard-delete an entity's version history for compliance (leaked secret, PII, GDPR erasure). The deliberate, audited, irreversible exception to append-only history. PostgreSQL build only. Operator-only: the trust boundary is shell + RELA_DATABASE_URL access (no ACL check), like rela db migrate.

rela history-purge <id> (--vseq N | --content-hash H | --all) --reason "..." [--commit] [--yes] [--force-live]

Arguments / flags:

id — the entity whose history to purge
--vseq N — purge the single version row with this vseq (from rela history)
--content-hash H — purge every row in the lineage with this content hash (erase a value everywhere it was captured; verifiable afterward)
--all — purge the entity's entire (fenced) history
--reason "..." — required; recorded in the audit trail. Do NOT put the secret here (logged in cleartext)
--commit — actually delete. Without it the command is a dry-run that only shows what would be purged
--yes — skip the type-the-id confirmation (scripts); requires --commit
--force-live — purge even though the live row still holds the content (writes a tombstone so the sweep will not re-capture it). Prefer redacting the live value first.

Purge refuses while the live row still holds the content (unless --force-live) and refuses a rename row. It is one necessary step, not cryptographic erasure — PITR/backup lifecycle is the operator's responsibility.

Examples:

rela history-purge TKT-42 --content-hash abc123 --reason "erase SSN per DPO-42"          # dry-run
rela history-purge TKT-42 --content-hash abc123 --reason "erase SSN per DPO-42" --commit  # do it

rela relation-history-purge

The relation analog of rela history-purge, addressing a relation by its three-part key. Same flags, guardrails, and irreversibility. PostgreSQL build only.

rela relation-history-purge <from> <type> <to> (--vseq N | --content-hash H | --all) --reason "..." [--commit] [--yes] [--force-live]

Examples:

rela relation-history-purge TKT-42 blocks TKT-99 --all --reason "erase per request" --commit

rela attach

Attach file(s) to an entity.

rela attach <entity-id> <file>... [flags]

Each file is stored at attachments/<entity-id>/<property>/<filename>. A file-type property holds one attachment by default; set max above 1 on the property (see the metamodel reference) to allow several.

Note: for a single-attachment property (max: 1), re-running attach replaces the existing file. For a multi-attachment property (max > 1), attach appends up to the cap, auto-suffixing a duplicate name (report.pdf → report (1).pdf) and erroring when full.

Arguments:

entity-id - Target entity ID
file... - One or more files to attach (supports glob patterns)

Flags:

Flag	Description
`-P, --property`	Property to attach file(s) to

If --property is not specified, uses the first file-type property defined for the entity type.

Examples:

rela attach BUG-042 screenshot.png
rela attach BUG-042 screenshot.png --property screenshot
rela attach DEC-007 supporting-doc.pdf --property supporting-docs

rela attachments

List all file attachments for an entity.

rela attachments <entity-id>

Shows the property name, path, and size for each attachment.

Arguments:

entity-id - Entity ID to list attachments for

Examples:

rela attachments BUG-042
rela attachments DEC-007

rela detach

Remove an attachment from an entity property.

rela detach <entity-id> <property> [--file <name>]

Deletes the underlying file from the attachment store and re-stamps the property. When the property holds a single attachment, --file may be omitted. When it holds several (a file property with max > 1), pass --file to select which one — rela attachments <entity-id> lists the names.

Arguments:

entity-id - Entity ID
property - Property name containing the attachment

Flags:

Flag	Description
`-f, --file`	File name to detach (required when more than one)

Examples:

rela detach BUG-042 screenshot
rela detach DEC-007 supporting-docs --file spec.pdf

rela link

Create a relation between two entities.

rela link <from> <relation> <to>

Arguments:

from - Source entity ID
relation - Relation type name
to - Target entity ID

Both entities must exist. The relation type is validated against the metamodel.

Templates:

If a template exists at templates/relations/<type>.md, its frontmatter values are used as defaults for relation properties. See rela template for creating templates.

Examples:

rela link DEC-001 addresses REQ-001
rela link SOL-001 implements DEC-001
rela link COMP-001 realizes SOL-001
rela link COMP-001 dependsOn COMP-002

rela unlink

Remove a relation between entities.

rela unlink <from> <relation> <to>

Arguments:

from - Source entity ID
relation - Relation type name
to - Target entity ID

Examples:

rela unlink DEC-001 addresses REQ-001

rela sync

Two-way sync between a local project (fsstore) and a remote rela-server backed by PostgreSQL. push sends locally-changed records to the server; pull brings remote changes into the local project. Conflicts are surfaced for manual resolution — no automatic merge. See Sync for the full design.

rela sync push [--remote <url>] [--token <token>] [--force <id>]
rela sync pull [--remote <url>] [--token <token>] [--force <id>]

Flags:

Flag	Description
`--remote`	Remote rela-server base URL (proxy-fronted). Env: `RELA_REMOTE`.
`--token`	Bearer token for the OAuth proxy. Prefer env `RELA_SYNC_TOKEN`.
`--force`	Resolve one record id: push = local wins, pull = remote wins.

The sync state (a per-record content-hash index and an opaque server cursor) lives in .rela/sync-state.json. Dirty detection is local: a record whose canonical hash differs from the index is pushed; the index advances only past confirmed-applied records, so an interrupted run resumes on re-run.

Conflicts. A record changed on both ends halts with a clear report and is NOT applied. Resolve it explicitly:

rela sync push --force <id> — overwrite the remote with the local copy.
rela sync pull --force <id> — overwrite the local copy with the remote.

Authentication. In production rela-server sits behind an OAuth proxy and has no native auth — the CLI authenticates to the proxy by presenting a JWT bearer (Authorization: Bearer $RELA_SYNC_TOKEN). The token is read from the env/flag and never logged. On loopback/dev with no proxy, sync works without a token. See Sync for the proxy configuration.

Examples:

export RELA_REMOTE=https://rela.example.com
export RELA_SYNC_TOKEN=$(my-idp-get-token)

rela sync push                 # send local changes
rela sync pull                 # bring in remote changes
rela sync push --force TKT-42  # resolve TKT-42: local wins
rela sync pull --force TKT-42  # resolve TKT-42: remote wins

Note: sync requires the remote to run the PostgreSQL backend. Against a non-postgres server the manifest endpoint returns 501 and pull reports that the server does not support sync.

rela trace

Trace dependencies between entities.

rela trace from

Trace downstream dependencies (what depends on this entity).

rela trace from <id> [flags]

Flags:

Flag	Description
`--depth`	Maximum depth (0 = unlimited)

Examples:

rela trace from REQ-001
rela trace from REQ-001 --depth 2

rela trace to

Trace upstream dependencies (what this entity depends on).

rela trace to <id> [flags]

Flags:

Flag	Description
`--depth`	Maximum depth (0 = unlimited)

Examples:

rela trace to COMP-001
rela trace to COMP-001 --depth 3

rela trace path

Find the shortest path between two entities.

rela trace path <from> <to>

Examples:

rela trace path REQ-001 COMP-001

rela graph

Export the entity graph to Graphviz DOT format.

rela graph [flags]

Flags:

Flag	Description
`-o, --output`	Output file (stdout if not specified)
`-f, --format`	Output format: `dot`, `png`, `svg`, `pdf`
`--direction`	Graph direction: `tb` (top-bottom) or `lr` (left-right)
`--types`	Filter by entity types (comma-separated)

Rendering to PNG/SVG/PDF requires Graphviz (dot command).

Examples:

# Print DOT to stdout
rela graph

# Save DOT file
rela graph --file architecture.dot

# Render to PNG
rela graph --file architecture.png -f png

# Filter by types
rela graph --types requirement,decision

# Left-to-right layout
rela graph --direction lr

rela export

Export entities to structured formats for external tool integration.

rela export [type] [flags]

Arguments:

type - Entity type to export (required unless using --all)

Flags:

Flag	Description
`-f, --format`	Output format: `json` (default), `csv`, or `yaml`
`--with-relations`	Include relation data in export
`--all`	Export all entities and relations

Output Formats:

JSON: Array of objects with full property data. Best for programmatic processing with jq.
CSV: Comma-separated values with header row. Best for spreadsheet import or mlr (Miller).
YAML: YAML format. Best for human readability and configuration.

Examples:

# Export all controls as JSON
rela export control --format json

# Export controls as CSV for spreadsheet import
rela export control --format csv

# Export controls with their relations included
rela export control --with-relations

# Export all entities and relations
rela export --all --format json

# Use with jq for custom filtering
rela export control --format json | jq '.[] | select(.properties.status == "draft")'

# Use with jq to create a summary report
rela export control --format json | jq '[.[] | {id, title: .properties.title, status: .properties.status}]'

# Use with Miller for CSV filtering
rela export control --format csv | mlr --csv filter '$status == "implemented"'

# Generate a gap report (controls without evidence)
rela export control --with-relations --format json | \
  jq '.[] | select(.relations.outgoing.evidencedBy == null) | {id, title: .properties.title}'

# Export to file
rela export control --format csv > controls.csv

Relation Data Structure:

When using --with-relations, each entity includes:

{
  "id": "CTRL-001",
  "type": "control",
  "properties": { ... },
  "relations": {
    "outgoing": {
      "mitigates": [{"id": "RISK-001", "title": "Unauthorized Access"}],
      "evidencedBy": [{"id": "EV-001", "title": "Audit Report"}]
    },
    "incoming": {
      "implements": [{"id": "PROC-001", "title": "Access Procedure"}]
    }
  }
}

Full Export Structure:

When using --all, the output includes both entities and relations:

{
  "entities": [ ... ],
  "relations": [
    {"from": "DEC-001", "relation": "addresses", "to": "REQ-001"}
  ]
}

rela fmt

Format entity and relation files for consistent styling.

rela fmt [type] [flags]

Arguments:

type - Optional: specific entity type to format

Flags:

Flag	Description
`--dry-run`	Preview changes without writing
`--check`	Check if files need formatting (exits 1 if they do)

This command normalizes:

Frontmatter property ordering (id/type first for entities, from/relation/to for relations)
Markdown content formatting (headings, lists, whitespace)
Paragraph wrapping to configured line width (default: 80 characters)

Configuration:

Line width can be configured in .rela/config.yaml:

formatting:
  line_width: 100 # default: 80

What gets wrapped:

Paragraph text is wrapped to the configured line width
Code blocks, headings, lists, and blockquotes are NOT wrapped (preserved as-is)

Examples:

rela fmt                # Format all entities and relations
rela fmt requirements   # Format only requirements (entities)
rela fmt --dry-run      # Preview changes without writing
rela fmt --check        # Check if files need formatting (for CI)

CI Integration:

Add to your CI pipeline to ensure consistent formatting:

- run: rela fmt --check

This will exit with code 1 if any files need formatting.

rela import

Import entities and relations from structured files.

rela import <file> [flags]

Arguments:

file - Path to the import file (JSON, YAML, or CSV)

Flags:

Flag	Description
`-f, --format`	Input format: `json`, `yaml`, or `csv`. Auto-detected from extension if not specified
`-n, --dry-run`	Validate without creating files
`-u, --update`	Replace existing entities instead of failing on duplicates
`--skip-errors`	Continue importing on validation errors
`-r, --relations`	Path to relations CSV file (for CSV imports)

Input Formats:

JSON - Object with entities and relations arrays, or just an array of entities:

{
  "entities": [
    {
      "id": "REQ-001",
      "type": "requirement",
      "properties": { "title": "User login", "status": "draft" }
    },
    {
      "id": "DEC-001",
      "type": "decision",
      "properties": { "title": "Use JWT", "status": "accepted" }
    }
  ],
  "relations": [{ "from": "DEC-001", "relation": "addresses", "to": "REQ-001" }]
}

YAML - Same structure as JSON:

entities:
  - id: REQ-001
    type: requirement
    properties:
      title: User login
      status: draft
relations:
  - from: DEC-001
    relation: addresses
    to: REQ-001

CSV - Columns for entity fields (id, type, and properties):

id,type,title,status,priority
REQ-001,requirement,User login,draft,high
REQ-002,requirement,User logout,draft,medium

For CSV, relations require a separate file with --relations:

from,relation,to
DEC-001,addresses,REQ-001

Examples:

# Import from JSON
rela import entities.json

# Import from YAML
rela import data.yaml

# Import from CSV
rela import entities.csv

# Import CSV with separate relations file
rela import entities.csv --relations relations.csv

# Dry-run to validate without creating files
rela import --dry-run data.json

# Update existing entities instead of failing
rela import --update data.json

# Continue on validation errors
rela import --skip-errors data.json

# Explicit format (when extension doesn't match)
rela import data.txt --format json

Behavior Notes:

Validation: All entities are validated against the metamodel before import
Auto-generated properties: If status is not provided, the entity type's default is used
Duplicate handling: Without --update, importing an existing entity ID fails
Update mode: --update does a full replacement, not a merge (existing properties not in the import file are removed)
Relations: Relations referencing entities not in the graph (and not in the import) will fail
Atomic by default: If any entity fails validation, no entities are created (unless --skip-errors)

Round-trip with export:

# Export all entities and relations
rela export --all -f json > backup.json

# Later, import to a new project
rela import backup.json

rela analyze

Run quality analysis checks.

rela analyze orphans

Find entities with no connections.

rela analyze orphans

rela analyze duplicates

Find entities with similar titles.

rela analyze duplicates

rela analyze unique

Find entities that violate a unique: true property constraint — same-type entities sharing a value for a unique property. The write path rejects new duplicates; this surfaces ones that already exist (e.g. after adding unique: true to a property whose data already contains collisions, which the constraint does not clean retroactively).

rela analyze unique

rela analyze gaps

Find gaps in ID sequences for entity types with sequential IDs.

rela analyze gaps

Gap analysis only applies to entity types with id_type: sequential. Entity types with short (default) or manual IDs are excluded since they don't follow numeric sequences.

rela analyze cardinality

Check relation cardinality constraints.

rela analyze cardinality

rela analyze validations

Run custom validation rules defined in the metamodel.

rela analyze validations

Validation rules check entity properties against custom conditions. See Metamodel Reference - Custom Validation Rules for details.

Example output:

$ rela analyze validations
✗ Accepted requirements must have a priority assigned (2):
  REQ-003: User authentication
  REQ-007: Data encryption
⚠ Decisions should have a rationale documented (1):
  DEC-002: Use PostgreSQL
Found 2 errors, 1 warnings across 2 rules

rela analyze properties

Validate entity property values against the metamodel schema.

rela analyze properties

Checks for:

Invalid enum values (not in allowed list)
Invalid custom type values
Invalid date formats
Invalid integer/boolean values
Missing required properties
Entity IDs not matching configured patterns

This catches issues in manually-edited markdown files that bypass CLI validation.

rela analyze schema

Analyze metamodel schema usage to find unused or underused types.

rela analyze schema
rela analyze schema --threshold 2
rela analyze schema --cleanup --dry-run

Shows:

Entity types with no instances
Relation types with no instances
Custom types (enums) not referenced by any property
Types with few instances (when --threshold is set)

Flags:

Flag	Description
`--threshold`	Show types with instance count <= threshold (0 = only unused)
`--cleanup`	Remove unused types from metamodel.yaml
`--dry-run`	Preview cleanup changes without modifying files

The cleanup operation only removes types that have no instances AND no references in configuration files (data-entry.yaml, validations, automations). Types referenced in forms, lists, views, or validations will not be removed even if they have zero instances.

rela analyze all

Run all analysis checks.

rela analyze all

Runs orphans, duplicates, gaps, cardinality, properties, and (if defined) custom validations.

rela mcp

Start the MCP (Model Context Protocol) server over stdio.

rela mcp

Exposes rela's capabilities to AI assistants like Claude Code, Cursor, and other MCP-compatible clients. The server runs on stdin/stdout using JSON-RPC and provides:

21 tools for entity/relation CRUD, graph tracing, analysis, and export
3 resources for reading entities, relations, and the metamodel by URI
4 prompts for common AI-assisted workflows
File watching with automatic graph sync on changes

Client Configuration (Claude Code):

Setup with claude mcp add (recommended):

claude mcp add rela -s local -- /path/to/rela mcp

Setup with .mcp.json (for sharing via git):

{
  "mcpServers": {
    "rela": {
      "command": "rela",
      "args": ["mcp"]
    }
  }
}

See MCP Server Guide for the full tool/resource/prompt reference.

rela tui

Launch the interactive terminal UI.

rela tui

See TUI Guide for details.

rela completion

Generate shell completion scripts.

rela completion <shell>

Arguments:

shell - Target shell: bash, zsh, fish, or powershell

Examples:

# Bash
rela completion bash > /etc/bash_completion.d/rela

# Zsh
rela completion zsh > "${fpath[1]}/_rela"

# Fish
rela completion fish > ~/.config/fish/completions/rela.fish

rela template

Manage templates for creating entities and relations.

Templates provide default frontmatter values and markdown body content when creating new entities or relations. They are stored in:

templates/entities/<type>.md - Entity templates
templates/relations/<type>.md - Relation templates

rela template init

Generate template files from the metamodel.

rela template init [type...] [flags]

Arguments:

type... - Optional: specific entity or relation types to generate templates for

Flags:

Flag	Description
`--entities`	Only generate entity templates
`--relations`	Only generate relation templates
`--force`	Overwrite existing templates

Without arguments, generates templates for all entity and relation types defined in the metamodel.

Examples:

# Generate all templates
rela template init

# Generate template for a specific entity type
rela template init requirement

# Generate template for a specific relation type
rela template init addresses

# Generate only entity templates
rela template init --entities

# Generate only relation templates
rela template init --relations

# Overwrite existing templates
rela template init --force

# Generate specific types with force
rela template init requirement decision --force

Generated Template Format:

Entity templates include all properties from the metamodel with their default values:

---
title: ""
status: draft
priority: medium
---

# Description

Describe your requirement here.

Relation templates include a placeholder for rationale:

---
---

# Rationale

Explain why this addresses relation exists.

Using Templates:

Once templates are created, they are automatically applied when using rela create or rela link. CLI flags override template defaults.

# Create a template
rela template init requirement

# Edit the template to customize defaults
# templates/entities/requirement.md

# New entities will use the template
rela create requirement -P title="My Requirement"

rela migrate

Migrate project files to the current schema format.

rela migrate [flags]

Flags:

Flag	Description
`--check`	Check for pending migrations without applying (useful for CI)

This command detects deprecated syntax patterns in your project files (e.g., metamodel.yaml) and transforms them to the current format while preserving comments and formatting.

When to use:

If you see an error like this when running any rela command:

metamodel.yaml uses deprecated syntax:
  - Rename id_type values: "sequential" → "auto", "string" → "manual"

Run 'rela migrate' to update your project files.

Run rela migrate to automatically update your files.

Examples:

# Apply all pending migrations
rela migrate

# Check for migrations without applying (for CI pipelines)
rela migrate --check

CI Integration:

Add to your CI pipeline to ensure project files are up-to-date:

- run: rela migrate --check

This will exit with code 1 if migrations are needed.

rela normalize

Normalize markdown headers in entity files to start at level 2 (##).

rela normalize [type] [flags]

This command adjusts header levels so the minimum header level in each entity is ##, preserving the relative hierarchy. For example:

# Overview → ## Overview

## Details → ### Details

### Subsection → #### Subsection

Setext-style headers (underlined with === or ---) are converted to ATX style (##).

Arguments:

type - Optional: specific entity type to normalize

Flags:

Flag	Description
`--dry-run`	Preview changes without writing

Examples:

rela normalize                # Normalize all entities
rela normalize requirements   # Normalize only requirements
rela normalize req            # Alias works too
rela normalize --dry-run      # Preview changes without writing

rela rename

Rename entity types or entity IDs across the project.

rela rename entity

Rename an entity type across the entire project.

rela rename entity <old-type> <new-type> [flags]

Arguments:

old-type - Current entity type name
new-type - New entity type name

Flags:

Flag	Description
`--plural`	Override plural form for directory name
`-f, --force`	Skip confirmation prompt

This updates:

The entity key in metamodel.yaml
All relation from/to references in metamodel.yaml
All validation entity_type references in metamodel.yaml
The entity directory (e.g., entities/issues/ → entities/tickets/)
The type field in all entity markdown files
Entity templates (if they exist)

Examples:

rela rename entity issue ticket
rela rename entity issue ticket --plural tickets
rela rename entity requirement feature --force

rela rename id

Rename an entity's ID and update all relations that reference it.

rela rename id <old-id> <new-id> [flags]

Arguments:

old-id - Current entity ID
new-id - New entity ID

Flags:

Flag	Description
`--dry-run`	Preview changes without applying

This updates:

The entity file (renamed and id field updated)
All relation files where this entity is the from or to endpoint

Examples:

rela rename id REQ-001 REQ-100
rela rename id REQ-001 REQ-100 --dry-run

rela schema

View the metamodel schema.

rela schema [command] [flags]

Displays information about the loaded metamodel including entity types, relation types, and custom types.

Subcommands:

Command	Description
`overview`	Show metamodel overview (default)
`entities`	List all entity types with descriptions
`relations`	List all relation types
`types`	List custom types defined in metamodel
`entity`	Show details for a specific entity type
`relation`	Show details for a specific relation

Flags:

Flag	Description
`--graphviz`	Output metamodel as GraphViz DOT format
`--constraints`	Include cardinality constraints in DOT output

Examples:

rela schema                    # Overview
rela schema entities           # List entity types
rela schema relations          # List relation types
rela schema types              # List custom types
rela schema entity service     # Detail for one entity type
rela schema relation addresses # Detail for one relation type
rela schema --graphviz         # Output as DOT format
rela schema --graphviz --constraints  # DOT with cardinality

rela gc

Remove orphaned files left behind by interrupted writes.

rela gc [flags]

Attachments are 1:1 with their owning entity — deleting an entity takes its attachments with it, so there is no separate attachment GC pass.

Flags:

Flag	Description
`--temp-files`	Clean up orphaned `.new` files from interrupted writes
`--dry-run`	Show what would be removed without actually removing

Examples:

rela gc --temp-files            # Remove orphaned temp files
rela gc --temp-files --dry-run  # Preview what would be removed

rela validate

Validate project configuration files.

rela validate

Checks metamodel.yaml and data-entry.yaml for:

Unknown/misspelled keys
Invalid cross-references (forms, lists, views)
Invalid entity types, relations, and properties
View traversal correctness
Dashboard and command configuration

Examples:

rela validate

rela version

Print version information.

rela version