dangerzone-cli¶

dangerzone-cli converts one or more documents into safe PDFs from a terminal. It uses the same conversion pipeline and the same sandbox as the graphical application. For a guided introduction, see Convert documents from the command line.

Location¶

Platform	Command
Linux	`dangerzone-cli`
macOS	`/Applications/Dangerzone.app/Contents/MacOS/dangerzone-cli`
Windows	`C:\Program Files\Dangerzone\dangerzone-cli.exe`
Source tree	`poetry run dangerzone-cli`

Usage¶

The output below is generated from the code at the time the documentation was built, so it matches the installed version of the same release.

Usage: dangerzone-cli [OPTIONS] [FILENAMES]...

  Convert potentially dangerous documents to safe PDFs.

  Documents are converted inside a sandbox, so that any embedded threats are
  neutralized. You can also use OCR to add a searchable text layer to the safe
  PDF, via the --ocr-lang option.

  Pass one or more file paths as arguments, or use '-' to read a document from
  standard input. For single-document conversions, you can write the safe PDF
  to a file with '-o <file>', or to standard output with '-o -'.

  Examples:

      dangerzone-cli evidence.odt                  # convert to 'evidence-safe.pdf'
      dangerzone-cli doc1.pdf doc2.docx            # convert to 'doc1-safe.pdf' and 'doc2-safe.pdf'
      dangerzone-cli --archive report.docx         # convert to 'report-safe.pdf' and move the original under './unsafe/'
      dangerzone-cli --ocr-lang eng scan.pdf       # add a searchable text layer in English
      dangerzone-cli -o out.pdf in.pdf             # write to 'out.pdf'
      dangerzone-cli -o - in.pdf > out.pdf         # write to stdout and pipe to 'out.pdf'
      dangerzone-cli - -o out.pdf < in.pdf         # read from stdin and write to 'out.pdf'
      dangerzone-cli - -o - < in.pdf > out.pdf     # read from stdin, write to stdout and pipe to 'out.pdf'

Options:
  -o, --output-filename TEXT    Output filename for the safe PDF. Default is
                                the input filename with '-safe.pdf' appended.
                                Alternatively, use '-' to write the safe PDF
                                to standard output.
  --ocr-lang TEXT               Language to OCR, defaults to none
  --archive                     Archives the unsafe version in a subdirectory
                                named 'unsafe'
  --debug                       Run Dangerzone in debug mode, to get logs from
                                gVisor.
  --set-container-runtime TEXT  The name or full path of the container runtime
                                you want Dangerzone to use. You can specify
                                the value 'default' if you want to take back
                                your choice, and let Dangerzone use the
                                default runtime for this OS
  --linger                      Do not stop the Podman machine VM that
                                Dangerzone uses to run containers, after the
                                conversions have completed. This is useful if
                                you want to run multiple conversions in a row,
                                since the startup of the VM takes some time.
                                If you choose to let the Podman machine
                                linger, you will need to stop it manually with
                                `dangerzone-machine stop`. This option affects
                                only Windows/macOS platforms.
  --version                     Show the version and exit.
  --help                        Show this message and exit.

FILENAMES... are the documents to convert. Every file must exist and must have one of the supported formats. Conversions run sequentially, in the given order. --output-filename is only valid with a single input file, and the name must end with .pdf. --set-container-runtime stores the choice in the settings file and exits without converting anything, see Using Podman Desktop.

Behaviour¶

On start, the tool prints a banner and then, when needed, installs the Windows Subsystem for Linux, stops other Podman machines, initializes and starts the Dangerzone Podman machine, checks for updates, and installs the sandbox image. On Linux, none of the machine steps apply. On Qubes OS with the native integration, conversions run in disposable qubes.

Slim Linux packages

On Linux, the dangerzone package doesn't come with the sandbox bundled, and so the CLI does not download the sandbox on its own.

Initialize it with dangerzone-image upgrade, or start the graphical application and accept the download. Alternatively, the dangerzone-full package bundles the sandbox.

Progress for each stage of each document is printed to the terminal. A failed conversion reports the error and moves on to the next document.

Exit status¶

0: All conversions succeeded (or the runtime was set with --set-container-runtime).
1: A usage error, an invalid OCR language, or at least one failed conversion.

Environment¶

DANGERZONE_DEV, DANGERZONE_BYPASS_SIG_CHECKS, QUBES_CONVERSION and the other variables listed in environment variables affect this tool.

Examples¶

Convert a single PDF next to itself:

$ dangerzone-cli report.pdf

Convert several office documents with English OCR and archive the originals:

$ dangerzone-cli --ocr-lang eng --archive *.docx *.pptx

Choose the output name:

$ dangerzone-cli --output-filename ~/clean/report.pdf report.pdf

Point Dangerzone at Podman Desktop on macOS, then revert:

$ /Applications/Dangerzone.app/Contents/MacOS/dangerzone-cli --set-container-runtime /opt/podman/bin/podman
$ /Applications/Dangerzone.app/Contents/MacOS/dangerzone-cli --set-container-runtime default