SFTP
The SFTP adapter downloads files from remote servers over SSH. Unlike other adapters, SFTP is a transport-only adapter — it downloads raw files rather than producing canonical CSV.
Provide SSH credentials via private key, password, or SSH agent.
Private key:
vgrid fetch sftp --host files.example.com --user deploy --key ~/.ssh/id_ed25519 ...Password:
export SFTP_PASSWORD=...vgrid fetch sftp --host files.example.com --user deploy ...SSH agent: If neither --key nor --password is provided, VisiGrid falls back to the SSH agent.
vgrid fetch sftp \ --host files.example.com --user deploy --key ~/.ssh/id_ed25519 \ --remote-dir /exports/daily \ --glob "*.csv" \ --out ./downloads/List available files without downloading:
vgrid fetch sftp \ --host files.example.com --user deploy --key ~/.ssh/id_ed25519 \ --remote-dir /exports/daily \ --list-onlyOptions
Section titled “Options”| Flag | Description | Default |
|---|---|---|
--host |
SFTP hostname | required |
--port |
SFTP port | 22 |
--username / --user |
SSH username | required |
--private-key / --key |
Path to SSH private key | — |
--passphrase |
Key passphrase | SFTP_KEY_PASSPHRASE env |
--password |
Password auth | SFTP_PASSWORD env |
--remote-dir |
Remote directory to scan | required |
--glob |
Filename filter pattern | *.csv |
--min-age |
Min seconds since mtime before downloading | 120 |
--since |
Only files with mtime >= this date (YYYY-MM-DD) | — |
--out |
Output directory for downloaded files | — |
--stdout |
Write single file to stdout | off |
--known-hosts |
Path to known_hosts file | ~/.ssh/known_hosts |
--known-hosts-out |
Where to write TOFU’d keys | — |
--trust-on-first-use |
Accept unknown host key and save it | off |
--overwrite |
Overwrite even if content hash matches | off |
--max-files |
Limit number of files to download | — |
--list-only |
Dry run: print files newest-first and exit | off |
--provenance |
Provenance output: sidecar, stderr, or none |
sidecar |
--state-dir |
Directory for seen.jsonl state file |
— |
--reprocess |
Re-download even if recorded in state-dir | off |
-q / --quiet |
Suppress progress messages | off |
Date handling
Section titled “Date handling”Not applicable — SFTP downloads raw files and does not produce canonical CSV rows. Use --since to filter files by modification time.
Host key verification. VisiGrid checks the server’s host key against known_hosts (OpenSSH format). Use --trust-on-first-use to accept an unknown key and save it. On key mismatch, VisiGrid errors with both the presented and expected fingerprints.
Min-age filter. Files must be at least --min-age seconds old (default: 120) before they are downloaded, preventing partially-written files from being picked up.
Content-based dedup. VisiGrid computes a BLAKE3 hash during download. If a file already exists locally with a matching hash, it is skipped. Use --overwrite to force re-download.
State tracking. With --state-dir, VisiGrid maintains a seen.jsonl file recording each downloaded file’s path, mtime, size, and BLAKE3 hash. Previously-seen files are skipped on subsequent runs.
Provenance sidecar. Each downloaded file gets a .{filename}.visigrid.json sidecar containing the SFTP URI, file size, mtime, BLAKE3 hash, host key fingerprint, and CLI version.
Atomic writes. Files are written to a .part temporary file first, then atomically renamed on completion.
Stdout mode. Requires exactly one matching file. Provenance is written to stderr by default.