Skip to content

Getting started with the command line

pivotkit renders a view over a data file without a browser: an HTML report to print or save as PDF, CSV, JSON, an Excel workbook or the chart as SVG. It also checks views in a pipeline before they go live. It needs Node 22 or later and no network.

You get there in five steps: install it, try it on the example files, get a view from your own file, render a report from the files the report downloads, then put it into CI.

1. Install

npm install --global pivotkit-cli
pivotkit --version

npm install --save-dev pivotkit-cli
npx pivotkit --version          # the project's own copy

npx pivotkit-cli --version      # every command: npx pivotkit-cli <command> ...

The package is named pivotkit-cli, its command pivotkit. Without an install, npx pivotkit-cli runs the command once; it does not put pivotkit on your PATH, so each line starts with npx pivotkit-cli (npx pivotkit alone asks npm for another package). The rest of this page writes pivotkit.

2. Try it on the example files

mkdir pivotkit-try && cd pivotkit-try
pivotkit example

Wrote 3 files into this directory:
  sales.csv                  the data: 2,000 rows of generated sales, as the report's Export → Source data writes it
  sales.pivotkit.json        a view: Revenue by region and category (a table)
  sales-chart.pivotkit.json  a view: Monthly revenue trend (a line chart)
Next:
  pivotkit render sales.pivotkit.json --data sales.csv -o sales.html    (an HTML report: open it in a browser)
  pivotkit validate sales-chart.pivotkit.json --data sales.csv --strict
  pivotkit describe sales.csv
Other examples: pivotkit example weather

Run what it prints, and open sales.html in a browser; the same view also gives a chart and a workbook:

pivotkit render sales.pivotkit.json --data sales.csv -o sales.html
pivotkit render sales-chart.pivotkit.json --data sales.csv -o trend.html      # with the chart
pivotkit render sales.pivotkit.json --data sales.csv -o sales.xlsx            # the same as Excel

pivotkit example weather writes the live demo's start (daily weather of 14 cities, with its licence in weather-SOURCE.txt); pivotkit example --list names the examples. It never writes over a file: in a directory that has one of its files it writes nothing.

Without the command, the same files are on this site:

curl -fsSLO https://pivotkit.eize.dev/assets/examples/sales.csv
curl -fsSLO https://pivotkit.eize.dev/assets/examples/sales.pivotkit.json

(all example files)

3. A view from your own file

Point it at a CSV, JSON or Excel file and it suggests a first view: text fields with few values as rows and columns, a date grouped by its span, the first number summed.

pivotkit describe sales.csv --suggest -o draft.pivotkit.json

draft: rows Region; columns Month by month; values Sum of Units
  other text fields: Country, Product, Category, Channel
  other numbers: Revenue, Discount
  to change a part: pivotkit describe sales.csv --suggest --values sum:Revenue (or --rows, --cols, --group <field>:<unit>)
wrote draft.pivotkit.json: a draft view of sales.csv
next: pivotkit render draft.pivotkit.json --data sales.csv -o draft.html

The draft reads types and counts, not meaning, so check what it picked and change a part with a flag:

pivotkit describe sales.csv --suggest --values sum:Revenue -o draft.pivotkit.json
pivotkit render draft.pivotkit.json --data sales.csv -o draft.html

Or say the whole layout yourself and render without a view file; --save-view keeps the view:

pivotkit render sales.csv --rows Region --cols Month --group Month:yearQuarter --values sum:Revenue -o by-quarter.html --save-view by-quarter.pivotkit.json

pivotkit render sales.csv --suggest -o draft.html does both in one step. For a workbook, --sheet picks the sheet (the first visible one otherwise; pivotkit describe book.xlsx lists them), and the view file names it. Views, Open view file in the report opens the view file on the same file and sheet, to go on there. Field names with spaces, the units of --group, --filter and --map: a view from the data's fields.

4. Render a report from the browser's files

A view applies to the data it was made on: the rows, with the fields under their own names. From a report in the browser (the live demo does it):

  1. Views, Download view (.pivotkit.json): the view file.
  2. Export, Source data, All rows as CSV (.csv): the rows. The application decides whether it offers this group (exportData); a file you loaded yourself you have already.

  3. Render them (the names are the playground's: the view is named after its name, the data after the application's file name with -data):

    pivotkit render revenue-by-region-and-category.pivotkit.json --data pivotkit-sales-data.csv -o report.html

The table's own CSV (Export, Table as CSV) is the result of the view, not its data: given as --data, the CLI says so and names what to take instead (when the data does not fit).

A view made on a sheet of an Excel workbook you loaded names that sheet; give the workbook as --data and the CLI reads that sheet (--sheet reads another; pivotkit describe book.xlsx lists the sheets) (the sheet of a workbook).

A view written by hand works too, as a file or as JSON text:

pivotkit render '{"rows":["Region"],"values":[{"field":"Revenue","agg":"sum"}]}' --data sales.csv -f csv

5. Check views in CI

validate exits 1 when a view has an error (with --strict also a warning), so a pipeline stops before a broken view is published. With the example files committed to reports/:

# .github/workflows/reports.yml
name: Reports
on: [push, pull_request]
jobs:
  reports:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install --global pivotkit-cli
      - run: pivotkit validate reports/sales.pivotkit.json --data reports/sales.csv --strict
      - run: mkdir -p out && pivotkit render reports/sales.pivotkit.json --data reports/sales.csv -o out/sales.html --now 2026-11-13

--now fixes "today" for relative date filters and the generated time, so the report is the same on every run. Pin the version (npm install --global pivotkit-cli@<version>) where the output must not change with a release.

PowerShell

--json writes one object on stdout, for a script:

$result = pivotkit validate sales.pivotkit.json --data sales.csv --json | ConvertFrom-Json
if (-not $result.ok) {
    $result.findings | Where-Object severity -eq 'error' | Format-Table code, path, message
    exit $result.exitCode
}
$written = pivotkit render sales.pivotkit.json --data sales.csv -o sales.xlsx --json | ConvertFrom-Json
$written.output.file      # sales.xlsx; .output.bytes its size

Shell completion: pivotkit completion powershell | Out-String | Invoke-Expression (bash, zsh and fish in the reference).

Next