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

Option	Description
-m message	Event content (required for log)
-t type	Event type: meeting, call, observation, … If omitted, menu shown
-o file	Output file for export. If omitted, write to stdout

Interface

Full-screen terminal interface with two views.

List view

Key	Action
j, k	Move down / up
g, G	Jump to top / bottom
/	Live search — type to filter
Esc	Clear search and tag filter
t	Filter by tag
n	New card
Enter	Open card in edit view
x	Export card to file
d	Delete card (confirms)
q	Quit — encrypt vault + write backup

Edit view

Switch tabs with 1–5:

Tab	Contents
1 Identity	Name, aliases, tags
2 Facts	Key-value fields (standard + custom)
3 Relations	Role → name pairs
4 Events	Timestamped log, newest first
5 Notes	Dated free-text notes

Within any tab:

Key	Action
j, k	Move
Enter	Edit field in place
a	Add item
d	Delete selected item
x	Export card
Esc	Return to list view

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

Path	Purpose
~/.local/share/filecard/vault.gpg	Encrypted vault
~/.local/share/filecard/backups/	Compressed backups (vault-YYYYMMDD-HHMMSS.gpg.gz)
~/.config/filecard/config.json	GnuPG fingerprint and vault path

Environment

Variable	Description
EDITOR	Editor used by filecard edit --raw. Defaults to vi

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