Import & Export

Move your shell history in and out of Suvadu. Export to JSONL, CSV, or JSON for backups and analysis. Import from Suvadu's own format or directly from Zsh history files.

Exporting History

Use suv export to write your command history to stdout. By default, the output format is JSONL (one JSON object per line), which is easy to stream, parse, and pipe into other tools.

suv export

Flags

Flag	Description
`--format <FORMAT>`	Output format: `jsonl` (default), `csv`, or `json`.
`--after <DATE>`	Only export commands recorded after this date (e.g., `2024-01-01`).
`--before <DATE>`	Only export commands recorded before this date.

Examples

# Export entire history as JSONL (default)
suv export > history.jsonl

# Export as CSV, filtered to 2024 onwards
suv export --format csv --after "2024-01-01" > history.csv

# Export as a single JSON array
suv export --format json > history.json

# Export a specific date range
suv export --after "2024-06-01" --before "2024-07-01" > june-2024.jsonl

Importing History

Use suv import to load commands into Suvadu from an external file. Suvadu can ingest its own JSONL export format or parse raw Zsh history files directly.

suv import <FILE>

Flags

Flag	Description
`--from <FORMAT>`	Source format: `jsonl` (default) or `zsh-history`.
`--dry-run`	Parse and validate the file without writing anything to the database. Shows how many commands would be imported.
`--allow-duplicates`	Keep entries that match an existing command and timestamp. By default, JSONL import skips those duplicates.

Examples

# Import from a Suvadu JSONL export
suv import history.jsonl

# Import from Zsh history
suv import --from zsh-history ~/.zsh_history

# Dry run — see what would be imported without writing
suv import --from zsh-history ~/.zsh_history --dry-run

Migrating from Zsh

If you have an existing Zsh history file, you can bring your entire command history into Suvadu with a single command. This is typically the first thing you do after installing Suvadu.

suv import --from zsh-history ~/.zsh_history

Suvadu parses the extended Zsh history format (timestamps, durations) and deduplicates entries during import. Your original ~/.zsh_history file is never modified. Raw Bash history and Atuin-native exports are not supported import formats in Suvadu 0.4.0.

Tip: Run with --dry-run first to preview how many commands will be imported and verify the file is parsed correctly before committing.

Data Portability

Export and import work together to move your history between machines. The workflow is straightforward:

On the source machine, export your history: suv export > history.jsonl
Transfer the file to the target machine (e.g., scp, USB drive, cloud storage).
On the target machine, import the file: suv import history.jsonl

The import works against a brand-new database — Suvadu auto-creates a placeholder session for each session_id from the source machine, and re-maps tags by name (creating any tags it hasn't seen before).

Note: Since Suvadu 0.3.4, JSONL import skips entries whose command and timestamp already exist, so re-importing the same export is idempotent. Pass --allow-duplicates only when you intentionally want to keep duplicate rows. Zsh-history import also deduplicates by command and timestamp.

Backup Strategy

For a full, restorable snapshot of your database, use suv backup — it writes a consistent copy you can restore by swapping the file back. Schedule it with cron:

# Daily database snapshot
0 9 * * * suv backup

An export is best for portability and analysis rather than restore — it serializes history to JSONL/CSV for moving between machines or processing with other tools:

# Weekly portable export to a timestamped file
suv export > ~/backups/suvadu-$(date +%Y%m%d).jsonl

Format Details

JSONL

One JSON object per line. Each object contains the command string, timestamp, exit code, duration, working directory, and any associated metadata (tags, bookmarks, notes). This is the recommended format for backups and machine-to-machine transfer because it preserves all Suvadu-specific data.

JSONL, JSON, and CSV exports are plaintext. Protect exported files with the encryption and access controls provided by your transfer or storage system.

CSV

Standard comma-separated values with a header row. Good for opening in spreadsheets, importing into databases, or quick analysis with tools like awk or csvkit.

JSON

A single JSON array containing all entries. Useful when you need the entire dataset as one parseable object, for example when feeding it into a script or API.

Note: All data stays local. Export writes to stdout (redirect to a file yourself), and import reads from a local file. Nothing is sent over the network.