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

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

Examples

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

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

# Import from Bash history
suv import --from bash-history ~/.bash_history

# Migrate from Atuin (its database is only ever read)
suv import --from atuin-db ~/.local/share/atuin/history.db

# 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. Every import path applies the same redaction and exclusion rules as live recording, and records where each row came from.

Migrating from Bash

suv import --from bash-history ~/.bash_history

A Bash history file stores only the command text, plus a timestamp when HISTTIMEFORMAT was set. A timestamped file keeps its real times and its multi-line command boundaries. A plain file has neither, so each line is imported as one command with an explicitly synthetic 1970-01-01 placeholder time rather than an invented one, and directory, exit code, duration and executor are stored as unknown — never a fabricated successful exit.

Migrating from Atuin

suv import --from atuin-db --dry-run ~/.local/share/atuin/history.db
suv import --from atuin-db ~/.local/share/atuin/history.db

Atuin has no dedicated full-fidelity export command, so the source contract is the database itself. Suvadu opens it read-only and reads it inside one transaction, so your Atuin history is never modified or copied elsewhere. Schemas from Atuin 18.0.0 to 18.23.0 are tested (history schema 20210422143411 to 20260818000000); an untested schema is rejected with its migration id rather than guessed at. The import keeps time, directory, exit code, duration, session, host and author, and records Atuin's row id, intent and shell as context — so re-running it does not duplicate what it already brought over. A backup of the Suvadu database is taken first unless you pass --no-backup.

Data Portability

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

1. On the source machine, export your history: suv export > history.jsonl
2. Transfer the file to the target machine (e.g., scp, USB drive, cloud storage).
3. 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).

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.