Getting started with Fieldnotes

Fieldnotes records what produced a result: the parameters, the script, and the output file paths, so you can find them again years later. It works from the command line in any language, stores everything in a local SQLite database, and needs no server and no account. This guide walks through your first run.

We will use a tiny example project. Any folder with a script, some parameters, and an output directory works the same way:

exampleproject/
  params.json          {"grid_size": 64, "seed": 7, "method": "baseline"}
  run_simulation.py    reads params.json, writes the outputs
  results/
    output.csv
    figure.png

1. Install

Install the command-line tool with pipx:

pipx install fieldnotes

Coming with the beta. The fieldnotes package is not on PyPI yet; it ships with the public beta. Fieldnotes is one command-line tool that records runs in any language, Julia, Python, R, Fortran, MATLAB, so there is no separate library to install per language and nothing to add to your scripts. Join the waitlist to hear the moment it is ready.

2. Register the project

Move into your project directory and run init once. This records the project root, so output file paths can be stored relative to it and stay valid if you move the folder or switch machines.

cd exampleproject
fieldnotes init

Initialised project "exampleproject"
  Root:    /home/you/exampleproject
  Records: /home/you/.fieldnotes/fieldnotes.db

3. Log a run

After your script finishes, record the run. Point Fieldnotes at the script to snapshot, the parameter file to read, and the outputs to link. Tags and a note are optional but make runs easier to find later.

fieldnotes log \
  --script run_simulation.py \
  --params params.json \
  --output results/output.csv \
  --tag baseline \
  --note "first sweep"

1d5db656-a332-4327-b5ba-ea6d8f4ccd92

That printed the new run's id. Fieldnotes has stored a full copy of the script text, the parameters, the output path (relative to the project root), and a git commit hash if the project happens to be a git repository. Nothing about your data files moved: Fieldnotes stores pointers, never the files themselves.

On a cluster you can also pass --slurm-job-id and --walltime to record where and how long a job ran.

4. See your runs

show with no arguments lists recent runs. Pass a run id, or just the first few characters of one, to see the full record.

fieldnotes show

RUN ID          TIMESTAMP               TAGS                    METRICS
----------------------------------------------------------------------------------
1d5db656…       09 Jul 2026  12:45      baseline                -

fieldnotes show 1d5db656

Run:          1d5db656-a332-4327-b5ba-ea6d8f4ccd92
Timestamp:    09 Jul 2026  12:45
Project:      exampleproject
Tags:         baseline

Parameters:
{
  "grid_size": 64,
  "seed": 7,
  "method": "baseline"
}

Output files:
  results/output.csv

Script snapshot: 6 lines captured

If an output file is ever moved or deleted, the detail view flags it as missing and points you at fieldnotes locate, which searches for the file and updates the record. A missing file never makes the run itself unreadable; the metadata is always there.

5. Export for a paper or grant

When you need a methods section, export every matching run. Markdown produces a ready-to-paste "Computational Methods" summary; --format csv and --format json give you the raw records.

fieldnotes export --format markdown

That's it

You now have a permanent, queryable record of that run. Run fieldnotes log from the command line after each simulation or plotting run, and the record builds itself as you work. Everything lives in ~/.fieldnotes/fieldnotes.db on your machine, yours to keep.