Command Line Interface

Chronicle exposes additional commands that can be used from the CLI for troubleshooting purposes.

Invoking the chronicle CLI tool

The mechanism for invoking the chronicle CLI tool depends on which Posit Team product you are using.

Workbench

If you are using Posit Workbench, the chronicle CLI tool is wrapped by the Workbench rstudio-server CLI. You can invoke it by running the following command in a terminal on that host:

sudo rstudio-server chronicle <command>

You can make this more convenient by creating an alias for the chronicle command. For example, you could add the following line to your .bashrc or .zshrc file:

alias chronicle='sudo rstudio-server chronicle'

Connect

If you are using Posit Connect, the chronicle CLI tool is available directly on the host. You must specify the full path to the chronicle CLI tool, as well as the Chronicle configuration file.

You can invoke it by running the following command in a terminal on that host:

sudo /opt/rstudio-connect/ext/chronicle-amd64 --config /etc/rstudio-connect/chronicle/connect-chronicle.gcfg <command>

You can make this more convenient by creating an alias for the chronicle command. For example, you could add the following line to your .bashrc or .zshrc file:

alias chronicle='sudo /opt/rstudio-connect/ext/chronicle-amd64 --config /etc/rstudio-connect/chronicle/connect-chronicle.gcfg'

chronicle CLI commands

The chronicle CLI tool is to be used with hosts running Chronicle. It supports the following commands:

chronicle status

The output of this command provides a summary of the server’s recent activity. Below is an example of the status command output captured a few seconds after server startup:

Chronicle Server Status
  Version:      2026.05.04
  Last Start:   2026-06-04T17:44:38Z
  Up Time:      4s
  Receivers Scraping:
    Receiver              Last Processed        Scrape Interval
    workbench-prometheus  Never           10s
  Chronicle Server:
    URL:  http://localhost:40509
    Last Data Sent: Never
    Last Failure: Never
    Last Error:   N/A
  Storage Locations:
    /var/lib/posit-chronicle/data
      No data stored yet
      No storage errors
  Stored Metrics:
    No metrics or logs have been stored yet
  Aggregated Metrics:
    No metrics or logs have been aggregated yet

This output displays the version of the running Chronicle server, the server’s start time, and its uptime. The status command reports information specific to the current server instance, so the output only includes events that have occurred since the last startup.

When a server first starts, it is normal for it not to have received any messages from agents and, therefore, not to have stored any data or refined any metrics. Assuming one or more agents are running, within a few minutes of startup, the output of this command should show that data has been received from the agents and stored.

Below is an example of the output from a server that has been running for just over a day. It includes several refined metrics along with the other information.

Chronicle Server Status
  Version:      2026.05.04
  Last Start:   2026-06-04T17:44:38Z
  Up Time:      1m32s
  Receivers Scraping:
    Receiver              Last Processed        Scrape Interval
    workbench-prometheus  2026-06-04T17:46:09Z  10s
  Chronicle Server:
    URL:  http://localhost:40509
    Last Data Sent: 2026-06-04T17:46:09Z
    Last Failure: Never
    Last Error:   N/A
  Storage Locations:
    /var/lib/posit-chronicle/data
      Last data stored: 2026-06-04T17:46:09Z
      No storage errors
  Stored Metrics:
    Name                         Timestamp
    v2/pwb_active_user_sessions  2026-06-04T17:46:09Z
    v2/pwb_build_info            2026-06-04T17:46:09Z
    v2/pwb_license_active_users  2026-06-04T17:46:09Z
    v2/pwb_license_user_seats    2026-06-04T17:46:09Z
    v2/up                        2026-06-04T17:46:09Z
  Aggregated Metrics:
    Name                         Timestamp
    v2/pwb_active_user_sessions  2026-06-04T17:46:08Z
    v2/pwb_build_info            2026-06-04T17:46:08Z
    v2/pwb_license_active_users  2026-06-04T17:46:08Z
    v2/pwb_license_user_seats    2026-06-04T17:46:08Z
    v2/up                        2026-06-04T17:46:08Z
Back to top