# Using Gregorio in a terminal

This page is an introduction to working with Gregorio from the command line. It is intended for users who are familiar with using LaTeX and compiling LaTeX documents at the command line. If that is not the case for you, you can start with an editor for TeX documents.

The command line tool `gregorio` converts a score file written in gabc notation into a TeX file. That TeX file contains commands for the GregorioTeX package.

Your LaTeX file incorporates the score into a document by means of the GregorioTeX command `\gregorioscore`. This command takes one or two arguments: The first argument is optional and should be enclosed in square brackets (`[]`) if it is given. This argument is a single letter, `a`, `f`, or `n`, and indicates the compilation behavior that should be observed for this score. The default value of this optional argument can be set with a package option or via a macro specifically designed for this purpose. See the GregorioRef for more details. The second argument is required and is the filename of your gabc score (enclosed in curly braces: `{}`).

Gregorio extensively uses the new features of LuaTeX, so you must compile your TeX files with `lualatex` (for LaTeX documents) or `luatex` (for Plain TeX documents). Also, in order to compile your scores automatically, `lualatex` needs to be able to run external commands. To allow that, run `lualatex` with the `‑‑shell‑escape` switch, or add `gregorio` to the list of commands allowed under restricted command execution: the list is named `shell_escape_commands` in `texmf.cnf`.

Behind the scenes, the automatic compilation (when enabled) creates `myfile-###.gtex` where `myfile` is the base name of your gabc score and `###` is the version of Gregorio.