Command-line Tools

vds is the command-line client for the VDS REST API. It does what the web application does, from a terminal or a script: list vehicles, devices and trips, manage measurement configurations and users, read a device’s status log, and author, check and run event definitions. Every command explains itself with --help; this page covers installation, connecting to your project, and two worked examples.

Install

vds is a single executable for Windows and Linux. Your VDS contact provides the Windows installer, a portable Windows archive, or the Linux archive. Once installed, vds self-update replaces the executable with the latest release, and vds version shows which one you have.

Connect to Your Project

The CLI talks to one project (a tenant) at a time and signs in with the same account you use in the browser.

vds tenants add-url https://<project>.<environment>.bosch-vds.com
vds auth login
vds vehicles list
  • vds tenants add-url reads the connection details from the project’s web address and stores them under a short tenant name, by default the project’s subdomain. Add --set-current to select it at the same time.
  • vds auth login opens the browser for the sign-in and keeps the session on this computer; vds auth status shows whether it is still valid, vds auth logout ends it.
  • With several projects configured, vds tenants list shows them and vds tenants use <name> switches; --tenant <name> on any command overrides the selection for that call.

The configuration lives in ~/.vds/config.yaml (%USERPROFILE%\.vds\config.yaml on Windows). vds tenants export and vds tenants import move a tenant’s settings between computers.

Getting Help

  • vds --help lists the command groups; vds <group> --help and vds <group> <command> --help explain each command, name the API operation it calls and show examples.
  • vds help expressions summarises the event expression language on one screen; the full reference is the Event Expressions section.
  • Every command’s --help text is also published in the tool’s README, so you can read the reference without installing.

Output for People and for Scripts

Commands print tables by default. Add --json to print the API’s response as JSON, which pipes into jq or any other tool:

vds trips list --status error,warning --json | jq -r '.data[] | "\(.id) \(.vehicle_name)"'

Times are accepted as YYYY, YYYY-MM, YYYY-MM-DD, RFC 3339 timestamps or Unix milliseconds, and printed in your local time zone. List commands page with --limit and --offset and report the page on standard error, so it never mixes with piped output.

Example: Author and Run an Event Definition

The Events page describes the concepts; this is the same workflow from the terminal.

# 1. See which signals the configuration offers to expressions
vds configs catalog 17

# 2. Check an expression while writing it
vds events validate --config 17 'Speed > 30.0 && delay(Brake > 0.5, 1.0)'

# 3. Create the definition from a file (the YAML the web application shows, or the API's JSON)
vds events create --file hard-braking.yaml --config 17

# 4. Preview which trips a run would evaluate, then run and wait for the result
vds events runs preview <definition-id> --start 2026-09-01 --vehicles "Truck 12"
vds events runs start <definition-id> --start 2026-09-01 --vehicles "Truck 12" --wait

# 5. List the events found, or export them as CSV in the web application's format
vds events runs occurrences <definition-id> <run-id>
vds events runs occurrences <definition-id> <run-id> --csv > hard-braking.csv

vds events validate prints each problem with a caret under the offending part of the expression and exits with status 1, so a script can stop before creating a definition that would not run. vds events get <definition-id> --yaml prints an existing definition in the file format vds events create and vds events update read back.

Example: Read a Device’s Status Log

The messages a logger writes during a trip are shown per trip in the web application (the health icon on the Trip Data page). The CLI also reads them across trips, per device:

# The device's log for the last 90 days, newest first
vds devices status-log 42

# Only errors, as JSON
vds devices status-log 42 --start 2026-09-01 --json | jq '.[] | select(.severity == "error")'

# The log of one trip
vds trips status <trip-id>

The Trip Log Messages page explains the messages. vds trips list --status error,warning lists the trips whose logger reported problems.

Example: Trip Files and OBD Snapshots

The files of a trip and their conversions are served by the project’s web address rather than by the REST API; the CLI reaches them with the same login. vds trips obd builds the trip-wide OBD snapshot the Trip Data page shows under View OBD snapshot (all files): every raw chunk is converted and the reports are merged with the newest reading of each signal winning.

# A summary: VIN, protocol, newest sample, chunks merged, sections per ECU
vds trips obd <trip-id>

# The merged report as JSON, or as the self-contained page the web viewer downloads
vds trips obd <trip-id> --json > snapshot.json
vds trips obd <trip-id> --html --out snapshot.html

# Confirmed fault codes across the trip
vds trips obd <trip-id> --json | jq '.ecus[].sections[] | select(.kind=="dtcs") | .dtcs[] | select(.variant=="Confirmed") | .code'

# The trip's files as stored, or converted on the way
vds trips download <trip-id> --out ./trip
vds trips download <trip-id> --format mf4 --exclude-gps --out ./mf4

# A run's complete results, beyond the row cap of the occurrences list
vds events runs results <def-id> <run-id> --csv --tz Europe/Berlin --out results.csv

# Dictionaries: upload a file, fetch the parsed definition
vds datadicts upload powertrain.dbc --group body
vds datadicts download <dict-id> --type can --out powertrain.can.json

The Files API Reference documents the paths behind these commands.

Use from an AI Assistant

vds mcp serve starts a local Model Context Protocol server, so an AI assistant that supports MCP can run the commands for you with your login. Every command becomes a tool, described by the same help text, and answers with the JSON the command prints with --json.

# Desktop assistants connect to http://127.0.0.1:8001/mcp
vds mcp serve

# An assistant running in the browser needs its page origin allowed
vds mcp serve --allow-origin https://assistant.example.com

# Only the commands that read from VDS
vds mcp serve --read-only

The tools run with your permissions and on the tenant you have selected; --tenant on the command pins another one. Commands that change the local setup (vds tenants, vds auth login, vds self-update) are not offered to the assistant. Stop the server when you are done: it accepts requests only from this computer, but while it runs, every allowed page can call the tools.

What Stays in the Web Application

Everything the REST API and the file paths offer is available from the CLI; the API Reference documents the operations behind each command. Plotting, dashboards and the editors remain in the web application.