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.

ava source sales.csv > session.json
DATASET_ID=$(node -p 'JSON.parse(require("fs").readFileSync("session.json", "utf8")).datasetId')
ava schema "$DATASET_ID" > schema.json

source 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, semantic, 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, profile, or semantic to supply an existing JSON file:

ava schema "$DATASET_ID" --file schema.json
ava profile "$DATASET_ID" --file profile.json
ava semantic "$DATASET_ID" --file semantic.json

Pass 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. Setting semantic replaces the complete business definition and retains schema/profile; schema/profile updates also retain semantic. Use metadata matching the loaded source.

Without --file, schema uses the cached structure or discovers it through the engine, profile computes fresh statistics, and semantic returns the saved definition (initially {}). For profile, --file cannot be combined with --metrics. See schema behavior, profile behavior, and business definitions.

Keep semantic JSON files to reuse confirmed metric definitions across sessions. A file containing {} clears the session's semantic definition. Invalid files leave the previous definition intact. Validation checks the JSON structure, not SQL correctness or whether the business rules fit the source. The CLI does not automatically find, merge, or persist semantic files outside the session.

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.json

profile 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 direct

These operations discover schema if needed and use an available profile and loaded semantic definitions. query executes DSL as written; semantic does not rewrite it or create database objects. 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.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.

Session lifecycle

Sessions expire after 30 idle minutes. Reload the source to obtain a new ID and reapply saved semantic definitions after checking that they still match the source.

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.