v1.3.0 — 2025‑09‑01 — Eric Andresen <Andresen.Eric@gmail.com>

############################################################
#                         Cheat Sheet                      #
############################################################

*Run (Windows/macOS/Linux):*
  - macOS/Linux: `python3 jkeep.py`
  - Windows: `python jkeep.py` or `py -3 jkeep.py`

*Top‑level flow:*  select a database (or create one) → work with
it → close when done.  Use the **root menu** to manage entire
databases and the **database menu** to work with records and
fields.  Pagination controls (`f` next, `b` prev, `w` wrap,
`v` detail, `c` columns, `/` search, `o` sort, `p` pager) are
available when listing records.

############################################################

There is a lot of technical detail in this README but none of it is needed to use the app. To try it out right away all you need is Python 3.8+ installed. Put jkeep.py in an empty folder, run python3 jkeep.py (or python jkeep.py on Windows) and follow the menu prompts. Play around—you won’t break anything. If you ever want to start over just delete every file in the folder except jkeep.py and launch the program again. It will recreate what it needs.

Jkeep provides a lightweight database that runs entirely on the command line. Each database lives in its own .json file and contains a small metadata header and a list of records. There is no server and no external dependency; everything persists in plain JSON on disk. This makes it portable—you can copy jkeep.py and your .json files anywhere and pick up where you left off. Use it to track assets, files, contacts, tasks or any free‑form data you like.

This release brings a number of quality‑of‑life improvements:

• Pagination — Records are displayed in pages that resize to your terminal. On a large terminal you see more rows; on a small one fewer. Press f or space to advance, b to go back and Enter or x to return to the menu.
• Wrap or truncate — Press w while viewing a list to toggle between truncating long fields to a single line and wrapping values across multiple lines. Wrapped rows take up more space, so the page size adjusts automatically.
• Detail card view — Press v (or choose the option at the prompt) to view a single record in full. Use f and b to step through neighbouring records and x or Enter to return.
• Column chooser — Press c to select which fields you want to see in the list. The selection persists between sessions.
• Search and sort — Press / to filter records by a search term (case‑insensitive). Press o to sort by any field in ascending or descending order.
• Pager — Press p to dump the entire (filtered and sorted) list to a system pager (less on Unix, more on Windows).

All of these features are implemented using only the Python standard library and require no additional installation.

After starting the program you are presented with the root menu. From here you can:

• List databases — See all .json files in the folder that are recognised as Jkeep databases. The list shows the name, created and modified dates and record count for each.
• Open database — Load an existing database and automatically create a ~backup.json copy of the file. The program remembers the last database you opened and will auto‑open it next time.
• Create new database — Enter a name and Jkeep writes a new empty .json file. The file will be named <name>.json.
• Rename database — Change the name of an existing database. This renames the file and updates the internal metadata.
• Delete database — Permanently delete a database and its backup. You must type DELETE to confirm.
• Import CSV — Convert a comma‑separated file into a new database. The first row of the CSV becomes the field names. An id column is ignored; Jkeep will generate unique record IDs.
• Export CSV — Write an existing database to <name>.csv. If the file exists Jkeep adds a numeric suffix to avoid overwriting.
• Recover — Restore a database from its ~<file>.json backup.
• Settings — Reorder menu items to suit your preference. The Exit option and Recover are fixed at the bottom and can’t be moved.
• Exit — Quit the program.

Once you open a database the menu changes to operations on records and fields:

• Add record — Enter values for each field and append a new record. Record IDs are assigned automatically.
• List records (paginated) — View your data using the pagination and navigation keys described above.
• Edit record — Update any field of a single record. You can keep the current value by pressing Enter.
• Delete record — Remove a record permanently after confirmation.
• Create field (column) — Add one or more new fields to the database. Existing records are updated with blank values for the new field. You can enter multiple field names one after the other and finish by pressing Enter on a blank line.
• Remove field (column) — Delete a field from all records. You must type REMOVE to confirm.
• Save database — Write changes to disk. Jkeep also autosaves when you add, edit or delete records and fields.
• Close current database — Return to the root menu.
• Recover from backup — Restore the currently open database from its backup.
• Exit — Quit the program.

When you choose “List records (paginated)” a view appears that fills your screen between a header and a footer. The following keys are active:

• f or space — next page
• b — previous page
• w — toggle wrap/truncate
• v — view a single record in detail
• c — choose which columns (fields) are displayed
• / — search (filter) by keyword
• o — sort by a field (asc/desc)
• p — open the list in a pager (less or more)
• Enter or x — return to the menu

While in the detail card view (press v), you can press f and b to step through the records or x/Enter to return to the list.

Jkeep uses only Python’s standard library. That means you just need Python 3.8 or later installed on your system. All of the file reading, JSON handling, CSV import/export and interactive keyboard input work across Windows, macOS and Linux. No database server, pip installs or virtualenvs are required.

Run the program from Command Prompt or PowerShell:

python jkeep.py

If you have multiple Python installations you might need to use py -3 jkeep.py to force Python 3. When listing records the program uses more to display the pager. If more is not available the pager option is ignored.

Open a terminal and run:

python3 jkeep.py

The pager uses less. If less is not installed the pager option is ignored.

The code is contained entirely in jkeep.py. If you wish to modify it or submit a patch you can treat the version number in APP_VERSION as authoritative. The project follows semantic versioning. This release (1.3.0) adds new functionality but does not break file formats from 1.2.x — existing databases will continue to load and work normally.