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.
ava source sales.csv > session.json
DATASET_ID=$(node -p 'JSON.parse(require("fs").readFileSync("session.json", "utf8")).datasetId')
ava schema "$DATASET_ID" > schema.jsonsource returns a session ID after preparing the source. Schema discovery happens on demand; schema returns the source structure plus language (name, fence, and optional instructions) for writing queries. Repeated schema calls use the session's cached structure. Known queries can run without a separate schema call.
Structured source loading, schema, profile, query, and viz do not need a model key. Set OPENAI_API_KEY and optional OPENAI_MODEL / OPENAI_BASE_URL before creating a session if you plan to use AI commands or a text source. Session model settings cannot be changed afterward.
Source inputs and engines
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 for path inputs; configuration files and stdin already include their type.
Use --engine to select an execution engine. The CLI infers Supabase and ClickHouse for matching source configurations; otherwise it defaults to DuckDB. This inference differs from the JavaScript constructor. The engine is fixed for the session. See source configurations for connection and reader settings.
Reuse saved metadata
After loading a source, use --file on schema or profile to supply an existing JSON file:
ava schema "$DATASET_ID" --file schema.json
ava profile "$DATASET_ID" --file profile.jsonPass a plain file path, without @. AVA validates the file and saves its contents in the session. Setting schema clears the saved profile, so set schema first when supplying both. Setting profile only replaces the statistics; it does not replace schema. Use metadata matching the loaded source.
Without --file, schema uses the cached structure or discovers it through the engine, and profile computes fresh statistics. --file cannot be combined with --metrics. See schema behavior and profile behavior.
Explore and analyze
Inspect statistics and execute a query:
ava profile "$DATASET_ID" --metrics row_count,null_count,mean > profile.json
ava query "$DATASET_ID" --dsl @query.sql --max-rows 100 > result.jsonprofile without --file recomputes statistics on each call. --metrics replaces the default metric list. For a few statistics on a large database, prefer targeted queries.
With model settings configured at session creation, use these commands for natural-language work:
ava suggest "$DATASET_ID"
ava translate "$DATASET_ID" "Total revenue by region"
ava analyze "$DATASET_ID" "Total revenue by region" --strategy directThese operations discover schema if needed and use an available profile. The CLI supports direct and loop. Its --max-rows accepts 1–10,000 (default 200), while the JavaScript API allows a higher hard limit.
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.jsonrecommend 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 | Optional --file: path to an existing schema JSON file. |
profile | dataset-id | Optional --file: path to an existing profile JSON file. Otherwise, --metrics selects comma-separated metric names; defaults to the standard metric set. An empty string computes no statistics. |
suggest | dataset-id | --count: integer 1–100; default 3. |
analyze | dataset-id, natural-language query | --strategy: direct (default), loop; --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 a config object; 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. Reload the source to obtain a new ID.
Dispose of sessions when finished:
ava dispose "$DATASET_ID"Most commands return JSON; source prints a guide in terminals and JSON when piped or redirected. Errors go to standard error with exit code 1. Schema discovery errors can occur after source creation; an existing session can still execute known queries or retry schema discovery.
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.