Installation

Requirements

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

filecard has not been tested on macOS or Windows.

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.

Two entry points are installed: filecard and fcard. Both invoke the same program. fcard is a shorter alias for interactive use.

fcard          # same as: filecard
fcard log ...  # same as: filecard log ...

Python dependencies

The following packages are installed automatically:

Package Purpose
click Command-line argument parsing
python-gnupg Interface to the system gpg binary
rapidfuzz Fuzzy string matching for search

MkDocs is only installed if you use the [dev] extra.

Python's curses module is used for the terminal interface. It is part of the Standard Library and requires no separate installation.

GnuPG key

filecard requires an existing GnuPG secret key. If you do not have one, create it before running filecard init:

gpg --gen-key

Follow the prompts. Use a strong passphrase. The key type and size defaults are suitable.

First-time setup

After installation, run:

filecard init

This will:

  1. List available GnuPG secret keys. Select one by number.
  2. Create ~/.local/share/filecard/ with permissions 700.
  3. Create the encrypted vault at ~/.local/share/filecard/vault.gpg.
  4. Write ~/.config/filecard/config.json containing the selected key fingerprint and vault path.

The vault path can be changed by editing config.json directly. The GnuPG fingerprint field must match the key used to encrypt the vault.

Verifying the installation

filecard --help

Should list init, log, export, and nuke as subcommands.

filecard

Opens the TUI. Press q to quit.

Virtual environments

Using a virtual environment is recommended:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Upgrading

Pull the latest source and reinstall:

git pull
pip install -e .

No database migration is required between patch versions. If a major schema change is introduced, a migration script will be provided in the repository root.