Skip to main content
Repost has two query surfaces. Using one’s syntax against the other is the most common agent mistake.
CommandsReads fromQuery style
events search, forwards searchthe indexed store (searchable history)a full field + boolean grammar
expect, tailthe live observe stream (events as they arrive)a small fixed-field filter
repost docs search prints a short cheatsheet; this page is the full reference.

​
Search indexed history

The text after events search / forwards search is a query over indexed fields. Scope with the --bucket / --forwarder flags — don’t put identifiers in the query (see Scope is enforced).
FieldMatches
methodHTTP method — method:POST
pathRequest path. path: is rewritten to the indexed path_original — path:/stripe/webhook
response_statusNumeric HTTP response code — response_status:500
received_atIngest time (also the sort and --since/--until window field)
bucket_id, event_idStable identifiers (prefer --bucket for scoping)
request.*, response.*Any JSON field in the captured body — request.type:charge.refunded
A bare word with no field: prefix searches the default fields only — path_original, request.body, response.body — not every field.
Don’t use status: in a query. The query layer rewrites it to a nested response.status field that won’t match the indexed response code. Use response_status: for the HTTP code on events search, and --failed to filter failed deliveries on forwards search.

​
Operators

AND, OR, NOT, parentheses, and * / ? wildcards are supported: 
repost events search 'method:POST AND path:/stripe/* AND NOT response_status:200' \
  --bucket stripe-prod --since 30m --json
Wildcards run against tokenized terms for text fields like path_original, so path:/stripe/* matches on path tokens, not the raw literal string.

​
Scope is enforced

The query is wrapped in mandatory organization and resource filters server-side:
  • org_id: in a query is rejected with validation_failed.
  • bucket_id: for a bucket you don’t own is rejected.
  • forwarder_id: is stripped — use the --forwarder flag instead.
Use flags for the common cases rather than query fields:
FlagFilters by
--forwarder / -fForwarder ID, or name (name also requires --bucket)
--bucket / -bBucket slug or ID
--eventA single event_id
--failedFailed deliveries — the reliable failure filter
--since / --untilTime window (RFC3339 or a duration like 1h)
--failed is the correct way to find failures. A free-text status:FAILED is rewritten and will not match the delivery status field. Default bare-word search covers path_original, target_url, request.body, response.body, and error_message.

​
Filter the live stream

expect and tail watch events as they arrive, before they’re indexed. They take a small, exact-match filter — not the search grammar above.
FlagMatches
--bucket / -bBucket slug or ID (required)
--pathPath, shell-glob style (--path '/stripe/*')
--methodHTTP method (case-insensitive)
--filterA field:value term over method, path, content_type, event_id, bucket_id
Wildcards in --path use shell-glob matching (*, ?, […]) against the literal path — different from the tokenized wildcards of indexed search. Usage is covered in Wait for events.

​
Page with cursors

events search, forwards search, and the list commands paginate with --cursor. Read the cursor off each response and pass it back to get the next page.
  • Forward-only. Each response carries next_cursor; there is no backward cursor. Stop when has_more is false.
  • Bound to the query and window. The cursor encodes a hash of the exact query plus --since/--until. Change the query, bucket, forwarder, or window and the old cursor is rejected with validation_failed — “stale or invalid cursor; re-run the search.”
  • Replayable, not single-use. A cursor has no expiry or one-time semantics — re-sending it returns the same page. Treat it as “page N of this exact query,” not a token you can only spend once.
page=$(repost events search 'method:POST' --bucket stripe-prod --since 1h --limit 100 --json)
while :; do
  echo "$page" | jq -c '.data.items[]'
  [ "$(echo "$page" | jq -r '.data.has_more')" = "true" ] || break
  cursor=$(echo "$page" | jq -r '.data.next_cursor')
  page=$(repost events search 'method:POST' --bucket stripe-prod --since 1h --limit 100 --cursor "$cursor" --json)
done

​
Continue

Diagnose a webhook

Put bounded search and the delivery chain to work on a real failure.

Wait for events

expect and tail against the live stream.

Discovery

Pull the manifest and per-command schemas from the binary.