filecard 0.1.3

GPG-encrypted personal dossier system for the command line.

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 (system package: gpg)
• A GnuPG secret key

Installation

git clone https://codeberg.org/duras/filecard
cd filecard
pip install -e .

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