Analyze CSV Files with a CLI

---
name: analyze-csv-workflow
description: "Profile the file, query it locally with DuckDB or csvkit, and save the analysis separately from the source."
---

# Analyze CSV files

## Intended outcome

Answer a tabular data question with reproducible commands and clearly stated data-quality limits.

## Evidence boundary

- Tool status distinguishes `docs-verified` material from independent execution; the two are not interchangeable.
- The current registry does not attribute a tool execution to a particular agent, so compatible agents cannot be called tested agents.
- Reconfirm the target account, environment, version, and official documentation before execution.
- Never auto-execute an R2, R3, or confirmation-marked step; obtain explicit approval immediately before it runs.

## Recommended tools, installation, and authentication

- **csvkit** (evidence: `docs-verified`, docs checked: `2026-07-10`, no independently executed version recorded)
  - Install: `pipx install csvkit`
  - Authentication: not required for the base operation
  - Minimum permissions: No service credential is required; restrict filesystem and network access to the task.
- **DuckDB CLI** (evidence: `docs-verified`, docs checked: `2026-07-10`, no independently executed version recorded)
  - Install: `brew install duckdb`
  - Authentication: not required for the base operation
  - Minimum permissions: No service credential is required; restrict filesystem and network access to the task.
- **jq** (evidence: `verified`, docs checked: `2026-07-10`, independently tested version jq-1.7.1-apple recorded)
  - Install: `brew install jq`
  - Authentication: not required for the base operation
  - Minimum permissions: No service credential is required; restrict filesystem and network access to the task.

## Input contract

- CSV path
- analysis question
- delimiter and encoding assumptions
- sensitive-column policy

## Output contract

- Schema profile
- bounded query result
- summary table
- data-quality warnings

## Safe workflow

1. **Profile the file** — Inspect size, header, inferred types, nulls, and a small sample.
   - Input: Source CSV
   - Output: Schema and quality profile
   - Risk: `read-only`
   - Command: `duckdb -c "describe select * from read_csv_auto('input.csv')"`
2. **Run bounded analysis** — Execute explicit SELECT queries without attaching or writing an external database.
   - Input: Reviewed SQL and source file
   - Output: Query results in CSV or JSON
   - Risk: `read-only`
   - Command: `duckdb -csv -c "select category, count(*) from read_csv_auto('input.csv') group by 1 order by 2 desc"`
3. **Save a reproducible summary** — Record commands, assumptions, row counts, and warnings in a separate artifact.
   - Input: Results and profile
   - Output: Analysis report
   - Risk: `local-write`

## Ask before proceeding

- Uploading the dataset
- Overwriting or rewriting the source CSV
- Joining sensitive data or exporting row-level records

## Rollback

- Keep analysis outputs in a separate directory
- Delete temporary extracts containing sensitive fields
- Restore generated files from version control if they replace existing reports

## Official sources

- [DuckDB CLI documentation](https://duckdb.org/docs/stable/clients/cli/overview.html) — Official CLI documentation for querying local files and formatting results.
- [jq manual](https://jqlang.github.io/jq/manual/) — Official filters, input modes, exit status, and JSON transformation reference.