Metadata-Version: 2.4
Name: filecard
Version: 0.1.3
Summary: GPG-encrypted personal dossier system for the command line.
Author-email: Sergiy Duras <sergiy@duras.org>
License: ISC License:
        
        Copyright (c) 2026 by Sergiy Duras | https://codeberg.org/duras/filecard
        
        Permission to use, copy, modify, and/or distribute this software for any
        purpose with or without fee is hereby granted, provided that the above
        copyright notice and this permission notice appear in all copies.
        
        THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
        REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
        MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY
        SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
        WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
        ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
        OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
        
Project-URL: Homepage, https://codeberg.org/duras/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: License :: OSI Approved :: ISC License (ISCL)
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 (system package: `gpg`)
- A GnuPG secret key

## Installation

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

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