dashcli

Agent-native BI dashboards from CSV and JSON files. Powered by Bun, SQLite, and ECharts.

dashcli suggest data.csv        # generate a dashboard spec from your data
dashcli serve spec.yaml         # live-reloading dashboard at localhost:3838
dashcli export spec.yaml        # standalone HTML you can email or host anywhere
dashcli read spec.yaml          # structured spec summary (text or JSON)
dashcli diff a.yaml b.yaml      # compare two specs, see what changed

Install — 30 seconds

Requirements: Claude Code, Git, Bun v1.0+

Step 1: Install on your machine

Open Claude Code and paste this. Claude does the rest.

Install dashcli: run git clone https://github.com/agi-bootstrap/dashcli.git ~/.dashcli && cd ~/.dashcli && ./setup then add a "dashcli" section to CLAUDE.md that says: dashcli is installed at ~/.dashcli. Use it to create data dashboards from CSV/JSON files. Commands: bun ~/.dashcli/src/index.ts suggest <file> generates a YAML dashboard spec on stdout, bun ~/.dashcli/src/index.ts serve <spec> launches a live-reloading dashboard at localhost:3838 (watches both spec and data files — auto-refreshes when either changes), bun ~/.dashcli/src/index.ts export <spec> creates standalone HTML, bun ~/.dashcli/src/index.ts profile <file> outputs column classification as JSON. When the user asks to visualize data, create a dashboard, or analyze a CSV/JSON file — use dashcli. Add --ai to suggest for LLM-powered specs (requires ANTHROPIC_API_KEY).

Step 2: Add to your repo so teammates get it (optional)

Add dashcli to this project: run cp -Rf ~/.dashcli .dashcli && rm -rf .dashcli/.git && cd .dashcli && ./setup then add a "dashcli" section to this project's CLAUDE.md listing the commands and telling Claude to use dashcli when the user asks to visualize data or create dashboards.

Real files get committed to your repo (not a submodule), so git clone just works. Everything lives inside .dashcli/. Nothing touches your PATH or runs in the background.

Manual install (without Claude Code)

git clone https://github.com/agi-bootstrap/dashcli.git ~/.dashcli
cd ~/.dashcli && ./setup

Then use bun ~/.dashcli/src/index.ts as the command, or add an alias:

alias dashcli='bun ~/.dashcli/src/index.ts'

Quick start

# scaffold a sample dashboard
dashcli create my-dashboard

# serve it
dashcli serve dashboards/my-dashboard.yaml
# open http://localhost:3838/d/my-dashboard

Or point at any CSV:

dashcli suggest data.csv > spec.yaml
dashcli serve spec.yaml

Commands

dashcli suggest <source> [--ai]

Generates a dashboard spec from a CSV or JSON file.

• Default (heuristic): Profiles columns, classifies types, generates a deterministic YAML spec. No API key, no network, under 100ms.
• --ai flag: Uses Claude to generate 3-5 richer specs with semantic understanding. Requires ANTHROPIC_API_KEY.

Both modes output YAML to stdout for composability.

dashcli serve <spec.yaml> [--port n]

Launches a local server on port 3838 with:

• Interactive filters (date range, dropdown, multi-select, range, text search)
• Live reload via SSE — edit the YAML or data file and the browser updates automatically
• Responsive layout (CSS Grid, mobile breakpoint at 768px)

dashcli export <spec.yaml> [--out dir]

Exports a self-contained HTML file with ECharts and all data embedded. Works offline, no server needed.

dashcli profile <source>

Outputs column classification as JSON — types, cardinality, sample values. Useful for agent composability.

dashcli create [name]

Scaffolds a new dashboard with sample data (sales.csv) and a ready-to-edit YAML spec.

dashcli read <spec.yaml>

Parses a YAML spec and outputs a structured summary: name, title, source, charts (id, type, position), filters, and layout. Works offline with no API key.

dashcli diff <specA> <specB>

Compares two dashboard specs and outputs a structured changelog keyed by chart/filter ID — added, removed, and changed items with field-level detail.

Global flags

Flag	Effect
--json	Outputs machine-readable JSON envelope: { ok, data, error: { message, code } }
--format <text|json>	Output format (--json always wins if both are set)

Error codes: SPEC_VALIDATION, FILE_NOT_FOUND, YAML_PARSE_ERROR, DATA_SOURCE_ERROR, RUNTIME_ERROR, UNKNOWN_COMMAND

Exit codes: 0 = success, 1 = validation/file error, 2 = data source error, 3 = runtime error

Dashboard spec

Dashboards are defined in YAML:

name: revenue
title: Revenue Dashboard
source: ./sales.csv
refresh: manual

filters:
  - id: period
    type: date_range
    column: date
    default: ["2025-01-01", "2025-12-31"]
  - id: region
    type: dropdown
    column: region
    default: all

layout:
  columns: 3
  rows: auto

charts:
  - id: total-revenue
    type: kpi
    query: "SELECT SUM(revenue) as value FROM sales WHERE {{period}}"
    label: Total Revenue
    format: currency
    position: [0, 0, 1, 1]

  - id: by-region
    type: custom
    query: "SELECT region, SUM(revenue) as total FROM sales WHERE {{period}} AND {{region}} GROUP BY region"
    label: Revenue by Region
    position: [1, 0, 2, 1]
    option:
      dataset: { source: "$rows" }
      xAxis: { type: category }
      yAxis: {}
      series:
        - type: bar
          encode: { x: region, y: total }

Chart types

Type	Required fields	Notes
custom	option (raw ECharts option object)	Full ECharts 5.6 API — bar, line, pie, scatter, gauge, heatmap, funnel, etc.
kpi	query (returns single value)	Supports format: currency, number, percent
table	query (returns rows)

custom charts use ECharts' dataset/encode pattern with data binding tokens:

Token	Resolves to	Example use
"$rows"	Full query result array	dataset: { source: "$rows" }
"$rows.column"	Array of values for one column	xAxis: { data: "$rows.region" }
"$row0.column"	Scalar from first row	data: [{ value: "$row0.value" }]
"$distinct.column"	Unique values for a column	xAxis: { data: "$distinct.region" }

A registered dashcli ECharts theme provides default colors, grid, axis styling, and per-series-type defaults (bar border-radius, line smoothing, pie donut, etc.) so most charts need only dataset, axis types, and series with encode.

Positions

Positions are [col_start, row_start, col_span, row_span], 0-indexed.

Filter types

Type	Default	Notes
date_range	["start", "end"]	BETWEEN ? AND ?
dropdown	all	column = ? or 1=1 when "all"
multi_select	[]	IN (?, ?, ...) via repeated query params
range	[min, max]	BETWEEN ? AND ? with numeric values
text	""	LIKE '%...%' with escaped wildcards

Use {{filter_id}} in queries. dashcli replaces filter placeholders with parameterized SQL.

Project structure

src/
  index.ts        CLI entry point
  server.ts       HTTP server + SSE live reload
  schema.ts       Zod-based spec validation
  viewer.ts       HTML/CSS/JS rendering
  query.ts        Filter interpolation + query execution
  datasource.ts   Data source abstraction (CSV/JSON -> SQLite)
  csv.ts          CSV parser + type inference
  json.ts         JSON adapter
  export.ts       Standalone HTML export
  suggest.ts      Heuristic + AI-powered spec generation
  profiler.ts     Column classification + type inference
  utils.ts        Shared utilities
  read.ts         dashcli read — spec summary output
  diff.ts         dashcli diff — spec comparison
  cli-utils.ts    JSON envelope, error codes, output formatting
  gen-schema.ts   JSON Schema generator (Zod -> JSON Schema)

schema/           Published JSON Schema for dashboard specs
sample/           Example dashboards and data
test/             Test suite (239 tests across 20 files)

Development

bun run dev              # run CLI in dev mode
bun run typecheck        # type-check without emitting
bun test                 # run test suite
bun run gen:schema       # regenerate JSON Schema from Zod spec

Design

Restrained, data-first aesthetic inspired by Bloomberg Terminal. System fonts, single accent color (#2563eb), 4px spacing grid. See DESIGN.md for the full design system.