Metadata-Version: 2.4
Name: cli-charts
Version: 2.4.1
Summary: Terminal-visible chart toolkit — 24 chart types rendered directly in the CLI, no browser, no files.
License-Expression: MIT
Project-URL: Homepage, https://github.com/2233admin/chartex
Project-URL: Repository, https://github.com/2233admin/chartex
Project-URL: Changelog, https://github.com/2233admin/chartex/blob/main/CHANGELOG.md
Keywords: cli,charts,terminal,visualization,ascii,claude
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Terminals
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: plotext>=5.2
Requires-Dist: rich>=13.0
Requires-Dist: phart>=0.4
Requires-Dist: networkx>=3.0
Requires-Dist: sparklines>=0.4
Requires-Dist: pandas>=2.0
Requires-Dist: duckdb>=0.10
Requires-Dist: pyfiglet>=0.8
Requires-Dist: uniplot>=0.5
Provides-Extra: braille
Requires-Dist: drawille>=0.2; extra == "braille"
Provides-Extra: lttb
Requires-Dist: lttb>=0.3; extra == "lttb"
Provides-Extra: tui
Requires-Dist: textual>=0.50; extra == "tui"
Provides-Extra: all
Requires-Dist: drawille>=0.2; extra == "all"
Requires-Dist: lttb>=0.3; extra == "all"
Requires-Dist: textual>=0.50; extra == "all"

# cli-charts

> When AI lives in the terminal, visualization must live there too.

24 chart types rendered directly in your terminal — no browser, no generated files, no context switch.
`pip install cli-charts` and your AI agent has a native sense of sight inside the CLI.

```
demo.gif  <-- record with: python -m cli_charts.dashboard --demo --no-interactive
```

---

## Install

```bash
pip install cli-charts

# with LTTB downsampling (recommended for time-series):
pip install "cli-charts[lttb]"

# with Textual TUI dashboard:
pip install "cli-charts[tui]"

# everything:
pip install "cli-charts[all]"
```

## Quick start

```bash
# bar chart
cli-charts bar --json '{"labels":["Q1","Q2","Q3"],"values":[10,14,12]}' --title "Revenue"

# time series
cli-charts line \
  --json '[{"label":"DAU","x":[1,2,3,4,5],"y":[100,120,115,130,125]}]' \
  --title "Daily Active Users"

# pie chart
cli-charts pie \
  --json '{"labels":["Equity","Bond","Cash"],"values":[60,30,10]}' \
  --title "Asset Allocation"

# python -m also works:
python -m cli_charts bar --json '{"labels":["A","B"],"values":[3,7]}'

# check core dependencies:
cli-charts --check-deps
# include optional extras (braille/lttb/tui):
cli-charts --check-deps --all
```

## Chart types (24)

| Engine | Types |
|--------|-------|
| plotext | `kline` `candlestick` `line` `scatter` `step` `bar` `multibar` `stackedbar` `hist` `heatmap` `box` `indicator` `event` `confusion` |
| rich | `table` `tree` `panel` `gauge` `pie` `dashboard` |
| drawille *(optional `[braille]`)* | `curve` |
| uniplot | `uniplot` |
| misc | `graph` `sparkline` `banner` |

## All flags

```
cli-charts <type> [--json JSON | --file PATH | --duckdb SQL --db PATH]
                  [--title TEXT] [--width N] [--height N] [--theme THEME]
                  [--sample N] [--xlabel X] [--ylabel Y]
                  [--xlim MIN MAX] [--ylim MIN MAX]
                  [--xscale linear|log] [--yscale linear|log]
                  [--orientation vertical|horizontal]
                  [--output FILE] [--no-color]
```

**Width** defaults to `$COLUMNS` (terminal width). Override with `--width 120`.

**`--sample N`** uses LTTB (Largest-Triangle-Three-Buckets) downsampling — shape-preserving, not random stride. Falls back to uniform stride if `lttb` not installed.

## Pipe / file input

```bash
# stdin pipe (for large data)
cat metrics.json | cli-charts bar --title "Benchmark"

# file (use with --sample for large datasets)
cli-charts scatter --file ./data/million_points.json --sample 5000 --title "Correlation"
```

## DuckDB integration

```bash
cli-charts kline \
  --duckdb "SELECT trade_date,open,high,low,close FROM stock_daily WHERE ts_code='600519.SH' ORDER BY trade_date DESC LIMIT 60" \
  --db /path/to/data.duckdb \
  --title "Kweichow Moutai K-line"
```

| Chart type | Column mapping |
|-----------|----------------|
| kline / candlestick | col0=date, open/high/low/close by name |
| line / scatter / step / uniplot | col0=x, col1..N=y series |
| bar / pie | col0=labels, col1=values |
| table | all columns as-is |
| hist | all columns as value series |
| heatmap | matrix from .values, col names as xlabels |
| curve | col0=x, col1=y |
| sparkline | col0 values |
| confusion | col0=actual, col1=predicted |
| graph | col0=src, col1=dst (edge list) |

## Dashboard

```bash
# interactive Textual TUI:
python -m cli_charts.dashboard --demo

# Rich static (pipe-safe, no textual required):
python -m cli_charts.dashboard --demo --no-interactive

# custom panels:
cli-charts dashboard --json '{
  "panels": [
    {"type":"gauge","data":[{"label":"CPU","value":73,"max":100}],"title":"CPU"},
    {"type":"sparkline","data":{"values":[1,3,5,2,8,4,6]},"title":"Load"},
    {"type":"table","data":{"columns":["Host","Status"],"rows":[["web-01","OK"]]},"title":"Services"}
  ]
}' --title "System Health"
```

## Exit codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Bad input (JSON parse error or missing key) — `ERROR:json:` / `ERROR:schema:` on stderr |
| 2 | Missing dependency — `ERROR:dep: pip install <pkg>` on stderr |
| 4 | Render failed — `ERROR:render: <traceback last line>` on stderr |

## For Claude Code / AI agents

See [SKILL.md](SKILL.md) for the full AI usage contract: decision tree, schema reference, DO/DO NOT rules, and anti-patterns.

```bash
# Claude Code skill (no pip required — uses scripts/ shims):
SKILL=~/.claude/skills/cli-charts
python $SKILL/scripts/chart.py bar \
  --json '{"labels":["A","B","C"],"values":[3,7,5]}' \
  --title "Example"
```

## Environment variables

| Variable | Effect |
|----------|--------|
| `CLI_CHARTS_LOG=1` | Append render history to `.chart_history.jsonl` |
| `NO_COLOR` | Disable ANSI colors (https://no-color.org) |

## License

MIT
