Difference between revisions of "Command-Line Options"

From BaseX Documentation
Jump to navigation Jump to search
 
(123 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 
This article is part of the [[Getting Started]] Guide.
 
This article is part of the [[Getting Started]] Guide.
It gives more details on the command-line options of all BaseX [[Start Scripts|start scripts]].
+
Each BaseX [[Startup]] mode has one or more command-line options which are described in this article.
  
=BaseX GUI=
+
Command-line options can be specified multiple times. Please note that all options will be evaluated in the given order. The standard input can be parsed by specifying a single dash ({{Code|-}}) as argument.
;Launch the GUI:
 
<pre>
 
$ basexgui [file]
 
</pre>
 
  
One or more XML and XQuery files can be passed on as parameters. If an XML file is specified, a database instance is created from this file, or an existing database is opened. XQuery files are opened in the XQuery editor.
+
=Standalone=
  
=BaseX Standalone=
+
The following options are available for the standalone [[Command-Line Client]]:
;Launch the console mode:
 
<pre>
 
$ basex
 
BaseX [Standalone]
 
Try "help" to get more information.
 
> _</pre>
 
  
Available command-line flags can be listed with {{Code|-h}}:
+
<syntaxhighlight>
<pre>
 
 
$ basex -h
 
$ basex -h
 
BaseX [Standalone]
 
BaseX [Standalone]
Usage: basex [-bcdiLosuvVwxz] [query]
+
Usage: basex [-bcdiIoqrRstuvVwxz] [input]
   [query]     Execute query file or expression
+
   [input]   XQuery or command file, or query string
   -b<pars>   Bind external query variables
+
   -b<args>   Bind external query variables
   -c<input>   Execute commands from file or string
+
   -c<input> Execute commands from file or string
   -d         Activate debugging mode
+
   -d         Toggle debugging output
   -i<input>   Open initial file or database
+
   -i<input> Bind file or database to context
   -L          Append newlines to query results
+
   -I<input>  Bind input string to context
   -o<output> Write output to file
+
   -o<path>   Write output to local file
   -s<pars>   Set serialization parameter(s)
+
  -q<expr>  Execute XQuery expression
   -u         Write updates back to original files
+
  -r<num>    Run query multiple times
   -v/V       Show (all) process info
+
  -R        Toggle query execution
   -w         Preserve whitespaces from input files
+
   -s<args>   Set serialization parameters
   -x         Show query execution plan
+
  -t[path]  Run tests in file or directory
   -z         Skip output of results
+
   -u         Toggle updates in original files
</pre>
+
   -v         Toggle output of progress info
 +
  -V         Toggle detailed query output
 +
   -w         Toggle whitespace chopping
 +
   -x         Toggle output of query plan
 +
   -z         Toggle output of query result
 +
</syntaxhighlight>
  
The meaning of all flags is listed in the following. If an equivalent database option exists (which can be specified via the [[Commands#SET|SET]] command), it is listed as well:
+
Further details are listed in the following table. If an equivalent database option exists (which can be specified via the <code>[[Commands#SET|SET]]</code> command), it is listed as well.
 +
For the examples to work, it might be necessary to escape some characters depending on your operating system.
  
{| class="wikitable"  
+
{| class="wikitable"
 
|- valign="top"
 
|- valign="top"
! width='90' | Flag
+
! width='120' | Flag
! Description
+
! width="40%" | Description
 
! Option
 
! Option
 +
! Default
 
! Examples
 
! Examples
 
|- valign="top"
 
|- valign="top"
| {{Code|[query]}}
+
| {{Code|[input]}}
| Evaluates an XQuery expression. If the specified input is a valid file reference or URL, its content will be evaluated instead.
+
|Evaluates the specified input:
 +
* The input string may point to an existing file. If the file suffix is {{Code|.bxs}}, the file contents will be evaluated as [[Commands#Basics|Command Script]]; any other file content will be evaluated as XQuery expression.
 +
* Otherwise, the input string itself is evaluated as XQuery expression.
 +
|
 
|
 
|
|• {{Code|"doc('X')//head"}}<br/>• {{Code|query.xq}}<br/>
+
|• {{Code|"doc('X')//head"}}<br/>• {{Code|query.xq}}<br/>• {{Code|commands.bxs}}<br/>
 
|- valign="top"
 
|- valign="top"
| {{Code|-b&lt;pars&gt;}}
+
| {{Code|-b&lt;args&gt;}}
 
| Binds external variables to XQuery expressions. This flag may be specified multiple times. Variables names and their values are delimited by equality signs (<code>=</code>). The names may be optionally prefixed with dollar signs. If a variable uses a namespace different to the default namespace, it can be specified with the [http://www.jclark.com/xml/xmlns.htm Clark Notation].
 
| Binds external variables to XQuery expressions. This flag may be specified multiple times. Variables names and their values are delimited by equality signs (<code>=</code>). The names may be optionally prefixed with dollar signs. If a variable uses a namespace different to the default namespace, it can be specified with the [http://www.jclark.com/xml/xmlns.htm Clark Notation].
| <code>[[Options#BINDINGS|BINDINGS]]</code>
+
| {{Option|BINDINGS}}
|• <code>-b$v=example -q$v</code><br/>• <code>-b{URL}ln=value<br/>-q"declare namespace ns='URL'; $ns:ln"</code>
+
|
 +
|• <code>-bv=example "declare variable $v external; $v"</code><br/>• <code>-b{URL}ln=value<br/>"declare namespace ns='URL'; declare variable $ns:ln external; $ns:ln"</code>
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-c&lt;input&gt;}}
 
| {{Code|-c&lt;input&gt;}}
| Executes [[commands]]:
+
| Executes [[commands]]. If the specified input is a valid URI or file reference, this file will be evaluated as [[Commands#Command_Scripts|Command Script]].
* Several commands in the input can be separated by semicolons.
 
* If the specified input is a valid file reference or URL, its content will be executed instead. Empty lines and lines starting with the number sign {{Code|#}} will be ignored.
 
* Since {{Version|7.3}}, commands can also be specified in the [[Commands#XML Syntax|XML Syntax]].
 
 
|
 
|
|• {{Code|-c"list;info"}}<br/>• {{Code|-ccommands.txt}}<br/>• {{Code|-c"<info/>"}}
+
|
 +
|• {{Code|-c list}}<br/>• {{Code|-ccommands.txt}}<br/>• {{Code|-c"<info/>"}}
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-d}}
 
| {{Code|-d}}
 
| Toggles the debugging mode. Debugging information is output to ''standard error''.
 
| Toggles the debugging mode. Debugging information is output to ''standard error''.
| <code>[[Options#DEBUG|DEBUG]]</code>
+
| {{Option|DEBUG}}
 +
| <code>false</code>
 
|
 
|
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-i&lt;input&gt;}}
 
| {{Code|-i&lt;input&gt;}}
| Opens a database or XML document specified by the argument. The opened input may be further processed by an XQuery expression.
+
| Opens the specified XML file, directory with XML files, or database. The opened input can then be processed by a command or XQuery expression.
 
|
 
|
| {{Code|-iitems.xml -q"//item"}}
+
|
 +
| {{Code|-iitems.xml "//item"}}
 
|- valign="top"
 
|- valign="top"
| {{Code|-L}}
+
| {{Code|-I&lt;input&gt;}}
| Separates returned query items by newlines (instead of spaces) and appends a newline to the end of a result.
+
| Assigns an input string as item of type {{Code|xs:untypedAtomic}} to the query context.
 
|
 
|
 
|
 
|
 +
| {{Code|-I "Hello Universe" -q "."}}
 
|- valign="top"
 
|- valign="top"
| {{Code|-o&lt;file&gt;}}
+
| {{Code|-o&lt;path&gt;}}
 
| All command and query output is written to the specified file.
 
| All command and query output is written to the specified file.
 +
|
 
|
 
|
 
| {{Code|-o output.txt}}
 
| {{Code|-o output.txt}}
 
|- valign="top"
 
|- valign="top"
| {{Code|-s&lt;pars&gt;}}
+
| {{Code|-q&lt;expr&gt;}}
 +
| Executes the specified string as XQuery expression.
 +
|
 +
|
 +
| {{Code|-q"doc('input')//head"}}
 +
|- valign="top"
 +
| {{Code|-r&lt;num&gt;}}
 +
| Specifies how often a specified query will be evaluated.
 +
| {{Option|RUNS}}
 +
| <code>1</code>
 +
| {{Code|-V -r10 "1"}}
 +
|- valign="top"
 +
| {{Code|-R}}
 +
| Specifies if a query will be executed or parsed only.
 +
| {{Option|RUNQUERY}}
 +
| <code>true</code>
 +
| {{Code|-V -R "1"}}
 +
|- valign="top"
 +
| {{Code|-s&lt;args&gt;}}
 
| Specifies parameters for serializing XQuery results; see [[Serialization]] for more details. This flag may be specified multiple times. Key and values are separated by the equality sign (<code>=</code>).
 
| Specifies parameters for serializing XQuery results; see [[Serialization]] for more details. This flag may be specified multiple times. Key and values are separated by the equality sign (<code>=</code>).
| <code>[[Options#SERIALIZER|SERIALIZER]]</code>
+
| {{Option|SERIALIZER}}
 +
|
 
| <code>-smethod=text</code>
 
| <code>-smethod=text</code>
 +
|- valign="top"
 +
| {{Code|-t[path]}}
 +
| Runs all [[Unit Module|Unit tests]] in the specified file or directory.
 +
|
 +
|
 +
| -t project/tests
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-u}}
 
| {{Code|-u}}
| Modifies original files after evaluating XQuery Update expressions.
+
| Propagates updates on input files back to disk.
| <code>[[Options#WRITEBACK|WRITEBACK]]</code>
+
| {{Option|WRITEBACK}}
 +
| <code>false</code>
 
|
 
|
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-v}}
 
| {{Code|-v}}
| Prints process and timing information to the ''standard output''.
+
| Toggles the output of process and timing information.
 
|
 
|
 +
| <code>false</code>
 
|
 
|
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-V}}
 
| {{Code|-V}}
 
| Prints detailed query information to the ''standard output'', including details on the compilation and profiling steps.
 
| Prints detailed query information to the ''standard output'', including details on the compilation and profiling steps.
| <code>[[Options#QUERYINFO|QUERYINFO]]</code>
+
| {{Option|QUERYINFO}}
 +
| <code>false</code>
 
|
 
|
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-w}}
 
| {{Code|-w}}
| By default, whitespaces around text nodes are chopped when a database is created. This flag can be specified to preserve whitespaces.
+
| Toggles whitespace chopping of XML text nodes. By default, whitespaces will be chopped.
| <code>[[Options#CHOP|CHOP]]</code>
+
| {{Option|CHOP}}
 +
| <code>true</code>
 
|
 
|
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-x}}
 
| {{Code|-x}}
| This flags turn on the output of the query execution plan, formatted in [[Options#XMLPLAN|XML]].
+
| Toggles the output of the query execution plan, formatted as {{Option|XML}}.
| <code>[[Options#XMLPLAN|XMLPLAN]]</code>
+
| {{Option|XMLPLAN}}
 +
| <code>false</code>
 +
|
 +
|- valign="top"
 +
| {{Code|-X}}
 +
| Generates the query plan before or after query compilation. {{Code|-x}} needs to be activated to make the plan visible.
 +
| {{Option|COMPPLAN}}
 +
| <code>true</code>
 
|
 
|
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-z}}
 
| {{Code|-z}}
| Skips the serialization of XQuery results. This flag is useful if the query is profiled or analyzed.
+
| Turns the serialization of XQuery results on/off. This flag is useful if the query is profiled or analyzed.
| <code>[[Options#SERIALIZE|SERIALIZE]]</code>
+
| {{Option|SERIALIZE}}
 +
| <code>true</code>
 
|
 
|
 
|}
 
|}
  
Alls options can be specified multiple times. With {{Version|7.3}}, all options will be evaluated in the given order (in earlier versions, the sequential evaluation was limited to the specified inputs, query files, queries and commands, while all other options were initially set). The standard input can be parsed by specifying a single dash ({{Code|-}}) as argument.
+
=GUI=
 +
 
 +
The following options are available for the standalone [[GUI|Graphical User Interface]]:
 +
 
 +
<syntaxhighlight>
 +
$ basexgui -h
 +
BaseX [GUI]
 +
Usage: basexgui [-d] [files]
 +
  [files]  Open specified files
 +
  -d  Enable debugging
 +
</syntaxhighlight>
 +
 
 +
You can pass one or more files as parameters. If an XML document is specified, a database instance can be created from this file. Other files are opened in the editor.
  
=BaseX Server=
+
=Server=
;Launch the server
+
 
<pre>
+
The following options are available for the [[Database Server]]:
$ basexserver
 
BaseX [Server]
 
Server was started.
 
</pre>
 
  
Available command-line flags can be listed with {{Code|-h}}:
+
<syntaxhighlight>
<pre>
 
 
$ basexserver -h
 
$ basexserver -h
 
BaseX [Server]
 
BaseX [Server]
Usage: basexserver [-cdeipSz] [stop]
+
Usage: basexserver [-cdnpSz] [stop]
   stop     Stop running server
+
   stop       Stop running server
   -c<cmds>  Execute initial database commands
+
   -c<input>  Execute commands from file or string
   -d       Activate debugging mode
+
   -d         Enable debugging output
   -e<num>  Set event port
+
   -n<name>  Set host the server is bound to
  -i        Enter interactive mode
+
   -p<port>  Set server port
   -p<num>  Set server port
+
   -S         Start as service
   -S       Start as service
+
   -z         Suppress logging
   -z       Suppress logging
+
</syntaxhighlight>
</pre>
 
  
The flags have the following meaning (equivalent database options are shown in the table as well):
+
Details on all options are listed in the following table (equivalent database options are shown in the table as well).
 +
For the examples to work, it might be necessary to escape some characters depending on your operating system.
  
{| class="wikitable"  
+
{| class="wikitable"
 
|- valign="top"
 
|- valign="top"
! width='90' | Flag
+
! width='120' | Flag
! Description
+
! width="40%" | Description
 
! Option
 
! Option
 
! Default
 
! Default
! width='165' | Examples
+
! Examples
 
|- valign="top"
 
|- valign="top"
 
| {{Code|stop}}
 
| {{Code|stop}}
| Stops an existing server instance and quits.
+
| Stops a local database server instance and quits.
 
|
 
|
 
|
 
|
 
|- valign="top"
 
|- valign="top"
| {{Code|-c&lt;cmd&gt;}}
+
| {{Code|-c&lt;input&gt;}}
| Launches database commands before the server itself is started. Several commands can be separated by semicolons.
+
| Executes [[commands]]. If the specified input is a valid URI or file reference, this file will be evaluated as [[Commands#Command_Scripts|Command Script]].
 
|
 
|
 
|
 
|
Line 168: Line 214:
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-d}}
 
| {{Code|-d}}
| Turns on the debugging mode. Debugging information is output to ''standard error''.
+
| Enables debugging output. Debugging information is output to ''standard error''.
| <code>[[Options#DEBUG|DEBUG]]</code>
+
| {{Option|DEBUG}}
|
+
| <code>false</code>
 
|
 
|
 
|- valign="top"
 
|- valign="top"
| {{Code|-e&lt;num&gt;}}
+
| {{Code|-n&lt;name&gt;}}
| Specifies the port on which the server will send events to clients.
+
| Specifies the host the server will be bound to.
| <code>[[Options#EVENTPORT|EVENTPORT]]</code>
+
| {{Option|SERVERHOST}}
| {{Code|1985}}
 
| {{Code|-e9998}}
 
|- valign="top"
 
| {{Code|-i}}
 
| Starts the interactive console mode, which can be used to enter database commands. This mode is similar to the default standalone and client mode.
 
|
 
|
 
 
|
 
|
 +
| {{Code|-p127.0.0.1}}
 
|- valign="top"
 
|- valign="top"
| {{Code|-p&lt;num&gt;}}
+
| {{Code|-p&lt;port&gt;}}
 
| Specifies the port on which the server will be addressable.
 
| Specifies the port on which the server will be addressable.
| <code>[[Options#PORT|PORT]]</code>
+
| {{Option|SERVERPORT}}
 
| {{Code|1984}}
 
| {{Code|1984}}
 
| {{Code|-p9999}}
 
| {{Code|-p9999}}
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-S}}
 
| {{Code|-S}}
| Starts the server as service (i.e., in the background).
+
| Starts the server as service (i.e., in the background). Use [[YAJSW]], or start BaseX as an ordinary background process to get more options.
 +
|
 
|
 
|
|
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-z}}
 
| {{Code|-z}}
| Does not generate any [[Logging|log files]].
+
| Prevents the generation of [[Logging|log files]].
 +
| {{Option|LOG}}
 +
| <code>true</code>
 
|
 
|
|
 
 
|}
 
|}
  
 
Multiple {{Code|-c}} and {{Code|-i}} flags can be specified. All other options will be set before any other operation takes place. The specified inputs, query files, queries and commands will be subsequently evaluated after that in the given order. The standard input can be parsed by specifying a single dash ({{Code|-}}) as argument.
 
Multiple {{Code|-c}} and {{Code|-i}} flags can be specified. All other options will be set before any other operation takes place. The specified inputs, query files, queries and commands will be subsequently evaluated after that in the given order. The standard input can be parsed by specifying a single dash ({{Code|-}}) as argument.
  
=BaseX Client=
+
=Client=
  
;Launch the console mode communicating with the server
+
If the [[Database Server|Database Client]] is executed, the user name and password will be requested on command-line. The initial user/password combination is '''admin'''/'''admin'''. The following options are available:
 
 
The user name and password will be requested. The default user/password combination is '''admin'''/'''admin''':
 
<pre>
 
$ basexclient
 
Username: admin
 
Password: *****
 
BaseX [Client]
 
Try "help" to get more information.
 
&gt; _
 
</pre>
 
  
Available command-line flags can be listed with {{Code|-h}}:
+
<syntaxhighlight>
<pre>
 
 
$ basexclient -h
 
$ basexclient -h
 
BaseX [Client]
 
BaseX [Client]
Usage: basexclient [-bcdiLnopPsUvVwxz] [query]
+
Usage: basexclient [-bcdiInopPqrRsUvVwxz] [input]
   [query]     Execute query file or expression
+
   [input]   XQuery or command file, or query string
   -b<pars>   Bind external query variables
+
   -b<args>   Bind external query variables
   -c<input>   Execute commands from file or string
+
   -c<input> Execute commands from file or string
   -d         Activate debugging mode
+
   -d         Toggle debugging output
   -i<input>   Open initial file or database
+
   -i<input> Bind file or database to context
   -L          Append newlines to query results
+
   -I<input>  Bind input string to context
   -n<name>   Set server (host) name
+
   -n<name>   Set server (host) name
   -o<output> Write output to file
+
   -o<path>   Write output to local file
   -p<num>     Set server port
+
   -p<port>   Set server port
   -P<pass>   Specify user password
+
   -P<pass>   Specify user password
   -s<pars>   Set serialization parameter(s)
+
  -q<expr>  Execute XQuery expression
   -U<name>   Specify user name
+
  -r<num>    Run query multiple times
   -v/V       Show (all) process info
+
  -R        Toggle query execution
   -w         Preserve whitespaces from input files
+
   -s<args>   Set serialization parameters
   -x         Show query execution plan
+
   -U<name>   Specify user name
   -z         Skip output of results
+
   -v         Toggle output of progress info
</pre>
+
  -V         Toggle detailed query output
 +
   -w         Toggle whitespace chopping
 +
   -x         Toggle output of query plan
 +
   -z         Toggle output of query result
 +
</syntaxhighlight>
  
The flags have the following meaning (equivalent database options are shown in the table as well):
+
See the following table for details (equivalent database options are shown in the table as well).
 +
For the examples to work, it might be necessary to escape some characters depending on your operating system.
  
{| class="wikitable"  
+
{| class="wikitable"
 
|- valign="top"
 
|- valign="top"
! width='90' | Flag
+
! width='120' | Flag
! Description
+
! width="40%" | Description
 
! Option
 
! Option
 
! Default
 
! Default
! width='165' | Examples
+
! Examples
 
|- valign="top"
 
|- valign="top"
| {{Code|[query]}}
+
| {{Code|[input]}}
| Evaluates an XQuery expression. If the specified input is a valid file reference or URL, its content will be evaluated instead.
+
|Evaluates the specified input:
 +
* The input string may point to an existing file. If the file suffix is {{Code|.bxs}}, the file contents will be evaluated as [[Commands#Basics|Command Script]]; any other file content will be evaluated as XQuery expression.
 +
* Otherwise, the input string itself is evaluated as XQuery expression.
 
|
 
|
 
|
 
|
|• {{Code|"doc('X')//head"}}<br/>• {{Code|query.xq}}<br/>
+
|• {{Code|"doc('X')//head"}}<br/>• {{Code|query.xq}}<br/>• {{Code|commands.bxs}}<br/>
 
|- valign="top"
 
|- valign="top"
| {{Code|-b&lt;pars&gt;}}
+
| {{Code|-b&lt;args&gt;}}
| Binds external variables to XQuery expressions. This flag may be specified multiple times. Variables names and their values are delimited by equality signs (<code>=</code>). The names may be optionally prefixed with dollar signs. If a variable uses a namespace different to the default namespace, it can be specified with the [http://www.jclark.com/xml/xmlns.htm Clark Notation] or [http://www.w3.org/TR/xquery-30/#id-basics Expanded QName Notation].
+
| Binds external variables to XQuery expressions. This flag may be specified multiple times. Variables names and their values are delimited by equality signs (<code>=</code>). The names may be optionally prefixed with dollar signs. If a variable uses a namespace different to the default namespace, it can be specified with the [http://www.jclark.com/xml/xmlns.htm Clark Notation] or [https://www.w3.org/TR/xquery-30/#id-basics Expanded QName Notation].
| <code>[[Options#BINDINGS|BINDINGS]]</code>
+
| {{Option|BINDINGS}}
 
|
 
|
|• <code>-b$v=example -q$v</code><br/>• <code>-b{URL}ln=value<br/>-q"declare namespace ns='URL'; $ns:ln"</code>
+
|• <code>-b$v=example "declare variable $v external; $v"</code><br/>• <code>-b{URL}ln=value<br/>"declare namespace ns='URL'; declare variable $ns:ln external; $ns:ln"</code>
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-c&lt;input&gt;}}
 
| {{Code|-c&lt;input&gt;}}
| Executes [[commands]]:
+
| Executes [[commands]]. If the specified input is a valid URI or file reference, its content will be executed instead. Empty lines and lines starting with the number sign {{Code|#}} will be ignored.
* Several commands in the input can be separated by semicolons.
 
* If the specified input is a valid file reference or URL, its content will be executed instead. Empty lines and lines starting with the number sign {{Code|#}} will be ignored.
 
* Since {{Version|7.3}}, commands can also be specified in the [[Commands#XML Syntax|XML Syntax]].
 
 
|
 
|
 
|
 
|
|• {{Code|-c"list;info"}}<br/>• {{Code|-ccommands.txt}}<br/>• {{Code|-c"<info/>"}}
+
|• {{Code|-c list}}<br/>• {{Code|-ccommands.txt}}<br/>• {{Code|-c"<info/>"}}
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-d}}
 
| {{Code|-d}}
 
| Toggles the debugging mode. Debugging information is output to ''standard error''.
 
| Toggles the debugging mode. Debugging information is output to ''standard error''.
| <code>[[Options#DEBUG|DEBUG]]</code>
+
| {{Option|DEBUG}}
|
+
| <code>false</code>
 
|
 
|
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-i&lt;input&gt;}}
 
| {{Code|-i&lt;input&gt;}}
| Opens a database or XML document specified by the argument. The opened input may be further processed by an XQuery expression.
+
| Opens the specified XML file, directory with XML files, or database. The opened input can then be processed by a command or XQuery expression.
 
|
 
|
 
|
 
|
| {{Code|-iitems.xml -q"//item"}}
+
| {{Code|-iitems.xml "//item"}}
 
|- valign="top"
 
|- valign="top"
| {{Code|-L}}
+
| {{Code|-I&lt;input&gt;}}
| Separates returned query items by newlines (instead of spaces) and appends a newline to the end of a result.
+
| Assigns an input string as item of type {{Code|xs:untypedAtomic}} to the query context.
 
|
 
|
 
|
 
|
 +
| {{Code|-I "Hello Universe" -q "."}}
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-n&lt;name&gt;}}
 
| {{Code|-n&lt;name&gt;}}
 
| Specifies the host name on which the server is running.
 
| Specifies the host name on which the server is running.
| <code>[[Options#HOST|HOST]]</code>
+
| {{Option|HOST}}
 
| {{Code|localhost}}
 
| {{Code|localhost}}
 
| {{Code|-nserver.basex.org}}
 
| {{Code|-nserver.basex.org}}
 
|- valign="top"
 
|- valign="top"
| {{Code|-o&lt;file&gt;}}
+
| {{Code|-o&lt;path&gt;}}
 
| All command and query output is written to the specified file.
 
| All command and query output is written to the specified file.
 
|
 
|
Line 301: Line 336:
 
|
 
|
 
|- valign="top"
 
|- valign="top"
| {{Code|-p&lt;num&gt;}}
+
| {{Code|-p&lt;port&gt;}}
 
| Specifies the port on which the server is running.
 
| Specifies the port on which the server is running.
| <code>[[Options#PORT|PORT]]</code>
+
| {{Option|PORT}}
 
| {{Code|1984}}
 
| {{Code|1984}}
 
| {{Code|-p9999}}
 
| {{Code|-p9999}}
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-P&lt;pass&gt;}}
 
| {{Code|-P&lt;pass&gt;}}
| Specifies the user password. If this flag is omitted, the password will be requested on command line. ''Warning'': when the password is specified via this flag, it may be visible to others.
+
| Specifies the user password. If this flag is omitted, the password will be requested on command line. ''Warning'': when the password is specified with this flag, it may get visible to others.
 +
| {{Option|PASSWORD}}
 
|
 
|
 +
| {{Code|-Uadmin -Padmin}}
 +
|- valign="top"
 +
| {{Code|-q&lt;expr&gt;}}
 +
| Executes the specified string as XQuery expression.
 
|
 
|
| {{Code|-Uadmin -Padmin}}
+
| {{Code|-q"1+2"}}
 +
|- valign="top"
 +
| {{Code|-r&lt;num&gt;}}
 +
| Specifies how often a specified query will be evaluated.
 +
| {{Option|RUNS}}
 +
| <code>1</code>
 +
| {{Code|-V -r10 "1"}}
 +
|- valign="top"
 +
| {{Code|-R}}
 +
| Specifies if a query will be executed or parsed only.
 +
| {{Option|RUNQUERY}}
 +
| <code>true</code>
 +
| {{Code|-V -R "1"}}
 
|- valign="top"
 
|- valign="top"
| {{Code|-s&lt;pars&gt;}}
+
| {{Code|-s&lt;args&gt;}}
 
| Specifies parameters for serializing XQuery results; see [[Serialization]] for more details. This flag may be specified multiple times. Key and values are separated by the equality sign (<code>=</code>).
 
| Specifies parameters for serializing XQuery results; see [[Serialization]] for more details. This flag may be specified multiple times. Key and values are separated by the equality sign (<code>=</code>).
| <code>[[Options#SERIALIZER|SERIALIZER]]</code>
+
| {{Option|SERIALIZER}}
 
|
 
|
 
| <code>-smethod=text</code>
 
| <code>-smethod=text</code>
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-U&lt;name&gt;}}
 
| {{Code|-U&lt;name&gt;}}
| Specifies the user name. If this flag is omitted, the user name will be requested on command line.  
+
| Specifies the user name. If this flag is omitted, the user name will be requested on command line.
|
+
| {{Option|USER}}
 
|
 
|
 
| {{Code|-Uadmin}}
 
| {{Code|-Uadmin}}
Line 328: Line 380:
 
| Prints process and timing information to the ''standard output''.
 
| Prints process and timing information to the ''standard output''.
 
|
 
|
|
+
| <code>false</code>
 
|
 
|
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-V}}
 
| {{Code|-V}}
 
| Prints detailed query information to the ''standard output'', including details on the compilation and profiling steps.
 
| Prints detailed query information to the ''standard output'', including details on the compilation and profiling steps.
| <code>[[Options#QUERYINFO|QUERYINFO]]</code>
+
| {{Option|QUERYINFO}}
|
+
| <code>false</code>
 
|
 
|
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-w}}
 
| {{Code|-w}}
| By default, whitespaces around text nodes are chopped when a database is created. This flag can be specified to preserve whitespaces.
+
| Toggles whitespace chopping of XML text nodes. By default, whitespaces will be chopped.
| <code>[[Options#CHOP|CHOP]]</code>
+
| {{Option|CHOP}}
|
+
| <code>chop</code>
 
|
 
|
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-x}}
 
| {{Code|-x}}
| This flags turn on the output of the query execution plan, formatted in [[Options#XMLPLAN|XML]].
+
| Toggles the output of the query execution plan, formatted as {{Option|XML}}.
| <code>[[Options#XMLPLAN|XMLPLAN]]</code>
+
| {{Option|XMLPLAN}}
 +
| <code>false</code>
 
|
 
|
 +
|- valign="top"
 +
| {{Code|-X}}
 +
| Generates the query plan before or after query compilation. {{Code|-x}} needs to be activated to make the plan visible.
 +
| {{Option|COMPPLAN}}
 +
| <code>after</code>
 
|
 
|
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-z}}
 
| {{Code|-z}}
| Skips the serialization of XQuery results. This flag is useful if the query is profiled or analyzed.
+
| Turns the serialization of XQuery results on/off. This flag is useful if the query is profiled or analyzed.
| <code>[[Options#SERIALIZE|SERIALIZE]]</code>
+
| {{Option|SERIALIZE}}
|
+
| <code>true</code>
 
|
 
|
 
|}
 
|}
  
Alls options can be specified multiple times. With {{Version|7.3}}, all options will be evaluated in the given order (in earlier versions, the sequential evaluation was limited to the specified inputs, query files, queries and commands, while all other options were initially set). The standard input can be parsed by specifying a single dash ({{Code|-}}) as argument.
+
=HTTP Server=
 
 
=BaseX HTTP Server=
 
  
;Launch the HTTP server:
+
The following options are available for the [[Web Application|HTTP Server]]:
<pre>
 
$ basexhttp
 
BaseX [Server]
 
Server was started.
 
2011-01-02 03:04:05.600:INFO::Logging to STDERR via org.mortbay.log.StdErrLog
 
2011-01-02 03:04:05.700:INFO::jetty-6.1.26
 
2011-01-02 03:04:05.800:INFO::Started SocketConnector@0.0.0.0:8984</pre>
 
  
Available command-line flags can be listed with {{Code|-h}}:
+
<syntaxhighlight>
<pre>
 
 
$ basexhttp -h
 
$ basexhttp -h
 
BaseX [HTTP]
 
BaseX [HTTP]
Usage: basexhttp [-aAbdehkKlnpPRsStTUWXz] [stop]
+
Usage: basexhttp [-cdhlnpsSUz] [stop]
   stop     Stop running server
+
   stop       Stop running server
   -a        Deactive SSL support
+
   -c<inputExecute commands from file or string
  -A        Set https port
+
   -d         Enable debugging output
  -b<passSpecify SSL password
+
   -g        Enable GZIP support
   -d       Activate debugging mode
+
   -h<port>  Set port of HTTP server
   -e<num>  Set event port
+
   -l         Start in local mode
   -h<num>  Set port of HTTP server
+
   -n<name>   Set host name of database server
  -k<path>  Path to the keystore
+
   -p<port>  Set port of database server
  -K<pass>  Specify keystore password
+
   -s<port>  Specify port to stop HTTP server
   -l       Start in local mode
+
   -S         Start as service
   -n<name> Set host name of database server
+
   -U<name>   Specify user name
   -p<num>  Set port of database server
+
   -z         Suppress logging
   -P<pass> Specify user password
+
</syntaxhighlight>
  -R        Deactivate REST service
 
   -s        Specify port to stop HTTP server
 
   -S       Start as service
 
  -t        Path to the truststore
 
  -T        Specify truststore password
 
   -U<name> Specify user name
 
  -W        Deactivate WebDAV service
 
  -X        Deactivate RESTXQ service
 
   -z       Suppress logging
 
</pre>
 
  
The flags have the following meaning (equivalent database options are shown in the table as well):
+
The meaning of all options is listed in the following table (equivalent database options are shown in the table as well).
 +
For the examples to work, it might be necessary to escape some characters depending on your Operating System.
  
{| class="wikitable"  
+
{| class="wikitable"
 
|- valign="top"
 
|- valign="top"
! width='90' | Flag
+
! width='120' | Flag
! Description
+
! width="40%" | Description
 
! Option
 
! Option
 
! Default
 
! Default
! width='145' | Examples
+
! Examples
 
|- valign="top"
 
|- valign="top"
 
| {{Code|stop}}
 
| {{Code|stop}}
| Stops a running HTTP server. By default, the database server will be stopped as well, unless one of the flags {{Code|-c}} or {{Code|-l}} is specified.
+
| Stops a local HTTP server and quits. The database server will be stopped as well, unless {{Code|-l}} is specified.
|
+
| <code>pom.xml</code>
 
|
 
|
 
|
 
|
 
|- valign="top"
 
|- valign="top"
| {{Code|-a}}
+
| {{Code|-c&lt;input&gt;}}
| Deactive the support for SSL connections.
+
| Executes [[commands]]. If the specified input is a valid URI or file reference, this file will be evaluated as [[Commands#Command_Scripts|Command Script]].
|
 
 
|
 
|
 
|
 
|
 +
| {{Code|-c"open database"}}
 
|- valign="top"
 
|- valign="top"
| {{Code|-A}}
+
| {{Code|-e}}
| Specify the port used for HTTPS connections.
+
| Enables debugging output. Debugging information is output to ''standard error''.
| <code>[[Options#HTTPSPORT|HTTPSPORT]]</code>
+
| {{Option|DEBUG}}
| 8989
 
| -A8988
 
|- valign="top"
 
| {{Code|-b}}
 
| Specify the password for this SSL certificate.
 
| <code>[[Options#SSLPASSWORD|SSLPASSWORD]]</code>
 
|
 
| -bPassword
 
|- valign="top"
 
| {{Code|-c}}
 
| Starts the server in ''client mode'', and sends all commands to a database server instance.
 
|
 
 
|
 
|
 
|
 
|
 
|- valign="top"
 
|- valign="top"
| {{Code|-d}}
+
| {{Code|-g}}
| Turns on the debugging mode. Debugging information is output to ''standard error''.
+
| Enables GZIP support in Jetty.
| <code>[[Options#DEBUG|DEBUG]]</code>
+
| {{Option|GZIP}}
 
|
 
|
 
|
 
|
 
|- valign="top"
 
|- valign="top"
| {{Code|-e&lt;num&gt;}}
+
| {{Code|-h&lt;port&gt;}}
| Specifies the port on which the server will send events to clients.
+
| Specifies the port on which the HTTP server will be addressable.
| <code>[[Options#EVENTPORT|EVENTPORT]]</code>
+
| <code>jetty.xml</code>
| {{Code|1985}}
 
| {{Code|-e9998}}
 
|- valign="top"
 
| {{Code|-h&lt;num&gt;}}
 
| Specifies the port on which the HTTP server will be addressable. This port is e.g. specified in the HTTP URLs.
 
| <code>[[Options#HTTPPORT|HTTPPORT]]</code>
 
 
| {{Code|8984}}
 
| {{Code|8984}}
 
| {{Code|-h9999}}
 
| {{Code|-h9999}}
|- valign="top"
 
| {{Code|-k}}
 
| Path to the keystore file
 
| <code>[[Options#KEYSTORE|KEYSTORE]]</code>
 
| BaseXSSL/keystore
 
| -k/temp/certify
 
|- valign="top"
 
| {{Code|-K}}
 
| Specify the password for the keystore.
 
| <code>[[Options#KEYSTOREPASSWORD|KEYSTOREPASSWORD]]</code>
 
|
 
|
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-l}}
 
| {{Code|-l}}
 
| Starts the server in ''local mode'', and executes all commands in the embedded database context.
 
| Starts the server in ''local mode'', and executes all commands in the embedded database context.
|
+
| {{Option|HTTPLOCAL}}
 
|
 
|
 
|
 
|
Line 476: Line 485:
 
| {{Code|-n&lt;name&gt;}}
 
| {{Code|-n&lt;name&gt;}}
 
| Specifies the host name on which the server is running.
 
| Specifies the host name on which the server is running.
| <code>[[Options#HOST|HOST]]</code>
+
| {{Option|HOST}}
 
| {{Code|localhost}}
 
| {{Code|localhost}}
 
| {{Code|-nserver.basex.org}}
 
| {{Code|-nserver.basex.org}}
 
|- valign="top"
 
|- valign="top"
| {{Code|-p&lt;num&gt;}}
+
| {{Code|-p&lt;port&gt;}}
| Specifies the port on which the BaseX Server will be addressable.
+
| Specifies the port on which the database server will be addressable.
| <code>[[Options#SERVERPORT|SERVERPORT]]</code>
+
| {{Option|SERVERPORT}}
 
| {{Code|1984}}
 
| {{Code|1984}}
 
| {{Code|-p9998}}
 
| {{Code|-p9998}}
 
|- valign="top"
 
|- valign="top"
| {{Code|-P&lt;pass&gt;}}
+
| {{Code|-s&lt;port&gt;}}
| Specifies the user password, which will be used by the HTTP services to open a new session. If this flag is omitted, the password will be requested on command line. ''Warning'': when the password is specified on command-line, it may be visible to others.
 
|
 
| {{Code|admin}}
 
| {{Code|-Uadmin -Padmin}}
 
|- valign="top"
 
| {{Code|-R}}
 
| Deactivates the [[REST]] service.
 
|
 
|
 
|
 
|- valign="top"
 
| {{Code|-s&lt;num&gt;}}
 
 
| Specifies the port that will be used to stop the HTTP server.
 
| Specifies the port that will be used to stop the HTTP server.
| <code>[[Options#STOPPORT|STOPPORT]]</code>
+
| {{Option|STOPPORT}} or<br/><code>pom.xml</code>
 +
| <code>8985</code>
 
|
 
|
|
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-S}}
 
| {{Code|-S}}
| Starts the server as service (i.e., in the background).
+
| Starts the server as service (i.e., in the background). Use [[YAJSW]], or start BaseX as an ordinary background process to get more options.
|
 
|
 
|- valign="top"
 
| {{Code|-t}}
 
| Path to the truststore file.
 
| <code>[[Options#TRUSTSTORE|TRUSTSTORE]]</code>
 
| BaseXSSL/keystore
 
| -t/temp/keystore
 
|- valign="top"
 
| {{Code|-T}}
 
| Specify the password for the truststore.
 
| <code>[[Options#TRUSTSTOREPASSWORD|TRUSTSTOREPASSWORD]]</code>
 
 
|
 
|
 
|
 
|
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-U&lt;name&gt;}}
 
| {{Code|-U&lt;name&gt;}}
| Specifies the user name, which will be used by the HTTP services for opening a new session. If this flag is omitted, the password will be requested on command line.
+
| Specifies a user name, which will be used by the HTTP services for opening a new session.
 +
| {{Option|USER}}
 
|
 
|
| {{Code|admin}}
 
 
| {{Code|-Uadmin}}
 
| {{Code|-Uadmin}}
|- valign="top"
 
| {{Code|-W}}
 
| Deactivates the [[WebDAV]] service.
 
|
 
|
 
|
 
|- valign="top"
 
| {{Code|-X}}
 
| Deactivates the [[RESTXQ]] service.
 
|
 
|
 
|
 
 
|- valign="top"
 
|- valign="top"
 
| {{Code|-z}}
 
| {{Code|-z}}
| Does not generate any [[Logging|log files]].
+
| Prevents the generation of [[Logging|log files]].
 +
| {{Option|LOG}}
 
|
 
|
|
 
 
|}
 
|}
  
Some options can also be triggered by setting the following system properties:
+
=Changelog=
 +
 
 +
;Version 9.0
 +
 
 +
* Added: BaseXHTTP, command-line option {{Code|-c}}.
 +
* Updated: BaseXHTTP, command-line option {{Code|-c}}, additionally accepts valid URLs and file references.
 +
 
 +
;Version 8.2
 +
 
 +
* Removed: Event ports, {{Code|-e}}.
  
* {{Code|org.basex.user}}: user name for opening new sessions
+
;Version 8.1
* {{Code|org.basex.password}}: user password for opening new sessions
 
* {{Code|org.basex.mode}}: by default, the HTTP server also starts an instance of the database server. If the mode is set to {{Code|local}}, an embedded database context is used for executing commands. If the mode is set to {{Code|client}}, all commands are sent to an existing database server instance.
 
* {{Code|org.basex.path}}: path to the BaseX [[Configuration|Home Directory]]
 
  
=Changelog=
+
* Added: Bind input strings to the query context with {{Code|-I}}.
 +
 
 +
;Version 8.0
 +
 
 +
* Removed: Command-line option <code>-L</code> (results will now be automatically separated by newlines).
 +
 
 +
;Version 7.9
 +
 
 +
* Added: Runs tests in file or directory with {{Code|-t}}.
 +
* Removed: interactive server mode.
 +
 
 +
;Version 7.8
 +
 
 +
* Added: Specify if a query will be executed or parsed only with {{Code|-R}}.
 +
 
 +
;Version 7.7
 +
 
 +
* Added: Bind host to the [[#BaseX Server|BaseX Server]] with {{Code|-n}}.
  
; Upcoming version
+
;Version 7.5
  
* Added: Support for SSL, added relevant Options {{Code|-a}}, {{Code|-A}}, {{Code|-b}}, {{Code|-k}}, {{Code|-K}}, {{Code|-t}}, {{Code|-T}}
+
* Added: detection of [[Commands#Basics|Command Scripts]].
 +
* Removed: HTTP server flags {{Code|-R}}, {{Code|-W}}, and {{Code|-X}}.
  
 
; Version 7.3:
 
; Version 7.3:
  
* Updated: all options are now evaluated in the given order
+
* Updated: all options are now evaluated in the given order.
* Updated: {{Code|-i}} creates main-memory representations for specified sources
+
* Updated: Create main-memory representations for specified sources with {{Code|-i}}.
* Updated: Options {{Code|-C}}/{{Code|-c}} and {{Code|-q}}/{{Code|[query]}} merged
+
* Updated: Options {{Code|-C}}/{{Code|-c}} and {{Code|-q}}/{{Code|[input]}} merged.
* Updated: Option {{Code|-L}} also separates serialized items with newlines (instead of spaces)
+
* Updated: Option {{Code|-L}} also separates serialized items with newlines (instead of spaces).
  
 
; Version 7.2:
 
; Version 7.2:
Line 571: Line 568:
 
; Version 7.1.1:
 
; Version 7.1.1:
  
* Added: Options {{Code|-C}} and {{Code|-L}} in standalone and client mode
+
* Added: Options {{Code|-C}} and {{Code|-L}} in standalone and client mode.
  
 
; Version 7.1:
 
; Version 7.1:
  
 
* Updated: Multiple query files and {{Code|-c}}/{{Code|-i}}/{{Code|-q}} flags can be specified.
 
* Updated: Multiple query files and {{Code|-c}}/{{Code|-i}}/{{Code|-q}} flags can be specified.
 
[[Category:Beginner]]
 

Latest revision as of 12:53, 8 July 2020

This article is part of the Getting Started Guide. Each BaseX Startup mode has one or more command-line options which are described in this article.

Command-line options can be specified multiple times. Please note that all options will be evaluated in the given order. The standard input can be parsed by specifying a single dash (-) as argument.

Standalone[edit]

The following options are available for the standalone Command-Line Client:

$ basex -h
BaseX [Standalone]
Usage: basex [-bcdiIoqrRstuvVwxz] [input]
  [input]    XQuery or command file, or query string
  -b<args>   Bind external query variables
  -c<input>  Execute commands from file or string
  -d         Toggle debugging output
  -i<input>  Bind file or database to context
  -I<input>  Bind input string to context
  -o<path>   Write output to local file
  -q<expr>   Execute XQuery expression
  -r<num>    Run query multiple times
  -R         Toggle query execution
  -s<args>   Set serialization parameters
  -t[path]   Run tests in file or directory
  -u         Toggle updates in original files
  -v         Toggle output of progress info
  -V         Toggle detailed query output
  -w         Toggle whitespace chopping
  -x         Toggle output of query plan
  -z         Toggle output of query result

Further details are listed in the following table. If an equivalent database option exists (which can be specified via the SET command), it is listed as well. For the examples to work, it might be necessary to escape some characters depending on your operating system.

Flag Description Option Default Examples
[input] Evaluates the specified input:
  • The input string may point to an existing file. If the file suffix is .bxs, the file contents will be evaluated as Command Script; any other file content will be evaluated as XQuery expression.
  • Otherwise, the input string itself is evaluated as XQuery expression.
"doc('X')//head"
query.xq
commands.bxs
-b<args> Binds external variables to XQuery expressions. This flag may be specified multiple times. Variables names and their values are delimited by equality signs (=). The names may be optionally prefixed with dollar signs. If a variable uses a namespace different to the default namespace, it can be specified with the Clark Notation. BINDINGS -bv=example "declare variable $v external; $v"
-b{URL}ln=value
"declare namespace ns='URL'; declare variable $ns:ln external; $ns:ln"
-c<input> Executes commands. If the specified input is a valid URI or file reference, this file will be evaluated as Command Script. -c list
-ccommands.txt
-c"<info/>"
-d Toggles the debugging mode. Debugging information is output to standard error. DEBUG false
-i<input> Opens the specified XML file, directory with XML files, or database. The opened input can then be processed by a command or XQuery expression. -iitems.xml "//item"
-I<input> Assigns an input string as item of type xs:untypedAtomic to the query context. -I "Hello Universe" -q "."
-o<path> All command and query output is written to the specified file. -o output.txt
-q<expr> Executes the specified string as XQuery expression. -q"doc('input')//head"
-r<num> Specifies how often a specified query will be evaluated. RUNS 1 -V -r10 "1"
-R Specifies if a query will be executed or parsed only. RUNQUERY true -V -R "1"
-s<args> Specifies parameters for serializing XQuery results; see Serialization for more details. This flag may be specified multiple times. Key and values are separated by the equality sign (=). SERIALIZER -smethod=text
-t[path] Runs all Unit tests in the specified file or directory. -t project/tests
-u Propagates updates on input files back to disk. WRITEBACK false
-v Toggles the output of process and timing information. false
-V Prints detailed query information to the standard output, including details on the compilation and profiling steps. QUERYINFO false
-w Toggles whitespace chopping of XML text nodes. By default, whitespaces will be chopped. CHOP true
-x Toggles the output of the query execution plan, formatted as XML. XMLPLAN false
-X Generates the query plan before or after query compilation. -x needs to be activated to make the plan visible. COMPPLAN true
-z Turns the serialization of XQuery results on/off. This flag is useful if the query is profiled or analyzed. SERIALIZE true

GUI[edit]

The following options are available for the standalone Graphical User Interface:

$ basexgui -h
BaseX [GUI]
Usage: basexgui [-d] [files]
  [files]  Open specified files
  -d  Enable debugging

You can pass one or more files as parameters. If an XML document is specified, a database instance can be created from this file. Other files are opened in the editor.

Server[edit]

The following options are available for the Database Server:

$ basexserver -h
BaseX [Server]
Usage: basexserver [-cdnpSz] [stop]
  stop       Stop running server
  -c<input>  Execute commands from file or string
  -d         Enable debugging output
  -n<name>   Set host the server is bound to
  -p<port>   Set server port
  -S         Start as service
  -z         Suppress logging

Details on all options are listed in the following table (equivalent database options are shown in the table as well). For the examples to work, it might be necessary to escape some characters depending on your operating system.

Flag Description Option Default Examples
stop Stops a local database server instance and quits.
-c<input> Executes commands. If the specified input is a valid URI or file reference, this file will be evaluated as Command Script. -c"open database;info"
-d Enables debugging output. Debugging information is output to standard error. DEBUG false
-n<name> Specifies the host the server will be bound to. SERVERHOST -p127.0.0.1
-p<port> Specifies the port on which the server will be addressable. SERVERPORT 1984 -p9999
-S Starts the server as service (i.e., in the background). Use YAJSW, or start BaseX as an ordinary background process to get more options.
-z Prevents the generation of log files. LOG true

Multiple -c and -i flags can be specified. All other options will be set before any other operation takes place. The specified inputs, query files, queries and commands will be subsequently evaluated after that in the given order. The standard input can be parsed by specifying a single dash (-) as argument.

Client[edit]

If the Database Client is executed, the user name and password will be requested on command-line. The initial user/password combination is admin/admin. The following options are available:

$ basexclient -h
BaseX [Client]
Usage: basexclient [-bcdiInopPqrRsUvVwxz] [input]
  [input]    XQuery or command file, or query string
  -b<args>   Bind external query variables
  -c<input>  Execute commands from file or string
  -d         Toggle debugging output
  -i<input>  Bind file or database to context
  -I<input>  Bind input string to context
  -n<name>   Set server (host) name
  -o<path>   Write output to local file
  -p<port>   Set server port
  -P<pass>   Specify user password
  -q<expr>   Execute XQuery expression
  -r<num>    Run query multiple times
  -R         Toggle query execution
  -s<args>   Set serialization parameters
  -U<name>   Specify user name
  -v         Toggle output of progress info
  -V         Toggle detailed query output
  -w         Toggle whitespace chopping
  -x         Toggle output of query plan
  -z         Toggle output of query result

See the following table for details (equivalent database options are shown in the table as well). For the examples to work, it might be necessary to escape some characters depending on your operating system.

Flag Description Option Default Examples
[input] Evaluates the specified input:
  • The input string may point to an existing file. If the file suffix is .bxs, the file contents will be evaluated as Command Script; any other file content will be evaluated as XQuery expression.
  • Otherwise, the input string itself is evaluated as XQuery expression.
"doc('X')//head"
query.xq
commands.bxs
-b<args> Binds external variables to XQuery expressions. This flag may be specified multiple times. Variables names and their values are delimited by equality signs (=). The names may be optionally prefixed with dollar signs. If a variable uses a namespace different to the default namespace, it can be specified with the Clark Notation or Expanded QName Notation. BINDINGS -b$v=example "declare variable $v external; $v"
-b{URL}ln=value
"declare namespace ns='URL'; declare variable $ns:ln external; $ns:ln"
-c<input> Executes commands. If the specified input is a valid URI or file reference, its content will be executed instead. Empty lines and lines starting with the number sign # will be ignored. -c list
-ccommands.txt
-c"<info/>"
-d Toggles the debugging mode. Debugging information is output to standard error. DEBUG false
-i<input> Opens the specified XML file, directory with XML files, or database. The opened input can then be processed by a command or XQuery expression. -iitems.xml "//item"
-I<input> Assigns an input string as item of type xs:untypedAtomic to the query context. -I "Hello Universe" -q "."
-n<name> Specifies the host name on which the server is running. HOST localhost -nserver.basex.org
-o<path> All command and query output is written to the specified file.
-p<port> Specifies the port on which the server is running. PORT 1984 -p9999
-P<pass> Specifies the user password. If this flag is omitted, the password will be requested on command line. Warning: when the password is specified with this flag, it may get visible to others. PASSWORD -Uadmin -Padmin
-q<expr> Executes the specified string as XQuery expression. -q"1+2"
-r<num> Specifies how often a specified query will be evaluated. RUNS 1 -V -r10 "1"
-R Specifies if a query will be executed or parsed only. RUNQUERY true -V -R "1"
-s<args> Specifies parameters for serializing XQuery results; see Serialization for more details. This flag may be specified multiple times. Key and values are separated by the equality sign (=). SERIALIZER -smethod=text
-U<name> Specifies the user name. If this flag is omitted, the user name will be requested on command line. USER -Uadmin
-v Prints process and timing information to the standard output. false
-V Prints detailed query information to the standard output, including details on the compilation and profiling steps. QUERYINFO false
-w Toggles whitespace chopping of XML text nodes. By default, whitespaces will be chopped. CHOP chop
-x Toggles the output of the query execution plan, formatted as XML. XMLPLAN false
-X Generates the query plan before or after query compilation. -x needs to be activated to make the plan visible. COMPPLAN after
-z Turns the serialization of XQuery results on/off. This flag is useful if the query is profiled or analyzed. SERIALIZE true

HTTP Server[edit]

The following options are available for the HTTP Server:

$ basexhttp -h
BaseX [HTTP]
Usage: basexhttp [-cdhlnpsSUz] [stop]
  stop       Stop running server
  -c<input>  Execute commands from file or string
  -d         Enable debugging output
  -g         Enable GZIP support
  -h<port>   Set port of HTTP server
  -l         Start in local mode
  -n<name>   Set host name of database server
  -p<port>   Set port of database server
  -s<port>   Specify port to stop HTTP server
  -S         Start as service
  -U<name>   Specify user name
  -z         Suppress logging

The meaning of all options is listed in the following table (equivalent database options are shown in the table as well). For the examples to work, it might be necessary to escape some characters depending on your Operating System.

Flag Description Option Default Examples
stop Stops a local HTTP server and quits. The database server will be stopped as well, unless -l is specified. pom.xml
-c<input> Executes commands. If the specified input is a valid URI or file reference, this file will be evaluated as Command Script. -c"open database"
-e Enables debugging output. Debugging information is output to standard error. DEBUG
-g Enables GZIP support in Jetty. GZIP
-h<port> Specifies the port on which the HTTP server will be addressable. jetty.xml 8984 -h9999
-l Starts the server in local mode, and executes all commands in the embedded database context. HTTPLOCAL
-n<name> Specifies the host name on which the server is running. HOST localhost -nserver.basex.org
-p<port> Specifies the port on which the database server will be addressable. SERVERPORT 1984 -p9998
-s<port> Specifies the port that will be used to stop the HTTP server. STOPPORT or
pom.xml
8985
-S Starts the server as service (i.e., in the background). Use YAJSW, or start BaseX as an ordinary background process to get more options.
-U<name> Specifies a user name, which will be used by the HTTP services for opening a new session. USER -Uadmin
-z Prevents the generation of log files. LOG

Changelog[edit]

Version 9.0
  • Added: BaseXHTTP, command-line option -c.
  • Updated: BaseXHTTP, command-line option -c, additionally accepts valid URLs and file references.
Version 8.2
  • Removed: Event ports, -e.
Version 8.1
  • Added: Bind input strings to the query context with -I.
Version 8.0
  • Removed: Command-line option -L (results will now be automatically separated by newlines).
Version 7.9
  • Added: Runs tests in file or directory with -t.
  • Removed: interactive server mode.
Version 7.8
  • Added: Specify if a query will be executed or parsed only with -R.
Version 7.7
Version 7.5
  • Added: detection of Command Scripts.
  • Removed: HTTP server flags -R, -W, and -X.
Version 7.3
  • Updated: all options are now evaluated in the given order.
  • Updated: Create main-memory representations for specified sources with -i.
  • Updated: Options -C/-c and -q/[input] merged.
  • Updated: Option -L also separates serialized items with newlines (instead of spaces).
Version 7.2
  • Added: RESTXQ Service
Version 7.1.1
  • Added: Options -C and -L in standalone and client mode.
Version 7.1
  • Updated: Multiple query files and -c/-i/-q flags can be specified.