Difference between revisions of "Using the Command Line"

From Inkscape Wiki
Jump to navigation Jump to search
(→‎Via export options: Add pipe examples from man page)
 
(5 intermediate revisions by 3 users not shown)
Line 1: Line 1:
  
 
This is a <span style="color:darkred">'''''Work in Progress'''</span>.
 
This is a <span style="color:darkred">'''''Work in Progress'''</span>.
 +
 +
For the full and up-to-date command line reference, see <code>man inkscape</code> or the constantly updated online copy of the manual at https://inkscape.org/doc/inkscape-man.html.
  
 
=Background=
 
=Background=
Line 49: Line 51:
 
* Export one object from the file to a PNG, hiding all other objects: '''inkscape --export-type="png" --export-id="MyTriangle" --export-id-only my_file.svg'''
 
* Export one object from the file to a PNG, hiding all other objects: '''inkscape --export-type="png" --export-id="MyTriangle" --export-id-only my_file.svg'''
 
: This will produce a PNG with a file name '''my_file_MyTriangle.png''' which tightly wraps the object. Only the triangle is shown.
 
: This will produce a PNG with a file name '''my_file_MyTriangle.png''' which tightly wraps the object. Only the triangle is shown.
* Export more than one object at a time to PNG files: '''inkscape --export-type="png" --export-id="MyTriangle,MyRectangle" my_file.svg'''
+
* Export more than one object at a time to PNG files: '''inkscape --export-type="png" --export-id="MyTriangle;MyRectangle" my_file.svg'''
 
: This will produce two PNG files, one tightly wrapping the triangle, the other the rectangle.
 
: This will produce two PNG files, one tightly wrapping the triangle, the other the rectangle.
* Export more than one object to SVG files: '''inkscape --export-type="svg" --export-id="MyTriangle,MyRectangle" --export-id-only my_file.svg'''  CRASH: FIXME
+
* Export more than one object to SVG files: '''inkscape --export-type="svg" --export-id="MyTriangle;MyRectangle" --export-id-only my_file.svg'''  CRASH: FIXME
 
: This will produce two SVG files, one with just the triangle, the other with just the rectangle.
 
: This will produce two SVG files, one with just the triangle, the other with just the rectangle.
 +
* Read an SVG from standard input (stdin) and export it to PDF format: '''cat my_file.svg | inkscape --pipe --export-filename=my_file.pdf'''
 +
* Export an SVG to PNG format and write it to standard output (stdout),  then convert it to JPG format with ImageMagick's convert program: '''inkscape --export-type=png --export-filename=- my_file.svg | convert - filename.jpg'''
 +
: If used with file read from standard input (stdin), '''--export-filename''' can be omitted
  
 
=== Via actions ===
 
=== Via actions ===
Line 100: Line 105:
 
: Note, most verbs require a GUI (even if they don't use it). To close the GUI automatically at the end of processing, use <code>--batch-process</code>.
 
: Note, most verbs require a GUI (even if they don't use it). To close the GUI automatically at the end of processing, use <code>--batch-process</code>.
 
* <code>--export-png</code>, <code>--export-ps</code>, <code>--export-eps</code>, <code>--export-pdf</code>, <code>--export-emf</code>, <code>--export-wmf</code>, <code>--export-xaml</code> must be replaced by one of:
 
* <code>--export-png</code>, <code>--export-ps</code>, <code>--export-eps</code>, <code>--export-pdf</code>, <code>--export-emf</code>, <code>--export-wmf</code>, <code>--export-xaml</code> must be replaced by one of:
** <code>--export-file=MyOutput.xxx</code> to export a single file of type xxx
+
** <code>--export-filename=MyOutput.xxx</code> to export a single file of type xxx
 
** <code>--export-type="xxx"</code> to batch export a list of input files to type xxx.
 
** <code>--export-type="xxx"</code> to batch export a list of input files to type xxx.
* <code>--usage</code> option was removed
+
* The <code>--without-gui</code> option has been removed. Most parameters trigger Inkscape to run without GUI by default now. Instead enable GUI mode specifically using <code>--with-gui</code> if needed.
* '''Attention''': the <code>-p</code> option for printing has changed meaning! It now means 'pipe', see below. There is no replacement available for printing.
+
* The <code>--usage</code> option was removed
* The option <code>--file</code>, <code>-f</code> has been dropped. To select a file to open, simply write it as the first argument to the <code>inkscape</code> command.
+
* The <code>-p</code> option for printing has changed meaning! It now means 'pipe', see below. There is no replacement available for printing.
* the command <code>-x</code> / <code>--extension-directory</code> that printed out the system extension directory, where Inkscape's stock extensions are installed, has been removed. It has been replaced by <code>--system-data-directory</code> and <code>--user-data-directory</code>, which print out the Inkscape installation's data directory and the user's custom data directory [waiting for merge 2020-02-25]
+
* The <code>--file<code>/</code>-f</code> options have been dropped. To select a file to open, simply write it as the first argument to the <code>inkscape</code> command.
 +
: You can also specify multiple files to process as a (space-separated) list or by using globs/wildcards like "*.svg" (only in compatible shell environments, ''not'' when using cmd.exe on Windows).
 +
* The <code>--extension-directory</code>/<code>-x</code> options that printed out the system extension directory containing Inkscape's stock extensions have been removed.
 +
: They have been replaced by <code>--system-data-directory</code> and <code>--user-data-directory</code>, which print out the Inkscape installation's data directory and the user's profile directory respectively.
  
 
== New options ==
 
== New options ==
  
 +
* <code>--export-type="xxx"</code>: Export a single file or a list of input files to type xxx. (output name is derived from input name; multiple export formats for batch export to all of them can specified as a comma-separated list)
 +
* <code>--export-filename=MyOutput.xxx</code>: Export a single file of type xxx (svg, png, ps, eps, pdf, emf, wmf, xaml)
 +
* <code>--actions</code>: chain actions from the action list. Actions can take an argument, like rotation angle, or element type. Conversion of verbs to actions is ongoing.
 
* <code>--action-list</code>: list available actions
 
* <code>--action-list</code>: list available actions
* <code>--actions</code>: chain actions from the action list. Actions can take an argument, like rotation angle, or element type. Conversion of verbs to actions is ongoing.
 
 
* <code>-p, --pipe</code>: Reads input file from standard input (stdin).
 
* <code>-p, --pipe</code>: Reads input file from standard input (stdin).
 
* <code>--pdf-page=PAGE</code>: Imports the given page of a pdf file. Numbering starts with 1.
 
* <code>--pdf-page=PAGE</code>: Imports the given page of a pdf file. Numbering starts with 1.
 
* <code>--pdf-poppler</code>: Imports a pdf via an external (poppler with cairo backend) library. Text consists of groups containing cloned glyphs where each glyph is a path.
 
* <code>--pdf-poppler</code>: Imports a pdf via an external (poppler with cairo backend) library. Text consists of groups containing cloned glyphs where each glyph is a path.
 
Images are stored internally. Meshes cause entire document to be rendered as a raster image.
 
Images are stored internally. Meshes cause entire document to be rendered as a raster image.
* <code>--batch-process</code>: Close GUI when done
+
* <code>--batch-process</code>: Close GUI when done. Only use this when you actually need a GUI. Otherwise you usually don't need (or want) this option, as it forces the GUI to show (similar to <code>--with-gui</code>).
* <code>--export-file=MyOutput.xxx</code>: Export a single file of type xxx (svg, png, ps, eps, pdf, emf, wmf, xaml)
 
* <code>--export-type="xxx"</code>: Batch export a list of input files to type xxx.
 
 
* <code>--export-ps-level>={2,3}</code>: choose PostScript level
 
* <code>--export-ps-level>={2,3}</code>: choose PostScript level

Latest revision as of 11:25, 30 July 2020

This is a Work in Progress.

For the full and up-to-date command line reference, see man inkscape or the constantly updated online copy of the manual at https://inkscape.org/doc/inkscape-man.html.

Background

Starting after the release of the 0.92.x series, Inkscape's code is undergoing a major rewrite with the dual goals of making it more powerful and flexible for the user while making it easier for the developer. This is a long term process and it will be awhile before we see the full benefits.

As a first step, we've started to use the latest Gtk 3 application code for Inkscape 1.0 which has resulted in some changes in how the command line works.

For the command line parameters for Inkscape versions up to 0.92.x, please check the corresponding output of inkscape --help on the command line.

What can you do with the command line?

Print out information

  • Help (list of command line options): inkscape --help or inkscape -?
  • Inkscape version: inkscape --version
  • Extension directory: inkscape --extension-directory or inkscape -x
  • List of available verbs (very long): inkscape --verb-list
  • List of available actions: inkscape --action-list

Query geometry information

  • Find the x position of a set of objects: inkscape --query-id="MyTriangle,MySquare" --query-x my_file.svg
This will return, for example:
200,300
  • Query the geometry of all objects: inkscape --query-all
This will return, for example (id,x,y,width,height):
MySvg,0,0,600,600
MyGroup,100,100,300,300
MyTriangle,120,120,100,80
MySquare,150,150,50,50

Export files

Via export options

Use of export options will suppress the GUI. All files listed on the command line will be opened, processed according to export options. and then be closed.

Some options are exclusive.

  • If both --export-filename and --export-type are given, the file name extension must match the type.
  • Only one of --export-area, --export-area-page, -export-area-drawing, --export-use-hints will be used to determine the export area. (Which one?)

Examples

  • Simple export of a PNG: inkscape --export-type="png" my_file.svg
This will produce a PNG with a name my_file.png
  • Export one object from the file to a PNG: inkscape --export-type="png" --export-id="MyTriangle" my_file.svg
This will produce a PNG with a file name my_file_MyTriangle.png which tightly wraps the object. Objects that extend into the exported area will be shown.
  • Export one object from the file to a PNG, hiding all other objects: inkscape --export-type="png" --export-id="MyTriangle" --export-id-only my_file.svg
This will produce a PNG with a file name my_file_MyTriangle.png which tightly wraps the object. Only the triangle is shown.
  • Export more than one object at a time to PNG files: inkscape --export-type="png" --export-id="MyTriangle;MyRectangle" my_file.svg
This will produce two PNG files, one tightly wrapping the triangle, the other the rectangle.
  • Export more than one object to SVG files: inkscape --export-type="svg" --export-id="MyTriangle;MyRectangle" --export-id-only my_file.svg CRASH: FIXME
This will produce two SVG files, one with just the triangle, the other with just the rectangle.
  • Read an SVG from standard input (stdin) and export it to PDF format: cat my_file.svg | inkscape --pipe --export-filename=my_file.pdf
  • Export an SVG to PNG format and write it to standard output (stdout), then convert it to JPG format with ImageMagick's convert program: inkscape --export-type=png --export-filename=- my_file.svg | convert - filename.jpg
If used with file read from standard input (stdin), --export-filename can be omitted

Via actions

Use of export options and actions can be mixed. (How?) All export options have matching actions (remove the '--' in front of the option and replace '=' with ':'). If only actions are used, either --without-gui or --batch-process must be used (due to our code structure, most verbs require the GUI to be present even if not used). All files on the command line will be opened, processed according to actions options, and then closed. Export can be forced at any point with the export-do action. This allows one to do multiple exports on a single file.

Examples

  • inkscape --without-gui --actions="export-id:MyTriangle; export-id-only; export-background:purple; export-filename:triangle_purple.png; export-do; export-background:red; export-filename:triangle_red.png" my_file.svg
This will export the object with the id MyTriangle with a purple background to the file triangle_purple.png and with a red background to the file triangle_red.png. (Note: there is an implicit file export at the end.
  • inkscape --without-gui --actions="export-id-only; export-id:Triangle; export-filename:action_triangle.png; export-do; export-id:Path; export-filename:action_path.png" export_test.svg
Exports the objects Triangle and Path to different files.

Modify files

  • inkscape --actions="select:Triangle; ObjectFlipVertically; export-filename:flipped-triangle.svg; export-do; EditUndo; select:Path; ObjectFlipHorizontally; export-filename: flipped-path.svg; export-do; EditUndo; FileClose" export_test.svg
Flip the triangle, save the result. Undo the flip, then flip the path, save the result. Undo the flip and close the file. (At the moment, one must undo any changes to avoid popping up a dialog warning about unsaved changes.)

Shell mode

To open and edit multiple files after one another without opening a new Inkscape instance for each file, Inkscape offers the shell mode. This mode uses your computer's resources more efficiently, and allows for faster batch processing. The commands are largely identical to those for the 'normal' mode.

You can launch the interactive command line with inkscape --shell.

The main difference to commands in the normal mode is that you need to explicitly indicate when you want to open a file, e.g. file-open:filename.svg; select:flowRootID; query-height.

Changes from 0.92

General Changes

  • Each command-line argument can be used only once. The order does not effect processing. Instead, some arguments, e.g. --verbs, can have a semicolon separated list of values:
inkscape --select=MyStar --verb "ObjectFlipVertically;FileSave;FileClose" MyStar.svg
  • xverbs are no longer supported. They are (will be) replaced by actions.
  • Inkscape can now take more than one input file, as in inkscape filename1.svg filename2.svg.
  • The --export-id argument now supports a semicolon separated list of objects, each one will be exported separately.
  • The --query-id argument now supports a comma separated list of objects. Any geometry query (e.g. --query-x) will return a comma separated list of values corresponding to the list of objects in --query-id.
  • In export mode, to overwrite a file, one must use --export-overwrite, otherwise a new filename will be generated: file.svg -> file_out.svg
  • The option --select now accepts a comma separated list of object IDs instead of only a single ID.
  • The shell mode changed. Some information is available here.

Deprecations and Replacements

  • The command-line option --verb is deprecated, use --actions instead:
inkscape --select=MyStar --actions="ObjectFlipVertically;FileSave;FileClose" MyStar.svg
Eventually all verbs will be replaced by actions. Temporarily, any verb can be used as an action.
Note, most verbs require a GUI (even if they don't use it). To close the GUI automatically at the end of processing, use --batch-process.
  • --export-png, --export-ps, --export-eps, --export-pdf, --export-emf, --export-wmf, --export-xaml must be replaced by one of:
    • --export-filename=MyOutput.xxx to export a single file of type xxx
    • --export-type="xxx" to batch export a list of input files to type xxx.
  • The --without-gui option has been removed. Most parameters trigger Inkscape to run without GUI by default now. Instead enable GUI mode specifically using --with-gui if needed.
  • The --usage option was removed
  • The -p option for printing has changed meaning! It now means 'pipe', see below. There is no replacement available for printing.
  • The --file/-f options have been dropped. To select a file to open, simply write it as the first argument to the inkscape command.
You can also specify multiple files to process as a (space-separated) list or by using globs/wildcards like "*.svg" (only in compatible shell environments, not when using cmd.exe on Windows).
  • The --extension-directory/-x options that printed out the system extension directory containing Inkscape's stock extensions have been removed.
They have been replaced by --system-data-directory and --user-data-directory, which print out the Inkscape installation's data directory and the user's profile directory respectively.

New options

  • --export-type="xxx": Export a single file or a list of input files to type xxx. (output name is derived from input name; multiple export formats for batch export to all of them can specified as a comma-separated list)
  • --export-filename=MyOutput.xxx: Export a single file of type xxx (svg, png, ps, eps, pdf, emf, wmf, xaml)
  • --actions: chain actions from the action list. Actions can take an argument, like rotation angle, or element type. Conversion of verbs to actions is ongoing.
  • --action-list: list available actions
  • -p, --pipe: Reads input file from standard input (stdin).
  • --pdf-page=PAGE: Imports the given page of a pdf file. Numbering starts with 1.
  • --pdf-poppler: Imports a pdf via an external (poppler with cairo backend) library. Text consists of groups containing cloned glyphs where each glyph is a path.

Images are stored internally. Meshes cause entire document to be rendered as a raster image.

  • --batch-process: Close GUI when done. Only use this when you actually need a GUI. Otherwise you usually don't need (or want) this option, as it forces the GUI to show (similar to --with-gui).
  • --export-ps-level>={2,3}: choose PostScript level