Pages of the blog

04 December, 2016

Command-line arguments in LibreOffice

The last few weeks I've been doing a patch in the Help associated with the bug tdf#100836. It seems that there is a file that describes everything, and it need to only move into the code, but not everything is simple. First, this help appears in the console mode, and it had been very desolate. On Windows system, it opens in the window that does not have a scroll bar instead to show it in the console. Secondly, mistakes were found at the time of writing, and they should be corrected before placing in the Help. As a result, instead of a single patch was made already 3: I did two (1, 2) and one was done Mike Kaganski. And as a fact, it requires further improvement, but unfortunately, I already have tired from writing of it. And since this Help will appear only next summer in the LibreOffice 5.4, I give it here, as always, with minor explanations. I hope that someone else will improve this help to the release, and you can enjoy more good official Help.


In most cases, you do not need to use this information. It will be useful to administrators and developers, and in cases when a non-trivial problem needs to be resolved (for example, to work without GUI)

Usage:
soffice [argument...]
argument - switches, switch parameters and document URIs (filenames) if it is needed then with its path.

Getting help and information

--help | -h | -? — Shows this help and quits.
--helpwriter — Opens LibreOffice built-in or online Help on Writer.
--helpcalc — Opens LibreOffice built-in or online Help on Calc.
--helpdraw — Opens LibreOffice built-in or online Help on Draw.
--helpimpress — Opens LibreOffice built-in or online Help on Impress.
--helpbase — Opens LibreOffice built-in or online Help on Base.
--helpbasic — Opens LibreOffice built-in or online Help on Basic scripting language.
--helpmath — Opens LibreOffice built-in or online Help on Math

Of course, it need to access internet for the online Help. If there is no built-in Help and the access Internet, the Help is not available. These features will be useful to developers of the LibreOffice documentation, as it allow them to do smaller movements with the help testing.

--version — Shows the version and quits.
--nstemporarydirectory — (MacOS X sandbox only) Returns path of the temporary directory for the current user and exits. Overrides all other arguments.

General arguments

--quickstart[=no] — Activates[Deactivates] the Quickstarter service. It can take only one value after the equal (no), which disables the service.
--nolockcheck — Disables check for remote instances using one installation.
--infilter={filter} Force an input filter type if possible. If it isn’t possible, LibreOffice uses the available filter for the document. For example:
--infilter="Calc Office Open XML"
--infilter="Text (encoded):UTF8,LF,,,"

Note that filter names may change, these examples show the use of the argument. Unfortunately, there is no easy way to know all the available filters.

--pidfile={file} — Store soffice.bin pid to {file}.
--display {display} — Sets the DISPLAY environment variable on UNIX-like platforms to the value {display} (only supported by a start script for the LibreOffice).

User/programmatic interface control

--nologo — Disables the splash screen at program start.
--minimized — Starts minimized. The splash screen is not displayed.
--nodefault — Starts without displaying anything except the splash screen (do not display initial window).
--invisible — Starts in invisible mode. Neither the start-up logo nor the initial program window will be visible. LibreOffice can be controlled, and documents and dialogs can be controlled and opened via the API. Using the parameter, LibreOffice can only be ended using the taskmanager (Windows) or the kill command (UNIX-like systems). It cannot be used in conjunction with --quickstart.
--headless — Starts in "headless mode" which allows using the application without GUI. This special mode can be used when the application is controlled by external clients via the API.

Note the last two arguments. Using --invisible does not disable the graphical interface. All the documents and dialogs are displayed on the monitor. --headless allows us to use the "silent mode", when the GUI is not needed.

--norestore — Disables restart and file recovery after a system crash.
--safe-mode — Starts in a safe mode, i.e. starts temporarily with a fresh user profile and helps to restore a broken configuration.

Developers "recommended" to me to remove the next argument from the Help. But since it is, and you can find fragmentary information about it, I point out all the available information which I have.

--splash-pipe=Uses com.sun.star.office.PipeSplashScreen insted com.sun.star.office.SplashScreen. Symbol = (equal) is mandatory, although the entire string after it is ignored. This argument is used in the call of the soffice form oosplash on UNIX-like systems and is not recommended for use in the console.
--accept={UNO-URL} — Specifies an UNO-URL connect-string to create an UNO acceptor through which other programs can connect to access the API. UNO-URL is string the such kind uno:connection-type,params;protocol-name,params;ObjectName. At the same time, according to the LibreOffice code, the ObjectName is ignored.
--unaccept={UNO-URL} — Closes an acceptor that was created with --accept. Use --unaccept=all to close all open acceptors.
--language={lang} — Uses specified language, if language is not selected yet for UI. The lang is a tag of the language in IETF language tag. This argument works only when you install the application, because as soon as the application is installed and running be deemed that the language has been selected. It is for easier installing on the remote machine.

Developer arguments

--terminate_after_init — Exit after initialization complete (no documents loaded).
--eventtesting — Exit after loading documents.

New document creation arguments

The arguments create an empty document of specified kind. Only one of them may be used in one command line. If filenames are specified after an argument, then it tries to open those files in the specified component. If it is impossible to open in the selected component, LibreOffice loads the document in any possible.
--writer — Creates an empty Writer document.
--calc — Creates an empty Calc document.
--draw — Creates an empty Draw document.
--impress — Creates an empty Impress document.
--base — Creates a new database.
--global — Creates an empty Writer master (global) document.
--math — Creates an empty Math document (formula).
--web — Creates an empty HTML document.

File open arguments

The arguments define how following filenames are treated. New treatment begins after the argument and ends at the next argument. The default treatment is to open documents for editing, and create new documents from document templates.
-n — Treats following files as templates for creation of new documents.
-o — Opens following files for editing, regardless whether they are templates or not.
--pt {Printername} — Prints following files to the printer {Printername}, after which those files are closed. The splash screen does not appear. If used multiple times, only last {Printername} is effective for all documents of all --pt runs. Also, --printer-name argument of --print-to-file switch interferes with {Printername}.
-p — Prints following files to the default printer, after which those files are closed. The splash screen does not appear. If the file name contains spaces, then it must be enclosed in quotation marks.
--view — Opens following files in viewer mode (read-only).
--show — Opens and starts the following presentation documents of each immediately. Files are closed after the showing. Files other than Impress documents are opened in default mode , regardless of previous mode.
--convert-to OutputFileExtension[:OutputFilterName] [--outdir output_dir] — Batch convert files (implies --headless). If --outdir isn't specified, then current working directory is used as output_dir. If --convert-to is used more than once, last value of OutputFileExtension[:OutputFilterName] is effective. If --outdir is used more than once, only its last value is effective. For example:
--convert-to pdf *.doc
--convert-to pdf:writer_pdf_Export --outdir /home/user *.doc
--convert-to "html:XHTML Writer File:UTF8" *.doc
--convert-to "txt:Text (encoded):UTF8" *.doc
Unfortunately, now there is no easy way to know all the possible filter values. Thus, the use of this argument is difficult, in spite of its potential usefulness.
--print-to-file [--printer-name printer_name] [--outdir output_dir] — Batch print files to file. If --outdir is not specified, then current working directory is used as output_dir. If --printer-name or --outdir used multiple times, only last value of each is effective. Also, {Printername} of --pt switch interferes with --printer-name.
--cat — Dump text content of the following files to console (implies --headless). Cannot be used with --convert-to.
-env:var[=value] — Set a bootstrap variable. For example: to set a non-default user profile path:
-env:UserInstallation=file:///tmp/test
Unfortunately, now there is no easy way to get all the possible variables for this flag.

Ignored switches

-psn — Ignored (MacOS X only).
-Embedding — Ignored (COM+ related; Windows only).
--nofirststartwizard — Does nothing, accepted only for backward compatibility.
--protector {arg1} {arg2} — Used only in unit tests and should have two arguments.

Source and additional information: