Command-line interface

Start a session

After installing @antv/ava, use the ava binary (or npx ava for a local npm installation). Persistent sessions require macOS or Linux.

export OPENAI_API_KEY="YOUR_API_KEY"
export OPENAI_MODEL="gpt-4o-mini"
ava source sales.csv

The source command prints a dataset ID. Use that returned ID in subsequent commands. Model settings are fixed when the dataset is loaded; set them before source if you plan to use AI commands.

Explore and analyze

Replace DATASET_ID below with the ID from ava source.

ava schema DATASET_ID
ava profile DATASET_ID --metrics row_count,null_count,mean
ava suggest DATASET_ID
ava translate DATASET_ID "Total revenue by region"
ava analyze DATASET_ID "Total revenue by region" --strategy direct
ava query DATASET_ID --dsl @query.sql --max-rows 100
ava dispose DATASET_ID

The CLI supports direct, loop, and subset. Its --max-rows accepts 1–10,000 (default 200), while the JavaScript API allows a higher hard limit.

ava source accepts a file or URL, @file containing a source configuration, or - for standard input. File extensions infer CSV, JSON, Parquet, Excel, and SQLite sources. Override with --type when needed.

Use --engine to select an execution engine. The CLI infers Supabase and ClickHouse for matching source configurations; otherwise it defaults to DuckDB. This CLI inference differs from the JavaScript constructor.

Charts without a dataset session

ava recommend --query "Plot revenue by region" --data @rows.json > chart.json
ava viz --spec @chart.json --output chart.html
ava visualize --query "Plot revenue by region" --data @rows.json

recommend and visualize require the model. viz renders a spec without an API key and requires a new output file; existing files are not overwritten. Check that recommendation returned a spec rather than null before rendering it.

Command parameters

All commands accept -h / --help (boolean; optional). Every positional argument shown below is required.

Command	Positional inputs	Flags and defaults
`source`	`dataset`: path, URL, `@file`, or `-`	`-t` / `--type`: `csv-file`, `json-file`, `parquet`, `excel`, `sqlite`; inferred from extension. `--engine`: `duckdb`, `python`, `javascript`, `supabase`, `clickhouse`; inferred as described above.
`schema`	`dataset-id`	No additional flags.
`profile`	`dataset-id`	`--metrics`: comma-separated names; defaults to the standard metric set. Empty string selects no metrics.
`suggest`	`dataset-id`	`--count`: integer `1`–`100`; default `3`.
`analyze`	`dataset-id`, natural-language `query`	`--strategy`: `direct` (default), `loop`, `subset`; `--max-rows` and `--max-result-bytes` below.
`translate`	`dataset-id`, natural-language `query`	No additional flags.
`query`	`dataset-id`	Required `--dsl`: code, `@file`, or `-`; non-empty and at most 512 KiB. Optional `--max-rows` and `--max-result-bytes` below.
`visualize`	None	Required `--query`: text; required `--data`: JSON array of objects, `@file`, or `-`; optional `-o` / `--output`: new HTML file path.
`recommend`	None	Required `--query`: text; required `--data`: JSON array of objects, `@file`, or `-`.
`viz`	None	Required `--spec`: JSON, `@file`, or `-`, containing `chartType` and non-empty `syntax`; required `-o` / `--output`: new HTML file path.
`dispose`	`dataset-id`	No additional flags.

Shared execution flag	Type	Default	Accepted range
`--max-rows`	Integer	`200`	`1`–`10000`.
`--max-result-bytes`	Integer	`1048576`	Positive safe integer.

Environment variable	Required	Default / behavior
`OPENAI_API_KEY`	For AI commands and text extraction	Read before source creation for dataset sessions; read at command time for standalone `recommend` and `visualize`.
`OPENAI_MODEL`	No	`gpt-4o-mini`.
`OPENAI_BASE_URL`	No	Provider default endpoint.

Session lifecycle

Sessions expire after 30 idle minutes. dispose releases them immediately. Most commands return JSON; source prints a guide in terminals and JSON when piped. Errors go to standard error with exit code 1.

Run ava --help or ava <command> --help for command-specific options.

Use with an agent

The Agent Skill guide includes a copyable installation prompt, setup instructions, and a complete revenue-analysis demo. The agent uses the CLI to load data, execute its queries, and render charts with its own reasoning.

Commands such as analyze, suggest, and recommend still require the model settings described above.