Skip to content
Browse documentation
More resources

Command-line interface

Explore datasets from the terminal using persistent local sessions.

Start a session

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

bash
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 a language id (duckdb-sql, clickhouse-sql, postgresql, tsql, snowflake-sql, python, or javascript) and optional top-level instructions for dialect rules or execution bindings. 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 one or more inputs. Each can be a file path, a URL, @file containing a source configuration, or - to read one configuration from standard input. AVA infers file types from extensions and recognizes GitHub repository links. Use --type to set a common type for file paths or file URLs, or --type github for repository names in owner/name form.

Pass multiple inputs in one command to analyze them in the same session.

bash
ava source sales.csv customers.json costs.xlsx

Run ava schema <datasetId> with the returned ID to see the table names to use in queries. See Connect multiple sources for supported sources.

Use --engine to select an execution engine. The CLI infers Supabase, ClickHouse, SQL Server, and Snowflake for matching source configurations. The default for other sources is DuckDB. The engine is fixed for the session. Sessions with multiple sources use DuckDB. 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:

bash
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:

bash
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:

bash
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

bash
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 needs no API key: without --output, it validates the spec and returns { chartType, config }, filling in a missing config.type, for direct rendering in a page. With --output, it writes HTML to a new 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.

CommandPositional inputsFlags and defaults
sourceOne or more dataset inputs: path, URL, @file, or --t / --type: csv-file, json-file, parquet, excel, sqlite, github; file types are inferred from extensions. --engine: duckdb, python, javascript, supabase, clickhouse, sqlserver, snowflake; inferred as described above.
schemadataset-idOptional --file: path to an existing schema JSON file.
profiledataset-idOptional --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.
semanticdataset-idOptional --file: path to a Semantic JSON file that replaces the complete session definition. Without it, reads the current definition.
suggestdataset-id--count: integer 1–100; default 3.
analyzedataset-id, natural-language query--strategy: direct (default), loop; --max-rows and --max-result-bytes below.
translatedataset-id, natural-language queryNo additional flags.
querydataset-idRequired --dsl: code, @file, or -; non-empty and at most 512 KiB. Optional --max-rows and --max-result-bytes below.
visualizeNoneRequired --query: text; required --data: JSON array of objects, @file, or -; optional -o / --output: new HTML file path.
recommendNoneRequired --query: text; required --data: JSON array of objects, @file, or -.
vizNoneRequired --spec: JSON, @file, or -, containing chartType and a config object; optional -o / --output: new HTML file path. Without it, returns the validated spec.
disposedataset-idNo additional flags.
Shared execution flagTypeDefaultAccepted range
--max-rowsInteger2001–10000.
--max-result-bytesInteger1048576Positive safe integer.
Environment variableRequiredDefault / behavior
OPENAI_API_KEYFor AI commands and text extractionRead before source creation for dataset sessions; read at command time for standalone recommend and visualize.
OPENAI_MODELNogpt-4o-mini.
OPENAI_BASE_URLNoProvider default endpoint.

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:

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