.docname {CLI - Options}
.include {docs}

This page lists all the options available for the [compiler](cli-compiler.qd) and REPL.

## Compiler options

Running **`quarkdown c file.qd`** compiles the given file and saves the output to file.

> [!NOTE]
> If the project is composed of multiple source files, the target file must be the root one, i.e. the one that [includes](including-other-quarkdown-files.qd) the other files.

### Preview and watch

- **`-p`** or **`--preview`**: enables automatic content reloading after compiling.
  If a [webserver](cli-webserver.qd) is not running yet, it is started and the document is opened in the default browser.
  This is required in order to render paged documents in the browser.

- **`-w`** or **`--watch`**: recompiles the source every time a file from the source directory is changed.

- `-b <browser>` or `--browser <browser>`: sets the browser to launch the preview with. Defaults to `default`. Accepted values:
  - `default`
  - `none`
  - `xdg` (uses `xdg-open`). `default` falls back to this.
  - `chrome`
  - `chromium`
  - `firefox`
  - `edge` (Windows only)
  - Any other name, backed by the `BROWSER_<NAME>` environment variable
  - A full path to a browser executable

- `--server-port <port>`: optional customization of the local [webserver](cli-webserver.qd)'s port. Defaults to `8089`.

> [!TIP]
> Combine `-p -w` to achieve **live preview**.

### Output

- **`--pdf`**: produces a PDF file. Learn more in the [PDF export](pdf-export.qd) page.

- `-o <dir>` or `--out <dir>`: sets the directory of the output files. Defaults to `./quarkdown-output`.

- `--out-name <name>`: sets the name of the output resource to be saved inside the output directory.
  Defaults to the name of the document, set via [`.docname`](document-metadata.qd).
  Special characters will be replaced with dashes in the actual file name.

- `-r <renderer>` or `--render <renderer>`: sets the target renderer. Defaults to `html`. Accepted values:
  - `html`
  - `html-pdf` (equivalent to `-r html --pdf`)
  - `text` (plain text)

### Permissions

- `--allow <permission>` / `--deny <permission>`: grants or revokes a [permission](cli-compiler.qd#permissions) (repeatable).
  Accepted values: `project-read`, `global-read`, `network`, `native-content`, `process`, `all`.
  By default, `project-read` and `native-content` are granted.

### Libraries

- `-l <dir>` or `--libs <dir>`: sets the directory where external libraries can be loaded from. Defaults to `<install dir>/lib/qd`.
  Learn more in the [external libraries](importing-external-libraries.qd) page.

### Other options

- `--pipe`: outputs the generated content to stdout instead of saving it to file and suppresses other logs,
  useful for piping to other commands.

- `--clean`: deletes the content of the output directory before producing new files. **Destructive operation.**

- `--strict`: forces the program to exit if an error occurs. When not in strict mode, errors are shown as boxes in the document.

- `--nowrap`: prevents the rendered output from being wrapped in a full document structure.
  If enabled in HTML rendering, only the inner content of the `<body>` tag is produced.

- `--pretty`: produces pretty output code. This is useful for debugging or to read the output code more easily,
  but it should be disabled in production as the results might be visually affected.

- `--timeout <seconds>`: sets the maximum time, in seconds, allowed for the entire execution to complete.
  `0` disables the timeout. Defaults to 30 seconds.

- `--no-media-storage`: turns the [media storage](media-storage.qd) system off.

- `--forbid-function-overwriting`: raises a compilation error when a [function is declared](declaring-functions.qd#overwriting-functions) with a name that is already in use, instead of silently overwriting the previous definition.

- `--subdoc-naming <strategy>`: sets the [subdocument](subdocuments.qd) output naming strategy. Defaults to `file-name`. Accepted values:
  - `file-name`: uses the subdocument's file name (human-readable, but prone to collisions)
  - `collision-proof`: appends a hash to `file-name` to minimize name collisions
  - `document-name`: uses the document name set via `.docname`, falling back to `file-name` if unset

- `-Dloglevel=<level>` (JVM property): sets the log level. If set to `warning` or higher, the output content is not printed out.
