duckviz

Send local files or folders to the DuckViz web app from your terminal. The bytes never leave your machine — DuckViz fetches them directly from a one-shot loopback server the CLI runs on 127.0.0.1.

Usage

npx duckviz                  # prints --help (no path → no ingest)
npx duckviz .                # files in current dir (top-level only)
npx duckviz ./logs           # files in ./logs (top-level only)
npx duckviz ./logs -r        # ./logs recursively
npx duckviz sales.csv        # single file
npx duckviz a.csv b.csv      # multiple files

npx duckviz ./logs --fresh   # replace any existing session in the browser
                             # (default: append to active session)

npx duckviz . --url http://localhost:3001   # point at a local dev server

Flags

| Flag | Default | Description | | -------------------- | --------------- | ------------------------------------------------------ | | -r, --recursive | off | Recurse into subdirectories | | --fresh | off | Replace any existing browser session (default: append) | | --url <url> | app.duckviz.com | DuckViz web app URL | | --port <port> | random | Pin the local server port | | --no-open | off | Print URL instead of opening the browser | | --ignore <pattern> | — | Extra ignore pattern (repeatable) |

File selection

• Allowlist: csv, tsv, json, ndjson, xlsx, xml, log, txt, parquet
• Hidden files (starting with .) are always skipped
• .gitignore patterns are respected when present
• Folders are non-recursive by default — pass -r to walk subdirectories

How it works

1. CLI walks the path, builds a manifest of matching files.
2. CLI starts an HTTP server on 127.0.0.1:<random> with a one-time bearer token.
3. CLI opens https://app.duckviz.com/cli-receive?endpoint=…&token=… in your browser.
4. The web app fetches the manifest and downloads each file from the loopback server straight into DuckDB-WASM. No bytes go through DuckViz servers.
5. The CLI exits once the browser reports done.

The local server only listens on the loopback interface, requires the bearer token on every request, restricts CORS to the DuckViz origin, and shuts down after 10 minutes of inactivity.