Skip to content

ptkl thunder

Query and mutate Thunder generic entities from the command line.

Overview

Thunder is the platform's generic entity engine (system/thunder) — a schemaless-ish storage layer for entity types that don't warrant a dedicated Component, with realtime configuration built in. ptkl thunder exposes both the typed convenience operations (find, upsert, …) and the two low-level read/write primitives they're built on, mapping onto the SDK Thunder client (@ptkl/sdk/beta).

Every command targets a single entity type (-t, --type), the Thunder equivalent of a collection/table name.

Subcommands

Subcommand Description
find Find entities matching filters
find-one Find a single entity matching filters
paginate Paginate entities matching filters
read Low-level read: send a raw Thunder read flag (Find | FindOne | Paginate)
write Low-level write: send a raw Thunder write flag (Upsert | InsertOne | UpdateOne | Delete | Operation)
upsert Upsert an entity: update if it matches filters, otherwise insert
insert-one Insert a single entity
update-one Update a single entity matching filters
delete Delete entities matching filters

Shared read options

find, find-one, paginate, and read all accept:

Option Description
-t, --type <type> Thunder entity type name (required)
--filters <json> Filters object as a JSON string (default: {})
--only <fields> Comma-separated list of fields to project
--cache-ttl <seconds> Cache TTL in seconds

Shared payload options

write, upsert, insert-one, and update-one accept the entity payload either inline or from a file:

Option Description
-d, --data <json> Data payload as a JSON string
-i, --file <file> Path to a JSON file containing the data payload (takes precedence over --data)

ptkl thunder find

Find all entities of a type matching filters.

ptkl thunder find -t <type> [--filters <json>] [--only <fields>] [--cache-ttl <seconds>]

Example

ptkl thunder find --type invoice --filters '{"status":"paid"}' --only "id,total,customer"

ptkl thunder find-one

Find a single entity matching filters.

ptkl thunder find-one -t <type> [--filters <json>]

Example

ptkl thunder find-one --type invoice --filters '{"invoiceNumber":"INV-1001"}'

ptkl thunder paginate

Paginate entities matching filters.

ptkl thunder paginate -t <type> [--filters <json>]

Example

ptkl thunder paginate --type invoice --filters '{"status":"paid"}'

ptkl thunder read

Low-level read: send a raw Thunder read flag directly. Use find/find-one/paginate for the common cases — read is for exercising the flag explicitly (e.g. debugging).

ptkl thunder read -t <type> --flag <flag> [--filters <json>]

Options

Option Description
--flag <flag> Thunder read flag: Find | FindOne | Paginate (required)

Example

ptkl thunder read --type invoice --flag Find --filters '{"status":"paid"}'

ptkl thunder write

Low-level write: send a raw Thunder write flag directly. Use upsert/insert-one/update-one/ delete for the common cases.

ptkl thunder write -t <type> --flag <flag> [--filters <json>] [-d <json> | -i <file>]

Options

Option Description
--flag <flag> Thunder write flag: Upsert | InsertOne | UpdateOne | Delete | Operation (required)

Example

ptkl thunder write --type invoice --flag InsertOne --data '{"invoiceNumber":"INV-1002","status":"draft"}'

ptkl thunder upsert

Upsert an entity: update it if it matches --filters, otherwise insert it.

ptkl thunder upsert -t <type> [--filters <json>] [-d <json> | -i <file>]

Example

ptkl thunder upsert --type invoice --filters '{"invoiceNumber":"INV-1002"}' --data '{"status":"paid"}'

ptkl thunder insert-one

Insert a single entity.

ptkl thunder insert-one -t <type> [-d <json> | -i <file>]

Example

ptkl thunder insert-one --type invoice --file ./invoice.json

ptkl thunder update-one

Update a single entity matching filters.

ptkl thunder update-one -t <type> [--filters <json>] [-d <json> | -i <file>]

Example

ptkl thunder update-one --type invoice --filters '{"invoiceNumber":"INV-1002"}' --data '{"status":"void"}'

ptkl thunder delete

Delete entities matching filters.

ptkl thunder delete -t <type> [--filters <json>]

Example

ptkl thunder delete --type invoice --filters '{"status":"draft","createdBefore":"2025-01-01"}'

See Also