Basic Command Line Interface (CLI)

This page explains the essential CLI commands used to create databases, process output XML files, and generate the HTML dashboard. It includes clear examples and describes exactly what each command does.

Display Version and Help

Display version information

robotdashboard -v  
robotdashboard --version

• Optional: -v or --version displays the current installed version of RobotFramework Dashboard.

Display CLI help

robotdashboard -h  
robotdashboard --help

• Optional: -h or --help provides detailed information about all CLI options.

Adding Output XML Files

Add one or multiple output XML files

robotdashboard -o output1.xml -o output2.xml -o output3.xml

• Optional: Each -o or --outputpath option specifies a single output XML file.
• The tool will read the files, upload the results to the database, and optionally generate a dashboard HTML file.
• Tags can be added to group or categorize runs.
• See Advanced CLI & Examples for more information on Tags!

Add all output XMLs from a folder (including subfolders)

robotdashboard -f ./reports  
robotdashboard -f ../../some_folder/sub_folder/logs  
robotdashboard -f C:/nightly_runs:tag1:tag2:tag3 -f some/other/path/results

• Optional: -f or --outputfolderpath specifies a folder; the CLI will process all *output*.xml files it finds.
• Tags can be added to group or categorize runs.
• See Advanced CLI & Examples for more information on Tags!

Controlling Database and Dashboard Behavior

Custom database path

robotdashboard -d result_data/robot_result_database.db

• Optional: -d or --databasepath specifies a custom database file to store results.
• Default: database path is the current folder with robot_results.db.

Custom dashboard HTML file name

robotdashboard -n results/result_robot_dashboard.html

• Optional: -n or --namedashboard specifies the file name and path for the generated dashboard HTML.
• Default: dashboard name is robot_dashboard_YYYYMMDD-HHMMSS.html.

Skip listing runs and/or skip generating dashboard

robotdashboard -l false -g false

• Optional: -l or --listruns disables listing runs in the console.
• Default: true, valid values are True, TRUE, T (similar for False).
• Optional: -g or --generatedashboard disables generating the HTML dashboard.
• Default: true, valid values are True, TRUE, T (similar for False).

Project Version

You can pass version associated with a test run.
For example, if you ran tests for your software/product version 1.2.1

robotdashboard -o output.xml --projectversion=1.2.1
robotdashboard -f ./results --projectversion=1.2.1

If you want to supply versions for each output, use:

robotdashboard -o output.xml:version_1.2.1 -o output2.xml:version_2.3.4
robotdashboard -f ./results:version_1.1 ./results2:version_2.3.4

Version Constraints

• --projectversion and version_ tags are mutually exclusive — using both will produce an error.
• Each output file can have at most one version_ tag. Multiple version_ tags on the same output will produce an error.

Added in RobotDashboard v1.3.0
version_ tag support added in v1.4.0

Timezone

The dashboard stores a timezone offset alongside run_start timestamps so the dashboard can display times correctly for your local timezone.
By default the offset is auto-detected from the machine running robotdashboard. Override it when your output.xml files were produced in a different timezone:

robotdashboard -o output.xml -z +02:00
robotdashboard -f ./results --timezone=+02:00
robotdashboard -o output.xml --timezone=-05:00
robotdashboard -o output.xml -z +00:00

• Optional: -z or --timezone specifies the UTC offset of the timestamps inside the output XML files.
• Default: auto-detected from the local machine timezone.
• Format: +HH:MM or -HH:MM (e.g. +02:00, -05:00, +00:00).
• Use the --timezone= form (with =) for negative offsets to avoid the leading - being parsed as a flag.
• The offset is appended to the run_start value stored in the database (e.g. 2025-03-13 00:21:34.123456+02:00).

Timezone and existing runs

Runs processed before this feature was introduced have no timezone offset stored in their run_start. This does not break anything — those runs display exactly as they did before and are unaffected by both timezone settings in the dashboard.

You only need to re-add those output.xml files (with the correct -z/--timezone flag) if you want the Convert Timestamps to Local Timezone feature to work for them. If you never intend to use timezone conversion, no action is required. See Upgrading & Database Migration and Settings – Display Timezone Offsets & Conversion for details.

Added in RobotDashboard v1.8.0

Removing Runs from the Database

Remove runs by index, run start, alias, tag, or limit

robotdashboard -r index=0,index=1:4;9,index=10  
robotdashboard --removeruns 'run_start=2024-07-30 15:27:20.184407,index=20'  
robotdashboard -r alias=some_cool_alias,tag=prod,tag=dev -r alias=alias12345  
robotdashboard -r limit=10

• Optional: -r or --removeruns specifies one or more runs to remove.
• Multiple values are separated by commas (,).
• Must specify data types: index, run_start, alias, tag or limit.
• Index ranges use : for ranges and ; for lists.
• Quotation marks are required when spaces exist in identifiers.
• With limit=10 only the 10 most recent runs will be kept, all others will be removed.

Customizing the Dashboard

Set a custom HTML title

robotdashboard -t "My Cool Title"

• Optional: -t or --dashboardtitle sets a custom HTML title for the dashboard.
• Default: title is Robot Framework Dashboard - YYYY-MM-DD HH:MM:SS.
• It is also possible to combine all sections into a single unified view, see Settings - General Settings (Graphs Tab), for the details
• The unified title will be the same as the -t, --dashboardtitle argument if provided, otherwise it defaults to "Dashboard Statistics"

Use a JSON dashboard configuration file to set default settings

robotdashboard -j ./path/to/config.json  
robotdashboard --jsonconfig default_settings.json

• Optional: -j or --jsonconfig sets a JSON dashboard configuration file used on first load.
• See Advanced CLI & Examples for more information on customized loading behaviour!

Force the JSON config even if local storage exists

robotdashboard -j ./path/to/config.json --forcejsonconfig  
robotdashboard --jsonconfig default_settings.json --forcejsonconfig

• Optional: --forcejsonconfig forces the use of the JSON dashboard configuration file even if local storage exists.
• See Advanced CLI & Examples for more information on customized loading behaviour!

Control number of runs displayed by default

robotdashboard -q 7  
robotdashboard --quantity 50

• Optional: -q or --quantity sets the default number of runs shown in the dashboard on first load.
• Default: value in the dashboard is 20. This can be changed in the filters.

Advanced Options

Enable Log Linking in the dashboard

robotdashboard -u true  
robotdashboard --uselogs True

• Optional: -u or --uselogs enables clickable graphs in the dashboard that open corresponding log.html files.
• Requirements: log files must be in the same folder as their respective output.xml files, with output replaced by log and .xml replaced by .html.
• See Log Linking for the full guide on file naming, local vs. server usage, and remote log uploads.

Add messages config for bundling test messages

robotdashboard -m message_config.txt  
robotdashboard --messageconfig path/to/message_config.txt

• Optional: -m or --messageconfig specifies a file containing custom messages with placeholders like ${x} or ${y}.
• See Advanced CLI & Examples for more details regarding the message config!

Use local JS and CSS dependencies

robotdashboard --offlinedependencies  
robotdashboard --offlinedependencies True

• Optional: --offlinedependencies specifies to use locally downloaded js/css files and embed them directly into the dashboard.
• By default, urls to the actual JS and CSS CDN are used.
• See Advanced CLI & Examples for more information.

Disable automatic database vacuuming

robotdashboard --novacuum
robotdashboard --novacuum True

• Optional: --novacuum disables automatic database vacuuming.
• Default: False. Using --novacuum with no value sets it to True.

Disable automatic dashboard regeneration on upload/delete

robotdashboard --server --noautoupdate
robotdashboard --server --noautoupdate True

• Optional: --noautoupdate disables automatic dashboard HTML regeneration after every upload or delete via the server API.
• Default: False (dashboard is regenerated automatically on every change).
• When enabled, two Refresh buttons appear in the admin page navbar: Refresh Dashboard and Refresh Admin Page Tables.
• This is useful when working with large datasets or slow database queries, where automatic regeneration would cause long API response times.
• Only relevant when used together with --server.
• See Dashboard Server for more details.

Use a custom database class

robotdashboard -c ./path/to/custom_class.py  
robotdashboard --databaseclass mysql.py

• Optional: -c or --databaseclass specifies a custom database class implementation.
• By default, Sqlite3 is used. See Custom Database Class for more information.

Starting the Dashboard Server

robotdashboard --server  
robotdashboard --server default  
robotdashboard -s 0.0.0.0:8543

• Optional: -s or --server starts the dashboard web server.
• See Dashboard Server for advanced usage.
• Docker users can bind to a specific host and port as shown.

Deprecated options

• Exclude milliseconds: -e False (moved to dashboard Settings)
• Aliases: -a True (moved to dashboard Settings)

For more advanced usage, see Advanced CLI & Examples, the Dashboard Server and Custom Database Class pages.