# Command line reference

This appendix provides the reference to the command line capabilities available when launching &app; from the terminal.

Let us note here that &app; 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!

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

Here is the list of the command line options in &app;:

Format options

  The format of any file destined for import or export can be specified with the `-f` format option. The format can be one of the following:

  gramps

    &app; database. This format is available for both import and export. When not specified, it can be guessed if the filename represents a directory.

  gedcom

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

  gramps-pkg

    &app; package. This format is available for both import and export. When not specified, it can be guessed if the filename ends with .tgz

  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.

Import options

  The files destined for import can be specified with the `-i` 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

gramps
format, the filename is actually the name of directory under which the gramps database resides. For
gedcom
and
gramps-pkg
, the filename is the name of the corresponding file.

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 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

gramps
and
iso
formats, the filename is actually the name of directory the gramps database will be written into. For
gedcom
,
wft
, and
gramps-pkg
, the filename is the name of the resulting file.

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 option. This is done after all imports are successfully completed. Currently available actions are

summary
(same as Reports View Summary) and
check
(same as Tools Database Processing Check and Repair).

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.

## Operation

The order of `-i`, `-o`, or `-a` options with respect to each does not matter. The actual execution order always is: all imports (if any) -> all exports (if any) -> all actions (if any).

If no `-i` option is given, gramps will launch its main window and start the usual interactive session with the empty database (since there is no data to process, anyway).

If no `-o` or `-a` options are given, gramps will launch its main window and start the usual interactive session with the database resulted from all imports. This database resides under ~/.gramps/import directory.

Any errors encountered during import, export, or action, will be either dumped to stdout (if these are exceptions handled by gramps) or or to stderr (if these are not handled). Use usual shell redirections of stdout and stderr to save messages and errors in files.

## Examples

To import four databases (whose formats can be determined from their names) and then check the resulting database for errors, one may type:

`gramps -i` file1.ged `-i` file2.tgz `-i` ~/db3 `-i` file4.wft `-a` check

To explicitly specify the formats in the above example, append filenames with appropriate `-f` options:

`gramps -i` file1.ged `-f` gedcom `-i` file2.tgz `-f` gramps-pkg `-i` ~/db3 `-f` gramps `-i` file4.wft `-f` wft `-a` check

To record the database resulting from all imports, supply `-o` flag (use `-f` if the filename does not allow gramps to guess the format):

`gramps -i` file1.ged `-i` file2.tgz `-o` ~/new-package `-f` gramps-pkg

To save any error messages of the above example into files outfile and errfile, run:

`gramps -i` file1.ged `-i` file2.tgz `-o` ~/new-package `-f` gramps-pkg >outfile 2>errfile

To import three databases and start interactive gramps session with the result:

`gramps -i` file1.ged `-i` file2.tgz `-i` ~/db3

Finally, to start normal interactive session type:

`gramps`