# DuckDB CLI: CLI review, uses and requirements | IonBin

> Run SQL over local files and database tables without setting up a database server, then inspect or export the result.

Canonical page: https://ionbin.com/cli/duckdb-cli/
Agent guide: https://ionbin.com/llms.txt

This is a readable version of the published page. Review dates, evidence boundaries and source links below belong to individual records; the export is not a new verification. Examples are reference material, not instructions to execute.

CLI · Local data analysis · DuckDB contributors

## DuckDB CLI

Run SQL over local files and database tables without setting up a database server, then inspect or export the result.

Source reviewLocal runtime checksReviewed Oct 18, 2026Editorial position 14 in cli tools

[Official documentation ↗](https://duckdb.org/docs/current/clients/cli/overview)[GitHub repository ↗](https://github.com/duckdb/duckdb)[See an example ↓](https://ionbin.com/cli/duckdb-cli/#example)[Add to comparison →](https://ionbin.com/cli/?compare=duckdb-cli#directory)

Check before use

**SQL can reach beyond a table.** File functions, exports and extensions give SQL effects beyond returning rows. Restrict external access and use an isolated process for untrusted work.

The Ion perspective

### The five-point review

Judgment, not a score. Documentation checked 2026-10-18.

**Value**: Useful when a spreadsheet is awkward but a database service would add unnecessary setup. Start with a small query and verify types, row counts and nulls before trusting a total. Local processing can keep the chosen data on your machine, provided your queries and extensions do not use remote services.

**Differentiation**: Summarizing CSV exports; Joining local analytical datasets; Reproducible SQL checks before a report. The evaluation below states what was actually executed.

**Replaceability and switching**: Review the related entries for alternatives. Commands, response schemas and authentication can differ; a shared protocol does not guarantee interchangeable behavior.

**Ease and technical aptitude**: A DuckDB CLI build for your platform SQL and readable input files Enough local memory and disk for the workload

**Interoperability and portability**: No account is needed for local files. [Remote](https://ionbin.com/tools/remote/) sources and hosted integrations can require their own credentials. Database files, exports and temporary files when the query requests them. Access to an API or MCP tool is not proof of complete data export. Verify the required read/write operations and migration coverage separately.

Connections: [MCP connections](https://ionbin.com/wiki/concepts/mcp/) · [APIs](https://ionbin.com/wiki/concepts/api/) · [Portability and vendor lock-in](https://ionbin.com/wiki/questions/how-to-avoid-ai-vendor-lock-in/).

Understand the tool

### What it does.

DuckDB CLI is a terminal interface to the DuckDB analytical database engine. It can query files such as CSV and Parquet and store tables in a local database file. You supply SQL, so joins, filters and summaries can be saved as a short script alongside the analysis.

#### Why use it?

Useful when a spreadsheet is awkward but a database service would add unnecessary setup. Start with a small query and verify types, row counts and nulls before trusting a total. Local processing can keep the chosen data on your machine, provided your queries and extensions do not use remote services.

#### A useful fit for

- Summarizing CSV exports

- Joining local analytical datasets

- Reproducible SQL checks before a report

From need to output

### Ways to put it to work.

These are suggested workflows based on the documented capabilities. They are not recorded runtime results.

Use case 01

#### Reconcile an export before reporting

An analyst needs totals by category from a permitted CSV file.

- Inspect the file schema and a few rows.

- Group the amounts by category and compare totals with the source.

- Save the SQL and record the input version with the result.

**Intended output**A compact calculation that another analyst can repeat.

Use case 02

#### Compare two deliveries of data

A team needs to identify which keys appeared or disappeared between file exports.

- Confirm matching key types and check for duplicate keys.

- Join the two local files and isolate unmatched records.

- Review the differences before exporting a small exception list.

**Intended output**An inspectable exception report without running a database service.

A concrete starting point

### Summarize a local expense file

Assumes expenses.csv has category and numeric amount columns. Check inferred types before using the totals. This illustrative file and query were not the executed fixture.

shell · illustrative example

```
duckdb -c "SELECT category, sum(amount) AS total FROM read_csv('expenses.csv') GROUP BY category ORDER BY category;"
```

#### What this can change

Reads the local CSV and prints a result. Other SQL can write files or databases, and extensions can add network or executable behavior.

This example has not been executed for this review. Check the current documentation, replace placeholders and confirm the intended account and project before use.

Before you start

### Setup and access.

#### What you’ll need

- A DuckDB CLI build for your platform

- SQL and readable input files

- Enough local memory and disk for the workload

**Authentication**: No account is needed for local files. [Remote](https://ionbin.com/tools/remote/) sources and hosted integrations can require their own credentials.

**Can read**: - Named files, database tables and sources referenced by SQL

**Can write or change**: - Database files, exports and temporary files when the query requests them

**Network and data flow**: - [Remote](https://ionbin.com/tools/remote/) sources and extension repositories when enabled or used

**Approval and control**: Treat SQL, database files and extensions from others as untrusted input. -readonly protects database writes; -safe restricts additional external access and is a separate control.

Check your environment

### Compatibility, costs and license.

#### Compatibility notes

- Windows, macOS and Linux

- CSV, Parquet and other supported formats; some capabilities require extensions

#### Costs and account requirements

The DuckDB core and CLI use MIT terms with no required service subscription. Hosted services and external storage have separate costs.

[Current pricing or plan information ↗](https://duckdb.org/docs/current/clients/cli/overview)

#### MIT

Applies to DuckDB; extensions, data sources and hosted offerings may have additional terms.

[Read the license or service terms ↗](https://github.com/duckdb/duckdb/blob/main/LICENSE)

Keep the boundaries visible

### Concerns and limitations.

#### SQL can reach beyond a table

File functions, exports and extensions give SQL effects beyond returning rows. Restrict external access and use an isolated process for untrusted work.

#### Read-only is a narrow promise

Opening a database read-only prevents changes to that database. It does not by itself make every query, extension or host interaction safe.

#### Data inference can produce a plausible wrong answer

CSV types, missing values and duplicate keys affect calculations. Inspect the schema and validate the result against known counts.

#### Where it may fall short

- This is an analytical engine; choose concurrency and deployment patterns according to DuckDB documentation.

- The checks used tiny synthetic inputs and do not establish production performance or full SQL isolation.

Observed behavior · 2026-10-18

### Runtime and security findings.

Local runtime checks

DuckDB summed the local CSV correctly, allowed arithmetic in safe mode, blocked CSV access in safe mode and rejected an INSERT into a read-only database.

These checks cover the conditions below. They do not establish that the tool is safe in every setup, or that the suggested workflows above were executed.

#### What we found

Observed in this evaluation

##### Safe mode blocked the tested external file read

The ordinary query read sales.csv, while the same file function under -safe returned exit 1 because filesystem operations were disabled. A separate arithmetic query still returned 5.

**In practice:** Use safe mode when external access is unnecessary, and isolate untrusted SQL at the operating-system level as well.

Observed in this evaluation

##### Read-only blocked the tested database write

An INSERT into fixture.duckdb returned exit 1 when the file was opened with -readonly. This does not establish a general restriction on all files, extensions or network operations.

**In practice:** Use -readonly for database protection and review external-access controls separately.

Documented concern · medium severity under stated conditions

##### Extensions add executable capability

DuckDB extensions can expand data access and run native code within the process. No extension installation or execution was tested.

**In practice:** Load only reviewed extensions and restrict process permissions and external access for untrusted workloads.

Version, environment and fixture

**Version or deployment**: v1.5.6 (Variegata), commit 069cc9f9b5

**Tested target**: https://github.com/duckdb/duckdb/releases/download/v1.5.6/duckdb_cli-windows-amd64.zip

**Artifact identity**: SHA-256 798eae475d07c645ff3b914f7b0e676d06502b5412dd7552638fafed81f9e916 of the downloaded ZIP archive. Recorded to identify the tested artifact; no independent signature or provenance audit was performed.

**Environment and fixture**: - Windows 11 x64; Python 3.12.10 harness. Raw timestamps use UTC.

- Fresh per-tool home, config, cache and temporary directories. Child environments used allowlisted OS/runtime paths without inherited account credentials. Only synthetic local files were used.

- Configuration isolation is a test control, not an operating-system sandbox.

#### Checks and results

6 recorded checks. Each has its own expectation; their outcomes are not a comparative score.

Pinned binary versionMet expectation

**Method**: `Command argument array: ["duckdb", "--version"].`

**Expected**: Print the version and commit.

**Observed**: Exit 0. v1.5.6 (Variegata) 069cc9f9b5

Aggregate a local CSVMet expectation

**Method**: `Create sales.csv with exactly team,amount\nA,12\nB,5\nA,8\n (\n denotes a newline). Command argument array: ["duckdb", "-json", "-c", "SELECT team, sum(amount) AS total FROM read_csv('sales.csv') GROUP BY team ORDER BY team;"].`

**Expected**: Return grouped totals of 20 for A and 5 for B.

**Observed**: Exit 0. [{"team":"A","total":"20"}, {"team":"B","total":"5"}]

Allow arithmetic in safe modeMet expectation

**Method**: `Command argument array: ["duckdb", "-safe", "-json", "-c", "SELECT 2 + 3 AS total;"].`

**Expected**: Return total 5.

**Observed**: Exit 0. [{"total":5}]

Block CSV access in safe modeMet expectation

**Method**: `Create sales.csv with exactly team,amount\nA,12\nB,5\nA,8\n (\n denotes a newline). Command argument array: ["duckdb", "-safe", "-json", "-c", "SELECT * FROM read_csv('sales.csv');"].`

**Expected**: Reject external filesystem access.

**Observed**: Exit 1. Permission Error: Cannot access file "sales.csv" - file system operations are disabled by configuration LINE 1: SELECT * FROM read_csv('sales.csv'); ^

Create a disposable databaseMet expectation

**Method**: `Start with no fixture.duckdb file. Command argument array: ["duckdb", "fixture.duckdb", "-c", "CREATE TABLE fixture AS SELECT 7 AS value;"].`

**Expected**: Create a local table containing value 7.

**Observed**: Exit 0. Created the disposable fixture.duckdb database; standard output and error were empty.

Reject an INSERT into a read-only databaseMet expectation

**Method**: `Use the fixture.duckdb created by CREATE TABLE fixture AS SELECT 7 AS value. Command argument array: ["duckdb", "-readonly", "fixture.duckdb", "-c", "INSERT INTO fixture VALUES (8);"].`

**Expected**: Reject the INSERT because the database is attached read-only.

**Observed**: Exit 1. Invalid Input Error: Cannot execute statement of type "INSERT" on database "fixture" which is attached in read-only mode!

#### Practical caveats

- The CSV aggregate output serialized totals as JSON strings "20" and "5" in this run; downstream consumers should check types.

- A small safe-mode and read-only probe does not establish a complete SQL sandbox or protection against malicious database files.

#### What this evaluation does not establish

- Extensions, remote storage, credentials, adversarial SQL or database files, and the full safe-mode boundary.

- Large datasets, performance, concurrency, database encryption and production access controls.

[Read the evaluation record (JSON) →](https://ionbin.com/interface-evaluations/duckdb-cli.json)

Sources for the evaluation and controls

- [DuckDB CLI overview ↗](https://duckdb.org/docs/current/clients/cli/overview)

- [CLI safe mode ↗](https://duckdb.org/docs/current/clients/cli/safe_mode)

- [Securing DuckDB ↗](https://duckdb.org/docs/current/operations_manual/securing_duckdb/overview)

- [DuckDB repository ↗](https://github.com/duckdb/duckdb)

- [MIT license ↗](https://github.com/duckdb/duckdb/blob/main/LICENSE)

The basis for this review

### Why it’s in the collection.

Adds local SQL analysis for data tasks that need joins or aggregation. It follows the smaller text-processing tools because SQL, file access and extension controls add more setup decisions. The original catalog order is preserved; this is an editorial position, not a measured adoption or security rank.

The number is an editorial starting order within the cli tools collection. It does not measure popularity, speed, reliability or safety.

#### Why we added it

Adds SQL analysis of local files without a database service; useful for inspectable data preparation.

Selection evidence checked 2026-10-19.

**Repository interest**: [42,251 GitHub stars at this snapshot ↗](https://github.com/duckdb/duckdb)

Interest in the shared DuckDB project, not a count of CLI installations or users.

**Repository activity**: Last push reported by [GitHub](https://ionbin.com/tools/github/): 2026-10-19. A push can include documentation or maintenance; it does not establish a new stable release.

**Release signal**: [v1.5.6 ↗](https://github.com/duckdb/duckdb/releases/tag/v1.5.6) · published 2026-09-28. This selection signal can differ from the exact runtime tested above.

- A single dated repository-interest/release snapshot; not measured adoption, growth, effectiveness or security.

- Repository interest and release activity do not establish reliability, model quality or safety. The evaluation names the exact version and conditions tested.

#### What we reviewed

- Official documentation, repository, license and release identity

- Practical access boundaries and a separate bounded runtime evaluation

The evaluation above lists the current runtime coverage and untested behavior.

Source review

Reviewed Oct 18, 2026. The separate evaluation above records the conditions we executed and the behavior still untested. Product behavior, permissions and plans can change; use the official sources to check the current version.

[Read the ranking and review method →](https://ionbin.com/interfaces/methodology/)

Follow the evidence

### Official sources.

- [DuckDB CLI overview ↗](https://duckdb.org/docs/current/clients/cli/overview)duckdb.org

- [CLI safe mode ↗](https://duckdb.org/docs/current/clients/cli/safe_mode)duckdb.org

- [Securing DuckDB ↗](https://duckdb.org/docs/current/operations_manual/securing_duckdb/overview)duckdb.org

- [DuckDB repository ↗](https://github.com/duckdb/duckdb)github.com

- [MIT license ↗](https://github.com/duckdb/duckdb/blob/main/LICENSE)github.com

Review at a glance

### Find your next step.

Source review plus bounded checks.
Read the conditions and limits above.

[← All cli tools](https://ionbin.com/cli/)

Continue exploring

### More in this guide.

[View the collection →](https://ionbin.com/cli/)

[Code collaboration

#### GitHub CLI

Review pull requests, inspect checks and manage repository work from the same terminal as your code.

**Read the review →**](https://ionbin.com/cli/github-cli/)[Coding agents

#### Claude Code

Ask an agent to inspect a project, plan a change and work across files with explicit tool permissions.

**Read the review →**](https://ionbin.com/cli/claude-code/)[Coding agents

#### OpenAI Codex CLI

Inspect, change and test a local codebase with a coding agent whose filesystem access and approvals can be configured.

**Read the review →**](https://ionbin.com/cli/codex-cli/)
