GENEALOGIX

Hands-On CLI Guide ​

This guide walks through every glx command using the Westeros demo archive — a large-scale genealogy of 790+ characters from A Song of Ice and Fire. By the end, you'll know how to validate, query, explore, and export any GLX archive.

Setup ​

Clone the demo archive and install the CLI:

bash
git clone https://github.com/genealogix/glx-archive-westeros.git
cd glx-archive-westeros

If you haven't installed the CLI yet, see the installation instructions.

Archive Health ​

glx validate — Check data integrity ​

Start by validating the archive. This checks YAML syntax, required fields, cross-references between entities, and vocabulary types.

bash
glx validate

The validator reports errors (hard failures) and warnings (soft failures). For a large archive, you'll typically see a few warnings — these flag potential issues without blocking:

text
Validated 4,841 files.
Found 4 errors:
- ❌ duplicate assertions ID: assertion-lysa-death-littlefinger
- ❌ events[event-duel-bran-assassin].Role references non-existent
      participant_roles: target
...
validation failed

TIP

Use glx analyze to check for temporal consistency issues (death before birth, parent younger than child) and other research gaps. Validation focuses on structural correctness.

glx stats — Dashboard overview ​

Get a quick overview of what's in the archive:

bash
glx stats
text
Entity counts:
  Persons:       792
  Events:        986
  Relationships: 822
  Places:        107
  Sources:       11
  Citations:     269
  Repositories:  4
  Media:         0
  Assertions:    1929

Assertion confidence:
  high         1509  ( 78.2%)
  medium        381  ( 19.8%)
  low            39  (  2.0%)

Direct assertion references (entity is an assertion's subject):
  Persons         631/792  (79.7%)
  Events          126/986  (12.8%)
  Relationships   6/822  (0.7%)
  Places          0/107  (0.0%)

Evidence coverage (assertion reachability):
  Includes unsourced or disproven assertions and place ancestors; percentages do not measure sourcing or proof.
  Persons         653/792  (82.4%)
  Events          126/986  (12.8%)
  Relationships   6/822  (0.7%)
  Places          44/107  (41.1%)

This tells you the archive has nearly 800 persons with 1,900+ assertions. The two coverage blocks answer different questions. "Direct assertion references" counts only entities an assertion names as its subject. "Evidence coverage" measures assertion reachability: a person is covered when an assertion names them as a participant or targets an event or relationship they take part in, and a place is covered when an assertion names it as a value (an event's place, a residence), when an asserted event happens there, or when it contains such a place. Every assertion counts, including unsourced or disproven assertions. Place ancestors count as gazetteer scaffolding, so reaching a county also reaches its state and country without independent assertions about them. These percentages measure assertion reach rather than sourcing or proof. Here no assertion targets a place directly, yet 41% of places are reached through asserted events. The remaining gaps in events and places suggest areas for future research.

glx places — Analyze place data quality ​

Check places for data quality issues — duplicates, missing coordinates, hierarchy gaps, and unreferenced places:

bash
glx places
text
Place analysis: 108 places

Duplicate names (ambiguous):
  "The Red Keep" appears 2 times:
    place-red-keep     The Red Keep, King's Landing, The Crownlands, Westeros
    place-the-red-keep The Red Keep, King's Landing, The Crownlands, Westeros

Missing coordinates (108 of 108):
  place-acorn-hall  Acorn Hall, The Riverlands, Westeros
  place-astapor     Astapor, Essos
  ...

Each place is shown with its canonical hierarchy path (e.g., "Winterfell, The North, Westeros"). The duplicate "Red Keep" flags an ID inconsistency to clean up.

glx analyze — Research gap analysis ​

Run automated analysis to surface evidence gaps, quality issues, chronological inconsistencies, and research suggestions:

bash
glx analyze
text
=== Research Gap Analysis: 847 issues found ===

EVIDENCE GAPS (312)
  HIGH person-aegon-i-targaryen       No birth date
  HIGH person-aegon-ii-targaryen      No birth date
  HIGH person-aegon-iii-targaryen     No birth date
  ...

EVIDENCE QUALITY (198)
  HIGH person-aegon-i-targaryen       No assertions backed by citations
  HIGH person-aegon-ii-targaryen      No assertions backed by citations
  ...

CONSISTENCY (5)
  HIGH person-aegon-v-targaryen       Death year (259) before birth year (c. 200)
  ...

SUGGESTIONS (332)
  →   person-arya-stark               Search for vital records
  →   person-benjen-stark             Search for vital records
  ...

Focus on a single person or category:

bash
# Analyze one person
glx analyze "Eddard Stark"

# Run only consistency checks
glx analyze --check consistency

# JSON output for tooling
glx analyze --format json

Which censuses get suggested ​

Census suggestions are tied to the country a person's places name. glx walks each event's place up its parent chain to the first place with type: country, and suggests that country's census years — US federal censuses for someone in Illinois, UK censuses for someone in Bath. A person whose places span a move gets both countries' schedules.

If the country has no schedule in glx (the table currently covers the United States, the United Kingdom, Canada and Ireland), no census is suggested for that person. Suggesting the 1790 US census to someone who never left Mecklenburg is worse than suggesting nothing.

When nothing in the archive names a country for a person — place hierarchies that stop at a city, say — no census is suggested either. glx does not guess a country from silence. Give it one with --country when you know where the archive is rooted:

bash
# Assume UK censuses where the archive names no country
glx analyze --country "United Kingdom"
glx coverage "Jane Webb" --country "United Kingdom"

Adding a type: country place to the hierarchy is the durable fix, since it also tells everyone else reading the archive where these people lived.

The same rules govern the census rows in glx coverage.

glx proof — Structured proof summary for a research question ​

Where glx analyze scans the whole archive for problems, glx proof answers one question about one person and assembles the evidence into a proof argument following the Genealogical Proof Standard (GPS). Supported questions are parentage, birth, death, marriage, and identity:

bash
glx proof "Eddard Stark" --question parentage
text
Proof Summary: Who are the parents of Eddard Stark? (person-eddard-stark)

  Question: Who are the parents of Eddard Stark?

  Evidence Collected:
    1. Histories & Lore of Winterfell (citation-winterfell-lore)
       -> parent_child relationship: existence asserted [confidence: high]
       -> Lists Rickard Stark as father.

  Evidence Gaps:
    [ ] Birth record
    [ ] Church records

  Conflicts: None identified

  Conclusion: PROVEN
    Parents identified: Rickard Stark.

The command gathers every assertion relevant to the question (including assertions on the person's events and relationships), resolves their citations (GPS element 2), draws evidence gaps from the coverage checklist (element 1), flags conflicting assertions and whether they have been resolved via the assertion status field — proven over disproven (element 4), and ends with a conclusion of PROVEN, PROBABLE, POSSIBLE, INSUFFICIENT EVIDENCE, or CONFLICTED (element 5).

bash
# Proof for a death, with Markdown output for a research report
glx proof "Eddard Stark" --question death --format markdown

# JSON output for tooling
glx proof "Eddard Stark" --question parentage --format json

Searching and Querying ​

glx search — Full-text search ​

Search across all entity types at once — useful when you don't know which entity holds the information:

bash
# Find anything mentioning Winterfell
glx search "Winterfell"
text
Found 24 match(es) for "Winterfell":

  Persons (3):
    person-eddard-stark  properties.residence: Winterfell, The North
    person-robb-stark  properties.residence: Winterfell, The North
    person-sansa-stark  properties.residence: Winterfell, The North

  Events (8):
    event-battle-winterfell  title: Battle of Winterfell
    ...

  Places (1):
    place-winterfell  name: Winterfell

Narrow the search to a specific entity type with --type, or use --case-sensitive for exact matching:

bash
# Search only events
glx search "Winterfell" --type events

# Case-sensitive search
glx search "Stark" --case-sensitive

# JSON output for scripting
glx search "Winterfell" --json

glx query persons — Find people ​

List all persons, or filter by name and birth year:

bash
# Find all Starks
glx query persons --name "Stark"
text
  person-arya-stark       Arya Stark  (b. 289)
  person-benjen-stark     Benjen Stark
  person-brandon-stark-bran  Brandon Stark  (b. 290)
  person-eddard-stark     Eddard Stark  (263 – 299)
  person-lyanna-stark     Lyanna Stark  (266 – 283)
  person-robb-stark       Robb Stark  (283 – 299)
  person-sansa-stark      Sansa Stark  (b. 286)
  ...

17 person(s) found

The --name flag searches all name variants — birth names, married names, aliases, and as-recorded forms. You can also filter by birth year:

bash
# Find persons born in the 280s
glx query persons --born-after 280 --born-before 290

glx query events — Find events by type ​

bash
# List all battles
glx query events --type battle
text
  event-battle-blackwater          battle  299
  event-battle-green-fork          battle  298
  event-battle-trident             battle  283
  event-battle-whispering-wood     battle  298
  event-tower-of-joy               battle  283
  ...

25 event(s) found
bash
# All executions
glx query events --type execution
text
  event-execution-brandon-rickard-stark  execution  282
  event-execution-ned-stark              execution  299
  event-execution-janos-slynt            execution  300
  ...

7 event(s) found

glx query relationships — Find connections ​

bash
# Find ward relationships
glx query relationships --type ward
text
  rel-ward-theon-greyjoy-ned-stark  ward
    [person-theon-greyjoy, person-eddard-stark]
  rel-ward-littlefinger-tully  ward
    [person-petyr-baelish, person-hoster-tully]
  rel-ward-frey-grandsons-winterfell  ward
    [person-walder-frey-big-walder, person-walder-frey-little-walder, person-robb-stark]

3 relationship(s) found

glx query assertions — Trace evidence ​

Find assertions by confidence level, source, or citation:

bash
# Low-confidence assertions (legendary figures, disputed identities)
glx query assertions --confidence low
text
  assertion-aegon-vi-blackfyre-theory  persons:person-young-griff
    house=Blackfyre (theoretical)  [low]
  assertion-alleras-sphinx-identity  persons:person-alleras-the-sphinx
    alias=Possibly Sarella Sand  [low]
  assertion-bran-built-wall  persons:person-bran-the-builder
    role=Builder of the Wall  [low]
  ...

37 assertion(s) found
bash
# All assertions from A Game of Thrones
glx query assertions --source source-agot

This returns every fact that traces back to the first novel — useful for auditing which sources support which claims.

Person Exploration ​

glx vitals — Quick vital records ​

Look up a person's key life data:

bash
glx vitals "Eddard Stark"
text
Vitals for person-eddard-stark:

  Name         Eddard Stark
  Sex          male
  Birth        263, Winterfell
  Christening  —
  Death        299, Great Sept of Baelor
  Burial       —
  Battle       283, Stoney Sept
  Battle       283, The Trident
  Coronation   283, King's Landing
  Execution    299, Great Sept of Baelor
  Rebellion    289, Pyke
  Tournament   298, King's Landing
  Trial        298, The Red Keep
  Rebellion    BET 282 AND 283, Westeros
  Tournament   281, Harrenhal
  Battle       283, Tower of Joy

You can use a person ID or a name substring — if multiple persons match, all matches are listed for disambiguation.

glx timeline — Chronological events ​

See every event in a person's life in chronological order, including family events discovered through relationships:

bash
glx timeline "Eddard Stark"

The timeline includes direct events (battles, coronations, trials) and family events like children's births and deaths, discovered by traversing relationships. Use --no-family to show only direct events:

bash
glx timeline "Eddard Stark" --no-family

glx migrations — Geographic movement ​

Trace where a person was over time and when they moved. Observations come from the person's events, their children's birth events (a child's birthplace is evidence of the parent's residence), and residence property values; each change of place is reported as a movement, named at the highest level where the two places differ (two states, or two villages of one district). A parent named on a child's burial is shown but not counted, since the burial places the child:

bash
glx migrations "Eddard Stark"

Migration patterns are evidence: people who made the same move at the same time are often kin. Search the whole archive for everyone who moved between two places, in order:

bash
glx migrations --pattern "Winterfell,King's Landing"

Use --family to also print timelines for the person's immediate family, and --format json for machine-readable output.

glx summary — Full person profile ​

Get a comprehensive profile with identity, vital events, life events, family, relationships, and an auto-generated life history:

bash
glx summary "Eddard Stark"
text
=== person-eddard-stark ===

  Name:             Eddard Stark
  Sex:              male

── Vital Events ──────────────────────────────────
  Birth:            263, Winterfell
  Death:            299, Great Sept of Baelor

── Life Events ───────────────────────────────────
  Battle:           283, Stoney Sept
  Battle:           283, The Trident
  Coronation:       283, King's Landing
  ...
  Alias:            Ned
  Alias:            The Quiet Wolf
  House:            Stark
  Title:            Lord of Winterfell (FROM 280 TO 299)
  Title:            Warden of the North (FROM 280 TO 299)
  Title:            Hand of the King (FROM 298 TO 298)

── Family ────────────────────────────────────────
  Spouse:           Catelyn Tully
  Mother:           Flint
  Father:           Rickard Stark
  Siblings:         Benjen Stark, Brandon Stark, Lyanna Stark

── Relationships ─────────────────────────────────
  King:             Robert Baratheon I
  Ward:             Theon Greyjoy

── Life History ──────────────────────────────────
  Eddard Stark was born in 263 in Winterfell. He was the child of
  Flint and Rickard Stark. He married Catelyn Tully. He died in 299
  in Great Sept of Baelor.

The life history narrative is auto-generated from the structured data — a starting point that you can replace with a hand-written narrative in the person's notes field.

Family Trees ​

glx ancestors — Ancestor tree ​

Display the ancestor tree for a person using box-drawing characters:

bash
glx ancestors person-robb-stark --generations 3
text
Robb Stark  (283 – 299)  person-robb-stark
├── Catelyn Tully  (264 – 299)  person-catelyn-tully
│   ├── Hoster Tully  (d. 299)  person-hoster-tully
│   │   └── Tully  person-tully
│   └── Minisa Whent  (d. BEF 300)  person-minisa-whent
└── Eddard Stark  (263 – 299)  person-eddard-stark
    ├── Flint  person-flint
    └── Rickard Stark  person-rickard-stark
        └── Edwyle Stark  person-edwyle-stark

Use --generations to limit depth (0 for unlimited). The tree traverses all parent-child relationship variants — biological, adoptive, foster, and step-parent.

glx descendants — Descendant tree ​

bash
glx descendants person-rickard-stark --generations 3
text
Rickard Stark  person-rickard-stark
├── Benjen Stark  person-benjen-stark
├── Brandon Stark  (d. BEF 300)  person-brandon-stark-213
├── Eddard Stark  (263 – 299)  person-eddard-stark
│   ├── Arya Stark  (b. 289)  person-arya-stark
│   ├── Brandon Stark  (b. 290)  person-brandon-stark-bran
│   ├── Jon Snow  (b. 283)  person-jon-snow
│   ├── Rickon Stark  (b. 295)  person-rickon-stark
│   ├── Robb Stark  (283 – 299)  person-robb-stark
│   └── Sansa Stark  (b. 286)  person-sansa-stark
└── Lyanna Stark  (266 – 283)  person-lyanna-stark
    └── Jon Snow  (b. 283)  person-jon-snow

Notice Jon Snow appears under both Eddard Stark and Lyanna Stark — the tree correctly traverses all parent-child relationships, revealing R+L=J through the data structure itself.

Relationship Paths ​

glx path — Shortest path between two people ​

Find how two people are connected through the relationship graph:

bash
glx path "Arya Stark" "Jon Snow"
text
Path from person-arya-stark to person-jon-snow (2 hop(s)):

  Arya Stark (person-arya-stark)
    - child in parent child ->
  Eddard Stark (person-eddard-stark)
    - parent in parent child ->
  Jon Snow (person-jon-snow)

The command uses breadth-first search across all relationship types — parent-child, marriage, sibling, betrothal, ward, and any other relationship in the archive. Try a path that crosses family boundaries:

bash
glx path "Robb Stark" person-lysa-tully
text
Path from person-robb-stark to person-lysa-tully (2 hop(s)):

  Robb Stark (person-robb-stark)
    - child in parent child ->
  Catelyn Tully (person-catelyn-tully)
    - sibling in sibling ->
  Lysa Tully (person-lysa-tully)

Use --max-hops to limit the search depth, and --json for machine-readable output:

bash
glx path "Sansa Stark" "Joffrey Baratheon" --max-hops 5 --json

Citations ​

glx cite — Generate citation text ​

Generate formatted citation text from structured citation data:

bash
# Format a specific citation
glx cite citation-agot-eddard-xv
text
"A Game of Thrones", novel, A Song of Ice and Fire (Novels) (2026-03-06),
  Eddard XV.
bash
# Format all citations in the archive
glx cite

This assembles each citation from its source title, source type, repository name, access date, and locator — saving you from writing citation_text by hand for each of 247 citations.

FAN Club Analysis ​

glx cluster — Find associates for brickwall research ​

When you hit a brickwall, the FAN (Friends, Associates, Neighbors) club technique can uncover new leads. The cluster command identifies people connected to a person through census households, shared events, and place overlap, ranked by connection strength:

bash
glx cluster person-eddard-stark

Associates are scored by how they connect: census co-residence is worth 3 points, a census page neighbor or shared event participation 2 points, and place overlap 1 point. The stronger the connection, the higher the score. Page neighbors come from the neighbors list on census events (see glx households under Adding Census Records below); only neighbors linked to a person can be scored.

Narrow the results to a specific place and time period:

bash
glx cluster person-eddard-stark --place place-winterfell --before 1300

This filters to only associates connected through events at Winterfell before the year 1300 — useful for isolating a specific community at a specific time.

Use --json for scripting or piping into other tools:

bash
glx cluster person-eddard-stark --json

TIP

The FAN club technique is most powerful when combined with glx timeline and glx query assertions. Find the associates, then check the timeline and evidence chains to understand how they were connected.

Logging Research ​

glx add research-log, glx add search, glx add study — Record searches as you go ​

A research log records every search you make, including the ones that found nothing. That negative evidence is what shows a "reasonably exhaustive search", and it stops you repeating a fruitless query next session. Open a log once, then append one search per lookup:

bash
# Open a log about a person
glx add research-log --id rl-jon-snow-mother --subject-person person-jon-snow \
  --objective "Identify Jon Snow's mother" --status in_progress

# Append searches as you make them
glx add search --log rl-jon-snow-mother --collection "Winterfell household rolls" \
  --query "Snow, 280-284" --result not_found --date 2026-09-17

glx add search --log rl-jon-snow-mother --collection "Tower of Joy accounts" \
  --result not_searched --note "Next session"

Each add search validates --result against the archive's search_result_types vocabulary, checks that --source, --repository and --citation exist, and rewrites only the log's own file. A --citation is also rolled up into the log's citations list.

A study sets the scope of a larger project:

bash
glx add study --title "Stark household, 260-300 AC" --type family_reconstruction \
  --status active --place place-winterfell --date-range "FROM 260 TO 300"

Adding Census Records ​

glx census add — Bulk census import from a template ​

When you find a household on a census, census add lets you transcribe it once in a simple YAML template and generate all the GLX entities — persons, events, sources, citations, places, and assertions — in one step.

Create a census template file (e.g., 1860-census-stark.yaml):

yaml
census:
  year: 260
  location:
    place: "Winterfell"
  source:
    title: "260 Census of the North"
  citation:
    locator: "Roll 3, Page 12"
  household:
    members:
      - name: "Rickard Stark"
        age: 35
        sex: male
        occupation: Lord
        birthplace: Winterfell
      - name: "Lyarra Stark"
        age: 30
        sex: female
        birthplace: Winterfell

Preview what would be generated:

bash
glx census add --from 1860-census-stark.yaml --archive . --dry-run
text
Census Import Summary
=====================
  Event:      event-260-census-winterfell-stark
  Source:     source-260-census-winterfell
  Citation:   citation-260-census-winterfell-stark
  Place:      place-winterfell

  Matched existing persons (2):
    = person-rickard-stark
    = person-lyarra-stark

  New places:     0
  New sources:    1
  Assertions:     10

(dry run — no files written)

Notice it matched Rickard and Lyarra Stark to existing archive persons by name — no person_id needed.

census.source.title is optional. Left out, the title is built from the year, the census.type and the location — type: federal gives "1860 Federal Census — Marion County, Florida", and no type at all gives "1860 Census — …". The country is never assumed: put it in source.title when you want it named. When you're satisfied, run without --dry-run:

bash
glx census add --from 1860-census-stark.yaml --archive .

The generated assertions include:

  • Birth year (ABT, low confidence) — estimated from age
  • Birthplace (medium confidence) — resolved against existing places
  • Sex (high confidence) — directly stated
  • Occupation (high confidence, dated) — directly stated
  • Residence (high confidence, dated) — enumerated at this place

Each assertion cites the census citation, building a proper evidence chain from source to conclusion.

TIP

Use household.neighbors to record the households enumerated next to this one (name, optional person, position such as previous_household, page, line). They are written to the census event's neighbors list, shown by glx households --neighbors, and counted by glx cluster when linked to a person. The older free-text fan.notes field still works and becomes an event note.

Head-only schedules (1790–1840) ​

Before 1850 the US census named only the head of household; everyone else is a tick mark in an age-and-sex column. Record the columns under household.tally, and add any household member you have identified with a tick mark with named: false:

yaml
census:
  year: 1820
  type: federal
  location:
    place_id: place-wythe-county-va
  household:
    members:
      - name: "James Little"
        person_id: person-james-little
        role: principal
      - name: "Elizabeth Starr"
        person_id: person-elizabeth-starr
        named: false
      - name: "Mary Little"
        person_id: person-mary-little
        named: false
    tally:
      - { sex: male, age_from: 45, count: 1, status: free white }
      - { sex: female, age_from: 45, count: 1, status: free white }
      - { sex: female, age_from: 10, age_to: 15, count: 2, status: free white }
      - { count: 1, status: engaged in agriculture }

Bracket bounds are inclusive: "of 10 and under 16" is age_from: 10, age_to: 15; leave out age_from for "under N" and age_to for "N and upwards". The first member must be named. A named: false member gets role household_member and only a low-confidence residence assertion, since the schedule states nothing about them individually (age, birthplace, occupation, and properties are rejected for such a member; the bracket goes in the tally). They count as found in that census: glx analyze stops suggesting it and glx coverage ticks it.

glx households — Reconstruct census households ​

households shows each census household a person appears in, head first and the rest by age:

bash
glx households person-mary-little
text
Households for Mary Little (person-mary-little):

  1820 Census — Little Household — Wythe County, Virginia  [event-1820-census-little]
    James Little (person-james-little) — head
    Elizabeth Starr (person-elizabeth-starr) — household member, counted, not named
    Mary Little (person-mary-little) — household member, counted, not named
    Tally (as enumerated):
      1 male 45+ (free white)
      1 female 45+ (free white)
      2 female 10–15 (free white)
      1 engaged in agriculture

List every household enumerated at a place (including places inside it) in one year, add the page neighbors, or get JSON:

bash
glx households --place place-wythe-county-va --year 1820
glx households person-mary-little --neighbors
glx households person-mary-little --format json

Format Conversion ​

glx split and glx join — Convert between formats ​

Convert a single-file archive to multi-file or vice versa:

bash
# Join a multi-file archive into a single file
glx join . westeros-combined.glx

# Split it back out
glx split westeros-combined.glx westeros-expanded/

glx export — Export to GEDCOM ​

Export the archive to GEDCOM format for use with traditional genealogy software:

bash
# Export to GEDCOM 5.5.1 (most compatible)
glx export . -o westeros.ged

# Export to GEDCOM 7.0
glx export . -o westeros.ged --format 70

The exporter reconstructs GEDCOM FAM records from GLX relationships, converts dates and places back to GEDCOM format, and preserves sources, citations, and notes.

WARNING

GEDCOM is a simpler format than GLX. Custom vocabularies (like battle, coronation, ward) will be exported as generic event/relationship types. Evidence chains are preserved as SOUR citations but lose the structured assertion model.

When reviewing FamilySearch records, transcribing the URL, accessed date, and ARK identifier into a new citation for every record is repetitive. glx link writes that boilerplate for you:

bash
# Attach to an existing source in your archive
glx link "https://www.familysearch.org/ark:/61903/1:1:C4H8-2DW2" \
  --archive . \
  --source source-deutschland-geburten-taufen \
  --text "Johann Peter Jungk, 1725"

# Or create a new source at the same time
glx link "https://www.familysearch.org/ark:/61903/1:1:C4H8-2DW2" \
  --archive . \
  --create-source "Deutschland Geburten und Taufen, 1558-1898"

# Preview without writing
glx link "ark:/61903/1:1:C4H8-2DW2" --archive . \
  --source source-fs-index --dry-run

The command:

  • Validates the ARK (full URL, URL without www, or bare ark:/61903/... all work)
  • Creates repository-familysearch if your archive doesn't already have it (skipped otherwise — your customizations are preserved)
  • Uses the --source you point at, or mints a new source with --create-source <title>
  • Writes a citation with the canonical URL, today's date as accessed, and the ARK as a structured external_ids entry whose fields.type matches GEDCOM 7 EXID import (https://www.familysearch.org/ark:/61903/). This keeps FS-imported GEDCOM files and glx link-generated citations format-compatible.
  • Is idempotent: running it twice with the same ARK is a no-op.

This is an offline MVP — glx link does not fetch anything over the network. The larger #87 scope (OAuth PKCE, GEDCOM X JSON extraction, automatic person/event/relationship import from the record) is tracked as follow-up work.

Archive Merging ​

glx merge — Combine two archives ​

When collaborating with other researchers or consolidating separate research branches, glx merge combines a source archive into a destination:

bash
# Merge cousin's research into your main archive
glx merge cousin-research/ --into my-family-archive/

# Preview what would be merged, including cross-archive duplicate detection
glx merge cousin-research/ --into my-family-archive/ --preview

The command copies all entities from the source into the destination. Duplicate entity IDs are reported and skipped (the destination version is kept). Both single-file and multi-file archives are supported.

TIP

Run glx merge <source> --into <dest> --preview first to see what would change. Then glx validate after merging to verify the combined archive is clean.

Migration ​

glx migrate — Convert deprecated properties to events ​

If you have an archive that uses the deprecated born_on/born_at/died_on/died_at/buried_on/buried_at person properties, glx migrate converts them to birth/death/burial Event entities:

bash
# Run the migration on the current directory
glx migrate .

The command creates birth/death/burial events from the property values, converts any assertions that referenced those properties to target the new events, and removes the deprecated properties. If a birth/death/burial event already exists for the person, the date and place are merged into it.

What to Try Next ​

Now that you've explored the Westeros archive, try these on your own data:

  1. Import a GEDCOM file: glx import family.ged -o family-archive — see the Migration Guide
  2. Create an archive from scratch: glx init my-archive — see the Quickstart
  3. Add custom vocabularies: Define domain-specific event types and relationship types for your research
  4. Track evidence: Build assertion chains from sources through citations to conclusions

See Also ​

Licensed under Apache License 2.0

Copyright © 2025-2026 Oracynth, Inc.