Skip to main content
As your archive grows, DMS provides tools to query and analyse the collection without leaving the terminal. dms search filters records across multiple dimensions, dms stats shows collection-level analytics, dms report generates a browsable catalogue, and dms diff compares two records field by field.

​
Searching records

All filters are combined with AND logic — every filter you add narrows the result set further. 
dms search --dir records/ [FILTERS]

​
Available filters

FlagDescription
-t, --typeExact match on heritage type (story, photo, poem, …)
-s, --subjectPartial match on any subject tag
-c, --creatorPartial match on any creator name
-l, --languageExact match on language code (en, sw, rw, fr, …)
--from DATERecords with date.created on or after YYYY-MM-DD
--to DATERecords with date.created on or before YYYY-MM-DD
-q, --queryFree-text search across title, description, and subject
--verboseInclude a description excerpt for each result

​
Search examples

dms search --dir records/ --type poem

​
Reading results

Matching records are shown in a rounded table with columns for filename, title, type, language, and creator. With --verbose, a truncated description (120 characters) is printed beneath the table for each match. 
╭─ Search Results (2 found) ──────────────────────────────────────────────╮
│ File                   Title                  Type   Lang  Creator      │
│ story_b3e7c8a1.json    Journey to Dzaleka…    story  en    Marie Cons…  │
│ audio_d7e8f9a0.json    Traditional Songs…     audio  rw    Espérance N… │
╰─────────────────────────────────────────────────────────────────────────╯
If no records match, the command prints No records matched your search. and exits with code 0.

​
Collection statistics

dms stats --dir records/
dms stats analyses every .json file in the directory and displays:
  • Type distribution — count of records per heritage type
  • Language breakdown — count of records per language code
  • Completion heatmap — which recommended fields (creator, date, subject, location, rights) are filled in across the collection, making it easy to spot gaps
This is useful for understanding the shape of your archive and prioritising metadata improvement work.

​
Generating a catalogue

dms report reads all records in a directory and produces a browsable catalogue you can open locally or host for the community. 
# Default: HTML report saved to records/report.html
dms report --dir records/

# Save to a specific path
dms report --dir records/ --output my_catalogue.html

# Markdown format
dms report --dir records/ --format md

# Markdown with custom title
dms report --dir records/ --format md --output catalogue.md --title "Oral Histories 2024"
OptionDefaultDescription
--dir(required)Directory of DMS records to include
--output<dir>/report.html or <dir>/report.mdOutput file path
--formathtmlOutput format: html or md
--titleDzaleka Heritage CollectionHeading shown at the top of the catalogue

​
Comparing two records

dms diff performs a field-level comparison between two records and highlights what has changed: 
dms diff records/story_v1.json records/story_v2.json
By default, only changed and missing fields are shown. Pass --all to include unchanged fields as well: 
dms diff examples/poem.json examples/story.json --all
This is useful for reviewing edits, comparing drafts, or auditing how a record has changed over time.
dms diff compares field values semantically — it will flag a field that changed from "public" to "restricted" without requiring you to do a line-by-line text diff of the raw JSON.