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.

Output 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!

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

Custom Filters

You can attach arbitrary key=value metadata to runs as filterable dimensions.

robotdashboard -o output.xml --customfilters "ProductVersion=1.1:Environment=staging"
robotdashboard -f ./results --customfilters "ComponentA=2.0:Environment=prod"

• Optional: --customfilters specifies one or more custom filter dimensions, as a colon-separated key=value string.
• Each unique key creates its own filter dropdown in the Dashboard's Filters modal.
• See Advanced CLI & Examples for more details and the Filtering page for how custom filter dropdowns work.

Added in RobotDashboard v1.7.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

Database

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.

Remove runs from the database

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
robotdashboard -r limit=10,tag=nightly # keep 10 newest 'nightly' runs per project, leave others
robotdashboard -r limit=10,tag=nightly,tag=prod # scope to multiple tags
robotdashboard -r age=10d # remove runs OLDER than 10 days. (y)ear/(d)ay/(h)our/(m)inute/(s)econd supported
robotdashboard -r age=-10d # remove runs YOUNGER than 10 days (note the leading minus)
# Log data of removed runs in jsonl  
robotdashboard -r limit=10 --logremoved "/myLogDir/removedRuns.jsonl"
robotdashboard -r limit=10 --logremoved "run:suite:/myLogDir/removedRuns.jsonl"
robotdashboard -r limit=10 --logremoved all
robotdashboard -r limit=10 --logremoved run:keyword

• 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 per project will be kept, all others will be removed. The limit must be at least 1.
• A project is a run name and every project_ run tag, the same grouping the dashboard overview page uses. A run that belongs to more than one project is kept as long as it is one of the 10 most recent runs of at least one of them, so a project that runs less often never loses its history to a project that runs more often.
• With limit=10,tag=nightly only the 10 most recent runs per project carrying that tag are kept; older tagged runs are removed and runs without the tag are left untouched. Add more tag= values to scope to multiple tags. Only limit supports this tag scoping — tag and age combined just run as two independent operations.
• With age=10d only runs older than 10 days will be removed
• With age=-10d (leading minus) only runs younger than 10 days will be removed
• Supported age units: (y)ear, (d)ay, (h)our, (m)inute, (s)econd — e.g. age=12h, age=-30m
• Optional: --logremoved logs run data to a .jsonl file before removal.
• Format: [types:]path where types are colon-separated from run, suite, test, keyword, all.
• If no types are specified, defaults to all (runs, suites, tests and keywords).
• If no path is provided, defaults to robot_removed_runs.jsonl in the current directory.
• Each removed run is appended as one JSON line containing the selected data types.

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.

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.

Dashboard

Generate dashboard and list runs

robotdashboard -g false  
robotdashboard -l false  
robotdashboard -l false -g false

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

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.

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.
• The title also appears in the navigation bar of the dashboard, overriding any Custom Title value set in the Theme settings.
• It is also possible to combine all sections into a single unified view, see Settings - Defaults Tab, for the details
• The unified title will be the same as the -t, --dashboardtitle argument if provided, otherwise it defaults to "Dashboard Statistics"

Control number of runs displayed by default

robotdashboard -q 7  
robotdashboard --quantity 50

• Optional: -q or --quantity sets the default number of runs per project shown in the dashboard on first load.
• A project is a run name and every project_ run tag, see the Amount filter.
• Default: value in the dashboard is 20. This can be changed in the filters.

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.

Log Linking

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.

Provide a custom URL for log files

robotdashboard -u true -o output.xml --logurl https://ci.example.com/build/42/log.html
robotdashboard -u true -f ./results --logurl "https://ci.example.com/build/42/log_{run_alias}.html"

• Optional: --logurl overrides the default log path with a custom URL stored in the database for the processed run(s).
• Useful in CI/CD pipelines where logs are published to a remote server at a unique URL per build.
• Supports a {run_alias} placeholder that is replaced per file when processing multiple outputs.
• If --logurl is provided without {run_alias} and multiple outputs are being processed, the command will produce an error.
• See Log Linking — CI Pipelines and Hosted Logs for full details and examples.

Dashboard Configuration

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!

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!

Server

Start 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.

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.

Enable HTTPS

robotdashboard --server --ssl-certfile cert.pem --ssl-keyfile key.pem
robotdashboard -s 0.0.0.0:8543 --ssl-certfile /path/to/cert.pem --ssl-keyfile /path/to/key.pem

• Optional: --ssl-certfile and --ssl-keyfile enable HTTPS by providing paths to an SSL certificate and its matching private key.
• Both flags must be provided together; neither has any effect without the other.
• Only relevant when used together with --server.
• See Dashboard Server for more details.

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.