tb

parix tb runs TigerBeetle operations against a Parix database.

parix tb --help

Each command sends a request to:

POST /api/v1/databases/{databaseId}/tb/{operation}

Read operations require db:read. Create operations require db:write.

Commands

Shared options

Most parix tb subcommands accept:

Payload resolution order:

1. --file
2. --payload
3. command flags

When using command flags, required values are validated by the CLI. When using --payload or --file, send the exact JSON payload expected by the Parix TigerBeetle API.

create-accounts

parix tb create-accounts [options] <database-id>

Options:

Examples:

parix tb create-accounts db_123 --id 1000 --ledger 1 --code 1
parix tb create-accounts db_123 --id 1001 --ledger 1 --code 1 \
  --user-data-128 410001 --user-data-64 202608 --user-data-32 1
parix tb create-accounts db_123 --payload '[{"id":"1000","ledger":"1","code":"1","flags":"0"}]'

create-transfers

parix tb create-transfers [options] <database-id>

Options:

Examples:

parix tb create-transfers db_123 --id 2000 --from 1000 --to 1001 --amount 1 --ledger 1 --code 1
parix tb create-transfers db_123 --id 2001 --from 1000 --to 1001 --amount 1 --ledger 1 --code 1 \
  --user-data-128 410001 --user-data-64 202608 --user-data-32 1
parix tb create-transfers db_123 --file ./transfer.json

TigerBeetle interprets timeout in seconds, not milliseconds. It applies to pending transfers; use 0 when the transfer is not pending.

The three user-data flags map to TigerBeetle's user_data_128, user_data_64, and user_data_32 fields. Treat the values as opaque decimal strings, and use --file or --payload when submitting a multi-item, linked, or audited batch.

Pass an explicit, stable --id for a business event that may be retried. If the first outcome is ambiguous, reuse that ID rather than allowing a later invocation to generate a new one.

lookup commands

parix tb lookup-accounts [options] <database-id>
parix tb lookup-transfers [options] <database-id>

Options:

Examples:

parix tb lookup-accounts db_123 --id 1000 --id 1001
parix tb lookup-transfers db_123 --ids 2000,2001

At least one --id or --ids value is required unless you use --payload or --file.

account filter commands

parix tb get-account-transfers [options] <database-id>
parix tb get-account-balances [options] <database-id>

Options:

Examples:

parix tb get-account-transfers db_123 --account-id 1000 --limit 10 --flag debits
parix tb get-account-balances db_123 --account-id 1000 --limit 10 --flag credits

query commands

parix tb query-accounts [options] <database-id>
parix tb query-transfers [options] <database-id>

Options:

Examples:

parix tb query-accounts db_123 --limit 10
parix tb query-transfers db_123 --ledger 1 --limit 10 --flag 1 --json

Flags

TigerBeetle flag meanings and bit values are specific to the payload type. A flag that is valid for an account, transfer, or account filter is not automatically valid for a query filter.

--flag accepts a non-negative integer bitfield or a name from the CLI's shared name table. Repeat it to combine values with bitwise OR. Use these flag domains:

For query commands, use numeric --flag 1 for reverse order:

parix tb query-transfers db_123 --ledger 1 --limit 10 --flag 1

Do not use debits or credits with query-accounts or query-transfers; those flags apply only to account filter operations. Do not use the named reversed value for queries, because the shared name table encodes the account-filter value 4 rather than the query-filter value 1.

The same shared table maps named imported to the account value 16. For an imported transfer, use the numeric transfer value 256 or provide a reviewed JSON file instead of --flag imported.

The CLI's shared name table contains:

linked
debits_must_not_exceed_credits
credits_must_not_exceed_debits
history
imported
closed
pending
post_pending_transfer
void_pending_transfer
balancing_debit
balancing_credit
closing_debit
closing_credit
debits
credits
reversed

For an account history filter, repeat names or use the exact numeric bitfield:

parix tb get-account-transfers db_123 --account-id 1000 --flag debits --flag credits
parix tb get-account-transfers db_123 --account-id 1000 --flag 3

Numeric and file safety

Flag-driven values remain decimal text in the generated JSON. For IDs, amounts, user-data fields, and timestamps that can exceed JavaScript's safe integer range, keep values as decimal strings.

Prefer --file for a complex or audited payload. Quote wide integer values in the JSON file so parsing does not round them before they reach Parix:

[
  {
    "id": "1701411834604692317316873037158841057",
    "debit_account_id": "1000",
    "credit_account_id": "1001",
    "amount": "1000000",
    "ledger": "1",
    "code": "1",
    "flags": "0",
    "timeout": "0"
  }
]

parix tb create-transfers db_123 --file ./transfer.json

--file and --payload bypass the CLI's flag-driven required-value checks. The API still validates the exact operation schema, so use an array for create and lookup operations and an object for account-filter and query operations.

Output

Without --json, the CLI prints execution metadata, the TigerBeetle documentation URL returned by the API, and the response payload. With --json, it shows the complete API response in terminal JSON form.

That JSON is rendered through the CLI's terminal logger and each output line is decorated. It is useful for complete inspection, but it is not clean machine-readable stdout and should not be piped directly to jq.

HTTP 4xx and 5xx responses (including TigerBeetle write conflicts with HTTP 409 and tbResults) set a non-zero process exit code. The error message includes the problem detail when present and appends tbResults for create conflicts. Inspect those codes against TigerBeetle create-result enums; do not treat exit status alone as a full reconciliation signal.

Wide integer fields in successful responses are decimal strings (id, amounts, balances, user_data_*, timestamps).