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.

What Stays in the Web Application

Uploading data dictionaries and downloading trip files or run results use the web application; the CLI cannot authenticate those transfers yet. Everything else the REST API offers is available, and the API Reference documents the operations behind each command.