Metadata-Version: 2.4
Name: filecard
Version: 0.1.7
Summary: GPG-encrypted personal dossier system for the command line.
Author-email: Sergiy Duras <sergiy@duras.org>
License-Expression: ISC
Project-URL: Homepage, https://pypi.org/project/filecard/
Project-URL: Repository, https://codeberg.org/duras/filecard
Project-URL: Bug Tracker, https://codeberg.org/duras/filecard/issues
Project-URL: Changelog, https://filecard.readthedocs.io/en/latest/changelog/
Keywords: gpg,encryption,cli,tui,contacts,personal-database,dossier,notes
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: BSD
Classifier: Operating System :: POSIX :: BSD :: OpenBSD
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Classifier: Topic :: Text Processing
Classifier: Topic :: System :: Archiving
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: python-gnupg>=0.5
Requires-Dist: rapidfuzz>=3.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Dynamic: license-file

# filecard

**GPG-encrypted personal dossier system for the command line.**

Inspired by the *Farley File* concept from Robert A. Heinlein's [Double Star](https://en.wikipedia.org/wiki/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

```sh
pip install --upgrade filecard
```

## Install from source

```sh
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

```sh
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

```sh
# 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

```sh
man filecard
```
<https://filecard.readthedocs.io/en/latest/>

## License

ISC
