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.

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.

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

Suvadu deduplicates by command timestamp and content, so importing the same file twice is safe — no duplicate entries will be created.

Backup Strategy

A simple backup is just a periodic export. For example, add a cron job or alias:

# Weekly backup 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.

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.