# 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 ... ``` 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 :) 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@`) 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 - Every command, option, exit code and message: [pivotkit-cli reference](). - A column renamed since the view was made: [`--map Old=New`](). - The same from your own code, in Node or the browser: [getting started with reports](). - A print template with your logo and layout: [print template]().