Interface¶

filecard uses a full-screen terminal interface built with Python's curses library. It requires a terminal of at least 80 columns and 20 rows. The interface handles terminal resize at every keypress.

There are two views: the list view and the edit view.

List view¶

The list view is the main screen. It appears on launch and returns to it after every edit.

Layout¶

 filecard 0.1.0                    ~/.local/share/filecard/vault.gpg
 Name                         Tags              Organisation
 Dak Broadbent                pilot, trusted    ...
 John Bonforte                politician, vip   Expansionist Party
------------------------------------------------------------------------
 n:new  Enter:edit  x:export  d:del  /:search  t:tag  g/G:top/bot  q:quit

Row 0 is the title bar showing the program version and vault path. Row 1 is the column header. The middle rows are the scrollable card list. The last two rows are the divider and the persistent hint bar.

Columns¶

Column	Source
Name	`card.name`
Tags	`card.tags`, comma-joined
Organisation	`card.facts["organisation"]`, if set

Key	Action
`j` or `Down`	Move cursor down
`k` or `Up`	Move cursor up
`g`	Jump to first card
`G`	Jump to last card

The selected row is highlighted with reverse video.

Search¶

Press / to enter live search mode. The hint bar changes to show the current query with a cursor indicator. Type characters to filter the list in real time using fuzzy matching. The list updates with every keystroke.

While in search mode:

Key	Action
Any printable character	Append to query
`Backspace`	Remove last character
`j`, `k`	Move within filtered results
`Enter`	Open highlighted card
`Esc`	Exit search mode (filter remains visible)

Press Esc again from normal mode to clear the query entirely.

Active filters are shown in the hint bar in brackets: [/query], [#tag], or both.

Tag filter¶

Press t to open the tag picker. It lists all tags currently present in the vault. Select a tag to filter the card list to cards carrying that tag. Selecting replaces any previous tag filter.

Press Esc from normal mode to clear the tag filter.

Actions¶

Key	Action
`n`	Prompt for a name and create a new card. Opens edit view immediately.
`Enter`	Open selected card in edit view.
`x`	Export selected card to a plain text file in the current directory.
`d`	Delete selected card. Prompts for confirmation at the bottom line.
`q`	Quit. Re-encrypts the vault and writes a timestamped backup.

Edit view¶

The edit view presents a card across five tabs.

Layout¶

 [1:Identity]  [2:Facts]  [3:Relations]  [4:Events]  [5:Notes]
------------------------------------------------------------------------
         name : John Bonforte
      aliases : Lorenzo Smythe
         tags : politician, vip
------------------------------------------------------------------------
 1-5:tab  j/k:move  Enter:edit  a:add  d:del  x:export  Esc:back

Row 0 is the tab bar. The active tab is shown in orange. Inactive tabs are shown in normal terminal text. Row 1 is the divider. The middle rows are the scrollable field list. The last two rows are the divider and the persistent hint bar.

Field labels are right-aligned with a fixed : gutter. This creates a clean vertical separator between labels and values.

Navigation¶

Key	Action
`1`–`5`	Switch to the corresponding tab
`j` or `Down`	Move cursor down
`k` or `Up`	Move cursor up
`Enter`	Edit selected field in place, or activate action row
`a`	Add a new item in the current tab
`d`	Delete selected item (where applicable)
`x`	Export the current card to a plain text file
`Esc`	Return to list view

In-place editing¶

When Enter is pressed on an editable field, the field value becomes editable at its position in the form. The label remains visible. The hint bar remains visible. The edited region is highlighted in orange on black to indicate input mode.

Key	Action
`Left`, `Right`	Move cursor within the field
`Home` or `Ctrl-A`	Jump to start
`End` or `Ctrl-E`	Jump to end
`Backspace`	Delete character before cursor
`Delete`	Delete character under cursor
`Ctrl-K`	Delete from cursor to end of field
`Ctrl-U`	Clear entire field
`Enter`	Confirm edit and save
`Esc`	Cancel edit without saving

Every confirmed edit is written to the in-memory vault immediately. No explicit save step is required.

Tab 1: Identity¶

Field	Description
`name`	The card's canonical name
`aliases`	Alternate names, comma-separated. Used in fuzzy search.
`tags`	Labels, comma-separated. Used for tag filtering.

Tab 2: Facts¶

Standard fields are shown first: occupation, organisation, born, languages, location, nationality.

Editing a standard field to blank clears it. Custom facts can be added with a. To delete a custom fact, move to it and press d. Standard facts cannot be deleted via d; clear them by editing to blank.

Tab 3: Relations¶

Each row shows a role and the name of the related person. A role may appear multiple times if more than one person holds that relationship (for example, two siblings or three children). Press Enter on a row to edit that specific name. Press d to delete that specific entry without affecting other names under the same role.

Press a to add a new relation. Two pickers open in sequence:

Role picker — standard roles with a custom option.
Name picker — existing card names with a custom option for names not yet in the vault.

Tab 4: Events¶

Events are shown newest first. Each row shows the date and type as the label, and the event content as the value. Press Enter to edit the content. The timestamp and type are fixed after creation.

Press a to log a new event. A type picker opens, then a content prompt appears at the bottom line.

Press d to delete an event.

Tab 5: Notes¶

Notes are stored with the date they were added. The date is the label; the text is the value. Press Enter to edit the text of a note. Press d to delete a note.

Press a to append a new note. A prompt appears at the bottom line.

Pickers¶

Pickers are overlay screens used for selecting tags, event types, relationship roles, and relationship target names. They take over the full terminal for the duration of the selection.

 Event type
------------------------------------------------------------------------
> meet_
  meeting
  message
  observation
------------------------------------------------------------------------
 Enter:select  j/k:move  Esc:cancel

Type characters to filter the list by fuzzy match. Use j and k to move the cursor. Press Enter to select the highlighted item.

When allow_custom is active — for event types, relationship roles, and relationship names — a use: <query> row appears at the bottom of the list when you have typed something. Selecting that row returns your typed text as-is, allowing values not in the standard list.

Press Esc to cancel without selecting anything.