Appendix D. Command line reference
Prev   Next

Appendix D. Command line reference

Table of Contents

Available options
Format options
Opening options
Import options
Export options
Action options
Operation
Examples

This appendix provides the reference to the command line capabilities available when launching GRAMPS from the terminal.

[Note]Note

GRAMPS was designed to be an interactive program. Therefore it uses graphical display and cannot run from the true non-graphical console. It would take an enormous amount of effort to enable it to run in a text-only terminal. This is why the set of command line options does not aim to completely get rid of dependency on the graphical display. Rather, it merely makes certain (typical) tasks more convenient. It also allows one to execute these tasks from the scripts. However, the graphical display must be accessible at all times!

[Tip]Tip

To summarize, the use of the command line options provides non-interactive behavior, but does not get rid of graphical display dependency. Take it or leave it!

Available options

This section provides the reference list of all command line options available in GRAMPS. If you want to know more than just a list of options, see next sections: the section called “Operation” and the section called “Examples”.

Format options

The format of any file destined for opening, importing, or exporting can be specified with the -f format option. The acceptable format values are listed below.

grdb

GRAMPS database. This format is available for opening, import, and export. When not specified, it can be guessed if the filename ends with .grdb

gramps-xml

GRAMPS XML database. This format is available for opening, import, and export. When not specified, it can be guessed if the filename ends with .gramps

gedcom

GEDCOM file. This format is available for opening, import, and export. When not specified, it can be guessed if the filename ends with .ged

gramps-pkg

GRAMPS package. This format is available for import and export. When not specified, it can be guessed if the filename ends with .gpkg

geneweb

GeneWen file This format is available for import and export. When not specified, it can be guessed if the filename ends with .gw

wft

Web Family Tree. This format is available for export only. When not specified, it can be guessed if the filename ends with .wft

iso

CD image. This format is available for export only. It must always be specified explicitly.

Opening options

There are two ways to give GRAMPS the name of the file to be opened:

  • supply bare file name

  • use the -O filename or -open=filename option

If the filename is given without any option flag, the attempt to open the file will be made, and then the interactive GRAMPS session will be launched.

[Tip]Tip

If no option is given, just the file name, GRAMPS will ignore the rest of the command line arguments. Use the -O flag to open the file and do something with the data.

The format can be specified with the -f format or --format=format option, immediately following the filename. If not specified, the guess will be attempted based on the filename.

[Tip]Tip

Only grdb, gramps-xml, and gedcom formats can be opened directly. For other formats, you will need to use the import option which will set up the empty database and then import data into it.

[Tip]Tip

Only a single file can be opened. If you need to combine data from several sources, you will need to use the import option.

Import options

The files destined for import can be specified with the -i filename or --import=filename option. The format can be specified with the -f format or --format=format option, immediately following the filename. If not specified, the guess will be attempted based on the filename.

[Tip]Tip

More than one file can be imported in one command. If this is the case, GRAMPS will incorporate the data from the next file into the database available at the moment.

When more than one input file is given, each has to be preceded by -i flag. The files are imported in the specified order, i.e. -i file1 -i file2 and -i file2 -i file1 might produce different GRAMPS IDs in the resulting database.

Export options

The files destined for export can be specified with the -o filename or --output=filename option. The format can be specified with the -f option immediately following the filename. If not specified, the guess will be attempted based on the filename. For iso format, the filename is actually the name of directory the GRAMPS database will be written into. For grdb, gramps-xml, gedcom, wft, geneweb, and gramps-pkg, the filename is the name of the resulting file.

[Tip]Tip

More than one file can be exported in one command. If this is the case, GRAMPS will attempt to write several files using the data from the database available at the moment.

When more than one output file is given, each has to be preceded by -o flag. The files are written one by one, in the specified order.

Action options

The action to perform on the imported data can be specified with the -a action or --action=action option. This is done after all imports are successfully completed.

Currently available actions are:

summary

This action is the same as Reports → View → Summary

check

This action is the same as Tools → Database Processing → Check and Repair.

report

This action allows producing reports from the command line. As reports generally have many options of their own, this action should be followed by the report option string. The string is given using the -p option_string or --options=option_string option.

[Tip]Tip

The report option string should satisfy the following conditions:

  • It must not contain any spaces. If some arguments need to include spaces, the string should be enclosed with quotation marks.

  • Option string must list pairs of option names and values.

  • Within a pair, option name and value must be separated by the equal sign.

  • Different pairs must be separated by commas.

Most of the report options are specific for every report. However, there some common options.

name=report_name

This mandatory option determines which report will be generated. If the supplied report_name does not correspond to any available report, the error message will be printed followed by the list of available reports.

show=all

This will produce the list of names for all options available for a given report.

show=option_name

This will print the description of the functionality supplied by the option_name, as well as what are the acceptable types and values for this option.

Use the above options to find out everything about a given report.

[Tip]Tip

If an option is not supplied, the last used value will be used. If this report has never been generated before, then the value from last generated report will be used when applicable. Otherwise, the default value will be used.

When more than one output action is given, each has to be preceded by -a flag. The actions are performed one by one, in the specified order.

Prev   Next
Miscellaneous filters Home Operation