ts report

Export one of the built-in usage reports as CSV or PDF. Reach for it when you need the data somewhere else — a spreadsheet, a compliance archive, a scheduled job — rather than on screen.

Usage

ts report <usage | usage-breakdown | visits | performance-traces>
          [--by=DIMENSION] [--since=DATE] [--until=DATE] [--output-file=PATH] [--pdf]

Description

The four reports are the files the Analytics site's report pages download, produced by the same renderer, so an export and the downloaded report always agree.

• usage — one row per launch: when it started, ended, and was last seen, its duration, the user and their class, how it came in (the entry point and grant), the application and workspace, the device, site, and address, and the client and application versions.
• usage-breakdown — usage totals for each value of one dimension: launches, users, usage time, its share of the period, and the last launch. --by names the dimension: application (the default), user, class, entryPoint, grant, placement, or device, spelled as written here.
• visits — guest visits: each one's kind (a share link, a Portal or native-client guest, a customer backend's visitor, or a deployment machine's guest), the guest, its times and duration, what it came in through, the application, and its outcome.
• performance-traces — client performance events with their application, user, start time, and duration.

The names sessions, user-usage, repository-usage, and shares are accepted too, each answered by the report that holds the same rows: usage, usage-breakdown by user, usage-breakdown by application, and the visits that came through share links.

CSV is the default and it goes to standard output, so a report pipes straight into another tool. Pass --output-file=PATH to write it to a file instead; ts then prints the path and the byte count rather than the report itself.

--pdf switches the format, and it requires --output-file. A PDF is binary, and writing it to a terminal would corrupt the output and leave your shell in a strange state — so ts refuses up front rather than emitting it. This check happens before the server is contacted, so the error is immediate and nothing is generated.

The two formats are not the same data. CSV carries every column the report has; the PDF is a laid-out subset built for circulation. Export CSV when someone is going to analyze the numbers, PDF when someone is going to read or file the document.

--since and --until bound the window, and both are optional and independent. Leaving one out leaves that side unbounded, so a bare ts report usage exports every launch recorded — which is usually much larger than you expect on a server that has been running a while. A value that is not a date is refused rather than read as no bound. Check the row count of any export you did not bound.

Options

Flag	Description	Default/Values	Notes
--by	The dimension usage-breakdown totals by.	application (default), user, class, entryPoint, grant, placement, device	usage-breakdown only.
--output-file	Write the report to this path.	PATH	Prints the path and size instead of the report. Required with --pdf.
--pdf	Export PDF instead of CSV.	Default CSV	Fails without --output-file. Fewer columns than the CSV.
--since	Window start.	ISO-8601; default unbounded	A value that is not a date is refused.
--until	Window end.	ISO-8601; default unbounded

Examples

# Last month's launches, straight into a spreadsheet
ts report usage --since=2026-07-01 --until=2026-08-01 > july-usage.csv

# Usage by user for the same window, as a PDF to circulate
ts report usage-breakdown --by=user --since=2026-07-01 --until=2026-08-01 \
  --pdf --output-file=july-user-usage.pdf

# Count the rows before you commit to a full export
ts report visits --since=2026-07-01 | wc -l

# Which applications are actually being used
ts report usage-breakdown --since=2026-01-01 --output-file=apps.csv

# This fails on purpose — a PDF cannot go to the terminal
ts report usage --pdf

Output

With --output-file, one line:

Wrote july-user-usage.pdf (48,132 bytes)

Without it, the CSV itself, header row first and nothing else, so it pipes and redirects cleanly.

Asking for a PDF without a destination fails before anything is generated:

Error: --pdf requires --output-file (PDF is not printable to the console).

--format=json is a poor fit for the CSV-to-stdout form: the report text ends up inside the envelope's messages array rather than as a parseable structure. Redirect the plain CSV, or write a file with --output-file and parse the JSON envelope for the path and size.

Exit Codes

0 on success, including when the window matches nothing and the CSV is just a header row. -2 when no report name is given. -1 when the name is not one of the reports, when --pdf is passed without --output-file, when --since or --until is not a date, or when --by names no dimension of the breakdown. -4 when no account is signed in and -5 when the signed-in account is not a Server Administrator.

Related Commands

• ts usage — The headline totals, when you do not need the rows.
• ts sessions — What you have running right now, as opposed to what ran.
• ts audit — Operator actions, which are a separate log from these reports.