filecard

GPG-encrypted personal dossier system for the command line.

Inspired by the Farley File concept from Robert A. Heinlein's Double Star.

Requirements

• Python: 3.11 or later
• GnuPG: gpg binary must be in your $PATH.
• A GnuPG secret key
• System: Linux or OpenBSD (macOS/Windows untested).
• Environment: A terminal supporting curses (most standard Linux/BSD terminals).

Install from PyPI

pip install --upgrade filecard

Install from source

git clone https://codeberg.org/duras/filecard
cd filecard
pip install -e ".[dev]"

The -e flag installs in editable mode: changes to the source directory take effect immediately without reinstalling.

Setup

filecard init

Selects your GnuPG key, creates the encrypted vault, and writes the configuration file.

Synopsis

filecard
filecard init
filecard log query -m message [-t type]
filecard export query [-o file]
filecard nuke

Description

filecard stores structured notes about people in a single GnuPG-encrypted file called the vault.

Each person is represented by a card containing facts, notes, relationships, and a timestamped event log.

Invoked without arguments, filecard decrypts the vault into memory, launches an interactive terminal interface, and re-encrypts the vault on exit. Decrypted data never touches the filesystem.

On every clean exit, a compressed backup of the encrypted vault is written to the backups/ directory alongside the vault. Backups are timestamped; only the ten most recent are kept.

The log and export commands operate without launching the interface.

Commands

init

Initialise a new vault.

• Prompts for a GnuPG key
• Creates ~/.local/share/filecard/vault.gpg
• Creates ~/.config/filecard/config.json

log query -m message [-t type]

Append an event to a card without opening the interface.

• Resolution: exact match → fuzzy match
• Aborts if ambiguous
• If -t is omitted, an interactive type menu is shown

export query [-o file]

Export a card as plain text.

• -o specified → write to file
• -o omitted → write to stdout

nuke

Destroy vault and configuration.

• Overwrites vault with random bytes (3 passes)
• Deletes vault and config
• Prompts for confirmation

Options

Interface

Full-screen terminal interface with two views.

List view

Edit view

Switch tabs with 1–5:

Within any tab:

All edits are applied immediately. No explicit save step.

Pickers

Tags, event types, and relationship roles are selected through an interactive fuzzy picker: type to filter the list, j/k to move, Enter to confirm, Esc to cancel.

Files

Environment

GnuPG and gpg-agent handle encryption and passphrase caching. See gpg-agent(1) for cache timeout configuration (default-cache-ttl, max-cache-ttl).

Security

• Vault is encrypted with GnuPG public-key encryption
• Decrypted data exists only in process memory
• Backup files contain only encrypted data

nuke overwrites the vault with random bytes before deletion. This does not guarantee physical erasure on SSDs with wear leveling. Use full-disk encryption (Linux LUKS, OpenBSD softraid CRYPTO) for that guarantee.

edit --raw writes a plaintext JSON file to /tmp for the duration of the edit. Mount /tmp as tmpfs on Linux, or use OpenBSD where /tmp is typically memory-backed.

Examples

# First-time setup
filecard init

# Open the interface
filecard

# Log an event from the shell
filecard log "john" -m "met at the spaceport" -t meeting

# Log with interactive type menu
filecard log "john" -m "called to confirm"

# Export to stdout
filecard export "john"

# Export to file
filecard export "john" -o john.txt

# Destroy vault
filecard nuke

Documentation

man filecard

https://filecard.readthedocs.io/en/latest/

License

ISC