Shell Commands

filecard provides four shell commands in addition to the interactive interface. These commands operate on the encrypted vault and exit immediately after completing their task.

Name resolution in all commands that accept a query argument follows this order:

  1. Exact case-insensitive name match.
  2. Single fuzzy match above the threshold (score ≥ 60).
  3. Top fuzzy match with score ≥ 90 is accepted without prompting.
  4. Multiple plausible matches: print candidates and exit with an error.

filecard

filecard

Launch the interactive interface. Decrypts the vault into memory, opens the list view, and re-encrypts the vault on exit. A timestamped backup is written on every clean exit.

filecard init

filecard init

Initialise a new vault. Fails if a configuration file already exists at ~/.config/filecard/config.json.

Steps:

  1. Lists available GnuPG secret keys with index numbers.
  2. Prompts for a key index.
  3. Creates ~/.local/share/filecard/ with mode 700.
  4. Creates the encrypted vault at ~/.local/share/filecard/vault.gpg.
  5. Writes ~/.config/filecard/config.json.

To start over, remove ~/.config/filecard/ and run init again. The old vault file is not deleted automatically.

filecard log

filecard log query -m message [-t type]

Append an event to a card without opening the interface. Useful for logging immediately after a meeting or call.

Arguments:

query : Name or partial name of the card. Resolved by fuzzy match.

Options:

-m message, --message message : Event content. Required.

-t type, --type type : Event type. Common values: meeting, call, message, observation, reminder. Any string is accepted. If omitted, an interactive numbered menu is shown.

Examples:

filecard log "Bonforte" -m "Met at the spaceport." -t meeting
filecard log "Dak" -m "Confirmed the flight plan."

The second example omits -t and shows a menu.

filecard export

filecard export query [-o file]

Export a card as formatted plain text. No ANSI codes are included in the output.

Arguments:

query : Name or partial name of the card. Resolved by fuzzy match.

Options:

-o file, --out file : Output file path. If omitted, output is written to stdout.

When -o is omitted, the output is suitable for piping:

filecard export "Bonforte" | mail -s "Brief" friend@example.com
filecard export "Bonforte" | head -20

When -o is specified, filecard writes the file and prints a confirmation line. If the file already exists it is overwritten.

Pressing x in the list view or edit view exports the current card to ~/.local/share/filecard/exports/ using the card name as the filename. That directory is created automatically on first use. The project directory is never used for export output.

Example output:

--------------------------------------------------------
John Bonforte
--------------------------------------------------------
  aliases          Lawrence Smith
  tags             politician, vip

  occupation       Minister of Foreign Affairs
  organisation     Expansionist Party
  born             1918

  relationships
    aide           Dak Broadbent

  notes
    2026-05-03  Never mention the 2115 election.

  events
    2026-05-02  [meeting]  Met at the spaceport.

--------------------------------------------------------
  created  2026-05-01   updated  2026-05-04
--------------------------------------------------------

filecard nuke

filecard nuke

Destroy vault and configuration.

  • Overwrites vault with random bytes (3 passes)
  • Deletes vault file
  • Removes all backup files from ~/.local/share/filecard/backups/
  • Deletes ~/.config/filecard/config.json
  • Prompts for confirmation

This operation cannot be undone. See Security for limitations of the overwrite approach on solid-state storage.