Context Navigation

Editing Help/CommandLineOptions

Adjust edit area height: Edit side-by-side

[[TranslatedPages]]
= Command Line Options =

Four types of command line options affect JOSM:
 * The [#Programarguments Program arguments⤓] directly control JOSM. They are called ''args'' by Java. 
 * The [#Javaoptions Java options⤓] affect its environment (JVM) and are sometimes named ''VM arguments''.
 * Only involved in Web Start are the [#run-options Run-options⤓]. 
 * Some [#Otheroptions Other options⤓] for diagnostics and launchers.

{{{
#!sh
# Running a jar
java [Java options] -jar josm-tested.jar [Program arguments]

# Launch a Web Start
javaws [run-options] -J[Java option] josm.jnlp
}}}

The [wikitr:/Help/Action/ShowStatusReport Status Report] lists the given Program arguments and Java options in its second section. 
Some [#Examples examples⤓] for both of them are shown below.
As usual in all four types the arguments are separated by space from each other.

== Program arguments ==#Programarguments

The first argument can be a **command** for JOSM to make it work autonomous. 
If JOSM can't recognize the first argument as command, then `runjosm` is assumed as default.

The remaining arguments are **options** for JOSM.  
They can be URLs, filenames, coordinates, simple options and option=value pairs. 
The complete list of commands and options is shown below:

{{{
usage:
  java <java options> -jar josm.jar [<command>] <options>

commands:
  runjosm     launch JOSM (default, performed when no command is specified)
  render      render data and save the result to an image file
  project     convert coordinates from one coordinate reference system to another

For details on the render and project commands, run them with the --help option.
The remainder of this help page documents the runjosm command.

options:
  --help|-h                                                Show this help
  --geometry=widthxheight(+|-)x(+|-)y                      Standard unix geometry argument
  [--download=]minlat,minlon,maxlat,maxlon                 Download the bounding box
  [--download=]<URL>                                       Download the location URL which has
                                                           coordinates like lat=x&lon=y&zoom=z
  [--download=]<filename>                                  Open a file (same as Menu/File/Open)
  --downloadgps=minlat,minlon,maxlat,maxlon                Download the bounding box as raw GPS
  --downloadgps=<URL>                                      Download the location as raw GPS
  --selection=<searchstring>                               Select with the given search
  --[no-]maximize                                          Launch in maximized mode
  --reset-preferences                                      Reset the preferences to default
  --load-preferences=<url-to-xml>                          Import preferences from XML file
  --set=<key>=<value>                                      Set preference key to value
  --language=<language>                                    Set the language
  --version                                                Displays the JOSM version and exits
  --debug     or   --trace                                 Print debugging messages to console
  --skip-plugins                                           Skip loading plugins
  --offline=[osm_api,][josm_website,][certificates,][all]  Disable access to the listed resources
}}}

The `--download=` part of the download option is optional. 
The arguments `--download`, `--downloadgps` and `--selection` are processed in this order.
The value `<url-to-xml>` can point to a local file with `file:relative/path/name.xml`.
The items in the `--offline` value are separated by comma.

== Java options ==#Javaoptions

They control the Java virtual machine [https://docs.oracle.com/javase/8/docs/technotes/tools/unix/java.html (JVM)] and can set [https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html properties] inside it. JOSM reads some of them directly, for example `josm.home`. Others like `user.language` and `user.country` affect the default settings of the JVM which affect JOSM too.

{{{
java options:
  -Djosm.dir.name=JOSM                      Change the JOSM directory name
  -Djosm.pref=/PATH/TO/JOSM/PREF            Set the preferences directory
                                            Default: C:\Users\name\AppData\Roaming\JOSM
  -Djosm.userdata=/PATH/TO/JOSM/USERDATA    Set the user data directory
                                            Default: /home/name/.local/share/JOSM
  -Djosm.cache=/PATH/TO/JOSM/CACHE          Set the cache directory
                                            Default: <...>
  -Djosm.home=/PATH/TO/JOSM/HOMEDIR         Set the common directory for preferences,
                                            user data and ./cache/. Lower precedence.
                                            Will get overridden from specific setting.
  -Xmx...m                                  Set maximum Java heap size in megabytes.
                                            May avoid Out-of-Memory errors.
}}}

The `-Xmx...m` option may be useful when [wikitr:/Download#Outofmemory Out of Memory] errors arise.
If you set a common directory with `Djosm.home` then JOSM will create the subdirectories ./autosave, ./cache and ./validator.
If a value has spaces, then enclose it in quotation marks like `"josm dev"`.
When the non-ASCII characters in the command prompt are scrambled, use `-Dfile.encoding=Cp850` to receive text from Java in another [https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html code page].
Which [https://msdn.microsoft.com/de-de/library/windows/desktop/dd317756%28v=vs.85%29.aspx code page] is used shows `chcp⏎` in the terminal.

[=#Examples **Examples**]
{{{
#!sh
# Load three files
  java -jar josm-tested.jar track1.gpx BigBen.jpg "london data.osm"
# Download from OSM according to an URL with zoom and coordinates
  java -jar josm-tested.jar https://www.openstreetmap.org/#map=19/51.51/-0.135
# Download a bounding box and select every element matching a string
  java -jar josm-tested.jar 51.505,-0.14,51.515,-0.13 --selection="Piccadilly Circus"
#
# Set directory for JOSM according to a property from the operating system
  java -Djosm.pref=$XDG_CONFIG_HOME -jar josm-tested.jar
# Quotations for a value with space and show JOSMs GUI in English
  java -Djosm.dir.name="josm dev" -jar josm-latest.jar --language=en
# Set the common directory in a sub-subdirectroy below the active command prompt
  java -Djosm.home=biketour2017/london -jar josm-tested.jar
# More memory in the Canadian variant of an English spoken environment
  java -Xmx1024m -Duser.language=en -Duser.country=CA -jar josm-latest.jar
#
# Log debug info and do not get disturbed by JOSM phoning home
  java -verbose -jar josm-latest.jar --set=message.notifier.enabled=false --debug >WhatsUp.txt
}}}

== Run-options ==#run-options
The run-options are used by the `javaws` command. They control the Web Start mechanism and can encapsulate Java options. 
{{{
  -offline                  Allows to Web Start JOSM without internet access
  -J<java option>           Supplies the <java option> to the JVM 
  -J-Xmx1024m               Here: Set maximum Java heap size to 1024 megabyte
}}}

The `-J` run-option takes its part behind the J letter and supplies that as Java option. 
The [wikitr:/Help/jnlpOptions jnlp-File] used by [https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javaws.html Web Start] offers a second way to [https://docs.oracle.com/javase/8/docs/technotes/guides/javaws/developersguide/syntax.html  set options] for JRE and for the JOSM program directly.

== Other options ==#Otheroptions
The `javaws` command has some control options on all systems.
On [wikitr:/Download#Mswindowswrapper MS Windows] only the Launcher `josm.exe` aka [http://launch4j.sourceforge.net/docs.html#Runtime_options  Launch4j] may give some debug info (needs 64-bit Java on 64-bit Windows).  
{{{
#!sh
# Control options:
javaws -viewer            Shows the Cache Viewer in the Java Control Panel 
# Allows to opens the Java Control Panel from the command line.

javaws -clearcache        Removes all non-installed applications from the cache
# Equal to 'Delete Files and Applications' from the 'Temporary File Settings' invoked 
# by the 'Settings' button in the 'General' tab of the Java Control Panel.
# javaws -Xclearcache on OpenJDK

# On MS Windows:
josm.exe --j4l-debug      Tries to write a launch4j.log to current directory
josm.exe --j4l-dont-wait  Ends the wrapper after invoking JOSM.
}}}
The `-clearcache` option and clearing the cache via the Java Control Panel will both delete JNLP based icons from the Desktop. The JOSM icon will be gone if it was placed as result of a click in a web browser on a jnlp-file.

=== See also ===
* [wikitr:/Download#Troubleshooting Troubleshooting Java]
* [wikitr:/InstallNotes Installation notes]
* [wikitr:/Help/Preferences Preferences] - Preferences overview

----
Back to [wikitr:/Help Main Help]

Note: See WikiFormatting and TracWiki for help on editing wiki content.

Change information

Your email or username:

E-mail address and name can be saved in the Preferences

Comment about this change (optional):

Note: See TracWiki for help on using the wiki.