PitSeeder 3.7.6

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 -n -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 (just add -n to suppress the banner):

pits -n -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 -n -r /path/to/pitroot/ --wwwa --json | jq '.Place[] | select((.Id | startswith("SD")) or (.Name | contains("Zoo"))) | {Id, Name}'

{
  "Id": "SanDiegoZoo",
  "Name": "San Diego Zoo"
}
{
  "Id": "SDZSafariPark",
  "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

• Current release notes: RELEASE_NOTES_3.7.6.md

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.