On Reddit.com/r/gramps, a user was unable discover any documentation about whether there is a CLI method to a export a CSV file of a filtered Tree?
I described the GUI options but didn’t have an answer of whether it was possible from the Command Line Interface.
The wiki page for the Gramps command line doesn’t show any option to apply a filter.
If the user’s intent is to export databases in a loop for many people, and if there is no CLI option, they may consider using Windows Power Automate if they are a Windows user. It has a bit of a learning curve, but with a little experimentation I was able to get it to run >1000 repeated operations in an application (not Gramps). Once I had it working, I let it run overnight and it did the job saving me hours of picking and clicking monotony.
Burned some free GitHub Claude time with the following prompt:
please examine the Gramps CLI modules at https://github.com/gramps-project/gramps/tree/master/gramps/cli and the attached user documentation. Determine if there are major features that should be added to the user documentation. Is there any Export capabilities that is missing? In particular, applying filters to the export and selecting CSV as an exporting format.
Let me fetch the actual Gramps source files directly:Now let me look at the actual export plugin source to understand what export options are available via CLI:Now I have enough to give a thorough analysis. Let me compile my findings.
Here is a detailed gap analysis comparing the Gramps 6.0 CLI documentation (the uploaded PDF) against what the source code actually supports:
This is the most significant omission. The documentation’s Export options section describes only the -e flag and file format codes. It says nothing about the Export Proxy system, which is the primary mechanism for controlling what data gets exported.
The source (gramps/gui/plug/export/WriterOptionBox) and the export.proxy-order config key (which does appear in the -s / --show output reproduced in the same document) expose five proxies that can be configured for any CLI export:
| Proxy | Config key | What it does |
|---|---|---|
| Privacy | export.proxy-order 'privacy' |
Strips records marked private |
| Living | export.proxy-order 'living' |
Restricts or removes living-person data |
| Person | export.proxy-order 'person' |
Applies a named custom person filter |
| Note | export.proxy-order 'note' |
Applies a named custom note filter |
| Reference | export.proxy-order 'reference' |
Excludes records not linked to selected persons |
The documentation shows export.proxy-order=[['privacy', 0], ['living', 0], ['person', 0], ['note', 0], ['reference', 0]] appearing in the gramps --show example output but never explains what these values mean, what the integer values (enabled/disabled flags) represent, or how to change them via --config before an export. A CLI user who wants to produce a privacy-filtered GEDCOM has no documented path to do so.
What should be added:
A new subsection under “Export options” explaining:
--config immediately before exporting, e.g.:# Export a GEDCOM excluding all private records and all living people
gramps -O "Family Tree 1" \
-c export.proxy-order:"[['privacy',1],['living',1],['person',0],['note',0],['reference',0]]" \
-e public_export.ged -f ged
LivingProxyDb modes: MODE_INCLUDE_ALL, MODE_EXCLUDE_ALL, MODE_INCLUDE_LAST_NAME_ONLY, MODE_INCLUDE_FULL_NAME_ONLY) and which config key controls that modeexport.person-filter)The document lists csv as a valid format code under “Subset of your data” with only one sentence: “Be careful however, import must be as values created by the export function. Only a part of your data is contained in the output.”
There is no mention of:
Person, Lastname, Firstname, Callname, Suffix, Prefix, Title, Gender, Birthdate, Birthplace, Birthsource, Baptismdate …). The 5.1 manual has a full dedicated page for this (Gramps_5.1_Wiki_Manual_-_Manage_Family_Trees:_CSV_Import_and_Export) but the 6.0 CLI page does not link to it, nor does it clarify CSV’s limitations (notes are never exported, sources are never exported, etc.).gramps -O "Family Tree 1" -e export.csv -f csv-r / --remove Option — Completely Missing from the Body TextThe help output listed in the document includes -r, --remove=FAMILY_TREE_PATTERN Remove matching Family Tree(s) (use regular expressions), but there is no body-text section explaining it, no caveats about it being destructive, no example, and no mention of whether -y / --yes is required to suppress the confirmation prompt. This is a data-loss risk if misused.
-C / --create Option — Underdocumented-C, --create=FAMILY_TREE Create on open if new Family Tree appears in the help listing but is never explained in the body text. Its use pattern (creating a new tree as part of an import pipeline) is not illustrated with an example.
-U / -P) — No Documentation at All-U, --username=USERNAME and -P, --password=PASSWORD appear in the help listing (they are used for PostgreSQL/network backends) but are never explained anywhere in the document. There is no mention of which backend they apply to, security considerations about password on the command line, or whether they interact with --create.
-Z Subcommand for --default — MissingThe Defaults section documents subcommands A, F, P, X, and E but omits Z (delete old .zip upgrade files), which is listed in the 5.1 and 5.2 manuals.
--load-modules — Completely Undocumented--load-modules=MODULE1,MODULE2,... appears in the usage header but is never explained anywhere in the document. There is no description of what dynamic modules are, where they live, or a use case.
The text correctly states “more than one file can be exported in one command” but provides no concrete example. A useful addition would be:
# Export simultaneously to both GEDCOM and Gramps XML
gramps -O "Family Tree 1" \
-e backup.gramps -f gramps \
-e share.ged -f ged
Plugins_Command_Line Wiki Page — Needs Cross-LinkThe wiki has a stub page at Gramps:Plugins_Command_Line covering per-plugin CLI options. The CLI manual should link to it, especially given the complexity of report and tool action options.
| Gap | Severity | Notes |
|---|---|---|
| Export proxy/filter system not documented | High | Core privacy and filtering capability invisible to CLI users |
| CSV export format not described in CLI doc | Medium | Users don’t know what they’ll get |
-r / --remove undocumented |
High | Destructive operation with no explanation |
-C / --create undocumented |
Medium | Common pipeline pattern |
-U / -P credentials undocumented |
Medium | PostgreSQL backend users have no guidance |
-Z default subcommand missing |
Low | Minor omission |
--load-modules undocumented |
Low | Niche but present in the help text |
| Multi-file export example missing | Low | Helpful but implied |
The export proxy/filter system is by far the most impactful gap. A CLI user automating nightly backups or publishing a filtered public GEDCOM has no documented way to discover that privacy and living-person filtering are available, let alone how to configure them without opening the GUI first. The fact that export.proxy-order appears in the --show sample output in the same document without any explanation makes the omission particularly jarring.
There’s a long-standing feature request for using filters from the command line:
Claude claims that it existed but was not documented.
I am not inclined to do CLI experimentation. But had Claude integrate the missing documentation in MediaWiki markdown and pasted that content into the ‘discussion’ tab for the wiki page. If someone wants to validate that there’s no hallucinating and update the main page, that’d would be great.
As for using the CLI to apply filters during export, see: