PitSeeder 3.7.5

PitSeeder

PitSeeder (pits) is a .NET command-line tool for working with JsonPit data stores. It can seed pits from JSON/JSON5 source files, export pits to JSON, and produce resolved WWWA exports where foreign key references are expanded inline.

Within this repository, PitSeeder lives under RAIkeep/PitSeeder so it can build against the local JsonPit and OsLib sources before those packages are published.

Install

After the package is published to NuGet:

dotnet tool install --global PitSeeder

On macOS or Linux, a practical option is to install directly into a directory on your PATH:

sudo dotnet tool install PitSeeder --tool-path /usr/local/bin

To update:

sudo dotnet tool update PitSeeder --tool-path /usr/local/bin

CLI Reference

pits [options] [<pit name>]

Features

Seed a single pit

Import a JSON5 file into a pit under the given pit root:

pits -s ./sample/Person.json5 -r ./output/

This creates ./output/Person/Person.pit.

Seed the WWWA set

Import all four WWWA files (Person, Object, Place, Activity) from a source directory:

pits -s ./sample/ -r ./output/ --wwwa

Export a single pit to a file

pits -r /path/to/pitroot/ Person -e ~/export/

Writes ~/export/Person.json containing the projected current state of all items.

Export a single pit to stdout

pits -r /path/to/pitroot/ Person --json

Output:

[
  {
    "Id": "Nomsa",
    "Name": "Nomsa Burkhardt",
    "Instruments": ["Voice", "Percussion", "Dance"],
    "Deleted": false,
    "Modified": "2026-04-06T04:06:10.349+00:00"
  },
  ...
]

Pipe to jq

Because --json writes to stdout, standard UNIX piping works:

pits -r /path/to/pitroot/ Person --json | jq '.[] | select(.Id == "Nomsa") | .Instruments'

["Voice", "Percussion", "Dance"]

Export all WWWA pits with resolved foreign keys

pits -r /path/to/pitroot/ --wwwa -e ~/export/

Writes ~/export/wwwa.json with all four pits merged into a single JSON object. Foreign key references in Who, What, Where, and Activity sections are resolved one level deep. Resolved wrappers dissolve and their contents are promoted to the item level; unresolved wrappers remain as-is.

For example, an Activity item with:

{
  "Who": { "Performer": "Nomsa" },
  "Where": { "Venue": "SDZSafariPark" }
}

becomes:

{
  "Performer": { "Id": "Nomsa", "Name": "Nomsa Burkhardt", "Instruments": ["Voice", "Percussion", "Dance"] },
  "Venue": { "Id": "SDZSafariPark", "Name": "San Diego Zoo Safari Park", "Homepage": "https://sdzsafaripark.org/" }
}

The same works with stdout:

pits -r /path/to/pitroot/ --wwwa --json | jq '.Activity[] | select(.Id == "SDZSP26") | .Venue.Name'

"San Diego Zoo Safari Park"

Cloud provider support

Use -c to look up a cloud storage root from ~/.config/RAIkeep.json5:

pits -c OneDrive -r RAIkeep/WwwaTests/ Person --json

This resolves the cloud root from the config and prepends it to the pit root.

PitRoot inference

When -s points to a .pit file, the pit root is inferred automatically by stripping the canonical folder:

pits -s /cloud/RAIkeep/WwwaTests/Person/Person.pit --json

No -r needed.

Help with resolved paths

Pass -h with other parameters to see all paths fully resolved:

pits -h -n -r /cloud/RAIkeep/WwwaTests/

The help display shows which pits exist at the given root.

WWWA Data Model

WWWA stands for Who, What, Where, Activity. It is a convention for organizing data across four canonical pits:

Items in any pit can reference items in other pits using these section keywords. The values are Ids that correspond to items in the target pit.

Build and Publish

See BuildFromSource.md for:

• building from source
• building inside the RAIkeep workspace against local projects
• packing and publishing the NuGet tool
• publishing self-contained binaries for macOS, Ubuntu, and Windows

License

This project is licensed under the Apache 2.0 license. See LICENSE.