DuckDB CLI for coding agents

A coding agent that needs to inspect a CSV or Parquet file can use DuckDB to run SQL directly from the shell. DuckDB is an analytical database, and its command-line program runs SQL in the terminal. The example below reads local data and returns a grouped summary without writing a Python script or changing the source file.

The agent starts the CLI with the duckdb command, passes a SQL statement with -c, and reads the result in the terminal. This approach works well for focused questions about local data, such as counting records or comparing totals. The CLI arguments documentation describes command syntax and output options.

Install and check the CLI

The DuckDB installation page lists the CLI downloads for each operating system. On macOS and Linux, it gives this install script:

curl https://install.duckdb.org | bash

On Windows, the page lists a PowerShell install script and a winget package. Make the duckdb executable available on your shell’s PATH, then check that it runs:

duckdb -c "SELECT version();"

The -c option runs the supplied SQL and exits. DuckDB opens a temporary in-memory database when you do not provide a database file, so this check does not create a persistent database.

The example uses only a local CSV file, so it needs no database account or credentials. If an agent later queries a remote database or protected storage, provide credentials through the appropriate local configuration or secret store. Do not paste secrets into the agent prompt.

Query a local CSV file

Create a small sample CSV file in the project directory. It contains three sales records:

cat > sales.csv <<'EOF'
region,amount
West,12
West,8
East,15
EOF

Ask DuckDB to group the rows by region and total the amounts:

duckdb -c "SELECT region, SUM(amount) AS total FROM read_csv('sales.csv') GROUP BY region ORDER BY region;"

read_csv reads the local CSV and detects its column types automatically. After grouping records by region, the query adds each group’s amount and sorts the results by region. With the sample rows above, the result contains East with a total of 15 and West with a total of 20. By default, the CLI shows query results as a table in its duckbox output mode.

For output that is easier to pass between shell commands, use the documented -csv output option:

duckdb -csv -c "SELECT region, SUM(amount) AS total FROM read_csv('sales.csv') GROUP BY region ORDER BY region;"

This prints the result as comma-separated values. If the agent wants to parse the rows as data, -json prints them as a JSON array instead. The query uses SELECT, so it reads the file without changing it. The shell command creates the example CSV, and DuckDB leaves it unchanged.

DuckDB 2.0 also has an agent mode for output that an AI coding agent reads. In this mode the CLI prints compact Markdown tables with a row count, and it prints errors as JSON on stderr. Large results are cut to their first and last rows, along with the total row count. The mode turns on by itself when a known agent environment variable such as AI_AGENT is set and the output goes to a pipe. An output flag like -csv keeps it off. The -agent flag forces it on:

duckdb -agent -c "SELECT region, SUM(amount) AS total FROM read_csv('sales.csv') GROUP BY region ORDER BY region;"

Give the agent a bounded task

A useful prompt names the file and asks a specific question. It also tells the agent to keep the query read-only:

Use DuckDB CLI to summarize sales.csv by region. Show the SQL command and report each region’s total. Use read-only SQL and do not modify the file.

The agent can run the command, inspect the result, and adjust the SQL if DuckDB reports an error. The CLI makes the query and returned values visible in the shell, but it does not guarantee that the agent chose the right columns or interpretation. Check the query and its result when the answer will inform a consequential decision.

DuckDB reads sales.csv and runs the SQL locally. Querying remote files or databases adds network access and may require separate credentials and configuration. DuckDB’s Parquet guide shows how to query a Parquet file directly with read_parquet, another common use for local data analysis.

Know when the CLI is not enough

DuckDB lets an agent query files directly. A DuckDB database file has limits when several programs use it at the same time. The concurrency documentation says one process can read and write a database file. Several processes can open the same file only in read-only mode. When an agent should only read a database file, start the CLI with -readonly and the file name. For writes from several processes, the same page describes two other setups, the Quack remote protocol and the DuckLake format.

For a coding agent inspecting project data, start with a local, read-only query and review the SQL alongside the result. Use the CLI’s output options when another shell command needs to consume the rows.