@basis-theory-labs/cli 4.3.0 → 4.4.0

package/README.md

@@ -19,7 +19,7 @@ $ npm install -g @basis-theory-labs/cli
 $ bt COMMAND
 running command...
 $ bt (--version)
-@basis-theory-labs/cli/4.3.0 linux-x64 node-v22.23.3
+@basis-theory-labs/cli/4.4.0 linux-x64 node-v22.23.3
 $ bt --help [COMMAND]
 USAGE
   $ bt COMMAND
@@ -66,7 +66,7 @@ EXAMPLES
   $ bt applications
 ```
 
-_See code: [dist/commands/applications/index.ts](https://github.com/Basis-Theory-Labs/basistheory-cli/blob/v4.3.0/dist/commands/applications/index.ts)_
+_See code: [dist/commands/applications/index.ts](https://github.com/Basis-Theory-Labs/basistheory-cli/blob/v4.4.0/dist/commands/applications/index.ts)_
 
 ## `bt applications create`
 
@@ -155,7 +155,7 @@ EXAMPLES
   $ bt proxies
 ```
 
-_See code: [dist/commands/proxies/index.ts](https://github.com/Basis-Theory-Labs/basistheory-cli/blob/v4.3.0/dist/commands/proxies/index.ts)_
+_See code: [dist/commands/proxies/index.ts](https://github.com/Basis-Theory-Labs/basistheory-cli/blob/v4.4.0/dist/commands/proxies/index.ts)_
 
 ## `bt proxies create`
 
@@ -292,7 +292,8 @@ Read a fixed window of Proxy runtime logs through Events and exit. Requires `eve
 
 ```
 USAGE
-  $ bt proxies logs read ID -x <value> [--since <value>] [--until <value>] [--format pretty|json|json-pretty]
+  $ bt proxies logs read ID -x <value> [--trace-id <value>] [--transform-type request_transform|response_transform]
+    [--since <value>] [--until <value>] [--format pretty|json|json-pretty]
 
 ARGUMENTS
   ID  Proxy id
@@ -304,6 +305,9 @@ FLAGS
                                 <options: pretty|json|json-pretty>
   --since=<value>               window start: positive duration (30s, 5m, 2h, 1d, 1w) or ISO timestamp with timezone;
                                 defaults to five minutes before the end
+  --trace-id=<value>            exact, case-sensitive stored BT trace ID; combines with transform direction using AND
+  --transform-type=<option>     exact transform direction; includes both directions when omitted
+                                <options: request_transform|response_transform>
   --until=<value>               window end (exclusive): positive duration or ISO timestamp with timezone; defaults to
                                 command start
 
@@ -311,17 +315,28 @@ DESCRIPTION
   Read a fixed window of Proxy runtime logs through Events and exit. Requires `event:read` and runtime logging already
   enabled.
 
-  Defaults to the five minutes preceding --until, or command start when --until is omitted. Explicit relative values use
-  command-start time. Both request and response transforms are included and distinguished. Windows include their start
-  and exclude their end, filtering event batch timestamps rather than individual record occurrence times. Each matching
-  batch is expanded in record sequence; flattened output has no global chronological ordering. History is tenant-limited
-  (24 hours by default, at most 30 days); the API clamps unavailable history. Indexing is asynchronous and pagination is
-  not a snapshot, so empty or exhausted results do not prove complete coverage. Large windows may hit bounded work
-  limits and fail with partial output. Application logs come from the injected `logger`, not arbitrary stdout or
-  `console.log`; collection requires resource opt-in and the platform runtime-log gate. Does not enable logging or open
-  a tunnel.
+  Optional --trace-id matches the effective stored BT trace ID exactly and case-sensitively. A submitted header may be
+  sanitized by Vault; the CLI does not normalize or trim it. A reused trace ID can match multiple invocations.
+  --transform-type filters request or response transforms, alone or combined with trace ID using AND; omitting it
+  includes both directions.
+
+  Defaults to the five minutes preceding --until, or command start when --until is omitted, regardless of filters.
+  Supply --since, for example --since 30d, to request a larger window. Explicit relative values use command-start time.
+  Windows include their start and exclude their end, filtering event batch timestamps rather than individual record
+  occurrence times. Each matching batch is expanded in record sequence; flattened output has no global chronological
+  ordering. History is limited by server retention and tenant entitlements; the API clamps unavailable history. Indexing
+  is asynchronous and pagination is not a snapshot, so empty or exhausted results do not prove complete coverage. Large
+  windows may hit bounded work limits and fail with partial output. Application logs come from the injected `logger`,
+  not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform runtime-log gate. Does not
+  enable logging or open a tunnel.
 
 EXAMPLES
+  $ bt proxies logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42 --since 30d
+
+  $ bt proxies logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --transform-type request_transform
+
+  $ bt proxies logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42 --transform-type response_transform --since 30m
+
   $ bt proxies logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --since 1h --until 30m
 
   $ bt proxies logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --since 2026-10-01T10:00:00Z --until 2026-10-01T10:15:00Z --format json
@@ -333,7 +348,8 @@ Tail Proxy runtime logs through Events. Requires `event:read` and runtime loggin
 
 ```
 USAGE
-  $ bt proxies logs tail ID -x <value> [--since <value>] [--format pretty|json|json-pretty]
+  $ bt proxies logs tail ID -x <value> [--trace-id <value>] [--transform-type request_transform|response_transform]
+    [--since <value>] [--format pretty|json|json-pretty]
 
 ARGUMENTS
   ID  Proxy id
@@ -345,24 +361,37 @@ FLAGS
                                 <options: pretty|json|json-pretty>
   --since=<value>               include initial history from a positive duration (30s, 5m, 2h, 1d, 1w) or ISO timestamp
                                 with timezone; omitted means watch from command start
+  --trace-id=<value>            exact, case-sensitive stored BT trace ID; combines with transform direction using AND
+  --transform-type=<option>     exact transform direction; includes both directions when omitted
+                                <options: request_transform|response_transform>
 
 DESCRIPTION
   Tail Proxy runtime logs through Events. Requires `event:read` and runtime logging already enabled.
 
-  Starts watching from command time. Supply --since to retrieve initial history before following new logs. Polls every
-  five seconds with a rolling five-minute overlap that never reaches before the requested start. Both request and
-  response transforms are included and distinguished. Time windows filter event batches, not individual record
-  occurrence times; a newly arriving batch can contain records that occurred before command start. History is
-  tenant-limited (24 hours by default, at most 30 days); the API clamps unavailable history. Large initial windows may
-  hit bounded work limits and fail with partial output. Visibility is delayed and best-effort; output has no durable
-  resume or global chronological ordering. Application logs come from the injected `logger`, not arbitrary stdout or
-  `console.log`; collection requires resource opt-in and the platform runtime-log gate. Silence does not distinguish an
-  idle resource, a wrong ID, disabled collection, or delayed indexing. Runs until interrupted, output closes, or an
-  error occurs.
+  Optional --trace-id matches the effective stored BT trace ID exactly and case-sensitively. A submitted header may be
+  sanitized by Vault; the CLI does not normalize or trim it. A reused trace ID can match multiple invocations.
+  --transform-type filters request or response transforms, alone or combined with trace ID using AND; omitting it
+  includes both directions. Filters apply to initial history and every live poll.
+
+  Starts watching from command time, regardless of filters. Supply --since to retrieve initial history before following
+  new logs. Polls every five seconds with a rolling five-minute overlap that never reaches before the requested start.
+  Time windows filter event batches, not individual record occurrence times; a newly arriving batch can contain records
+  that occurred before command start. History is limited by server retention and tenant entitlements; the API clamps
+  unavailable history. Large initial windows may hit bounded work limits and fail with partial output. Visibility is
+  delayed and best-effort; output has no durable resume or global chronological ordering. Application logs come from the
+  injected `logger`, not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform
+  runtime-log gate. Silence does not distinguish an idle resource, a wrong ID or filter, disabled collection, or delayed
+  indexing. Runs until interrupted, output closes, or an error occurs.
 
 EXAMPLES
   $ bt proxies logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca
 
+  $ bt proxies logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42
+
+  $ bt proxies logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --transform-type request_transform
+
+  $ bt proxies logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42 --transform-type response_transform --since 30m --format json
+
   $ bt proxies logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --since 30m --format json
 ```
 
@@ -468,7 +497,7 @@ EXAMPLES
   $ bt reactors
 ```
 
-_See code: [dist/commands/reactors/index.ts](https://github.com/Basis-Theory-Labs/basistheory-cli/blob/v4.3.0/dist/commands/reactors/index.ts)_
+_See code: [dist/commands/reactors/index.ts](https://github.com/Basis-Theory-Labs/basistheory-cli/blob/v4.4.0/dist/commands/reactors/index.ts)_
 
 ## `bt reactors create`
 
@@ -574,7 +603,8 @@ Read a fixed window of Reactor runtime logs through Events and exit. Requires `e
 
 ```
 USAGE
-  $ bt reactors logs read ID -x <value> [--since <value>] [--until <value>] [--format pretty|json|json-pretty]
+  $ bt reactors logs read ID -x <value> [--trace-id <value>] [--since <value>] [--until <value>] [--format
+    pretty|json|json-pretty]
 
 ARGUMENTS
   ID  Reactor id
@@ -586,6 +616,7 @@ FLAGS
                                 <options: pretty|json|json-pretty>
   --since=<value>               window start: positive duration (30s, 5m, 2h, 1d, 1w) or ISO timestamp with timezone;
                                 defaults to five minutes before the end
+  --trace-id=<value>            exact, case-sensitive stored BT trace ID
   --until=<value>               window end (exclusive): positive duration or ISO timestamp with timezone; defaults to
                                 command start
 
@@ -593,16 +624,22 @@ DESCRIPTION
   Read a fixed window of Reactor runtime logs through Events and exit. Requires `event:read` and runtime logging already
   enabled.
 
-  Defaults to the five minutes preceding --until, or command start when --until is omitted. Explicit relative values use
-  command-start time. Windows include their start and exclude their end, filtering event batch timestamps rather than
-  individual record occurrence times. Each matching batch is expanded in record sequence; flattened output has no global
-  chronological ordering. History is tenant-limited (24 hours by default, at most 30 days); the API clamps unavailable
-  history. Indexing is asynchronous and pagination is not a snapshot, so empty or exhausted results do not prove
-  complete coverage. Large windows may hit bounded work limits and fail with partial output. Application logs come from
-  the injected `logger`, not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform
-  runtime-log gate. Does not enable logging or open a tunnel.
+  Optional --trace-id matches the effective stored BT trace ID exactly and case-sensitively. A submitted header may be
+  sanitized by Vault; the CLI does not normalize or trim it. A reused trace ID can match multiple invocations.
+
+  Defaults to the five minutes preceding --until, or command start when --until is omitted, regardless of filters.
+  Supply --since, for example --since 30d, to request a larger window. Explicit relative values use command-start time.
+  Windows include their start and exclude their end, filtering event batch timestamps rather than individual record
+  occurrence times. Each matching batch is expanded in record sequence; flattened output has no global chronological
+  ordering. History is limited by server retention and tenant entitlements; the API clamps unavailable history. Indexing
+  is asynchronous and pagination is not a snapshot, so empty or exhausted results do not prove complete coverage. Large
+  windows may hit bounded work limits and fail with partial output. Application logs come from the injected `logger`,
+  not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform runtime-log gate. Does not
+  enable logging or open a tunnel.
 
 EXAMPLES
+  $ bt reactors logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42 --since 30d
+
   $ bt reactors logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --since 1h --until 30m
 
   $ bt reactors logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --since 2026-10-01T10:00:00Z --until 2026-10-01T10:15:00Z --format json
@@ -614,7 +651,7 @@ Tail Reactor runtime logs through Events. Requires `event:read` and runtime logg
 
 ```
 USAGE
-  $ bt reactors logs tail ID -x <value> [--since <value>] [--format pretty|json|json-pretty]
+  $ bt reactors logs tail ID -x <value> [--trace-id <value>] [--since <value>] [--format pretty|json|json-pretty]
 
 ARGUMENTS
   ID  Reactor id
@@ -626,23 +663,31 @@ FLAGS
                                 <options: pretty|json|json-pretty>
   --since=<value>               include initial history from a positive duration (30s, 5m, 2h, 1d, 1w) or ISO timestamp
                                 with timezone; omitted means watch from command start
+  --trace-id=<value>            exact, case-sensitive stored BT trace ID
 
 DESCRIPTION
   Tail Reactor runtime logs through Events. Requires `event:read` and runtime logging already enabled.
 
-  Starts watching from command time. Supply --since to retrieve initial history before following new logs. Polls every
-  five seconds with a rolling five-minute overlap that never reaches before the requested start. Time windows filter
-  event batches, not individual record occurrence times; a newly arriving batch can contain records that occurred before
-  command start. History is tenant-limited (24 hours by default, at most 30 days); the API clamps unavailable history.
-  Large initial windows may hit bounded work limits and fail with partial output. Visibility is delayed and best-effort;
-  output has no durable resume or global chronological ordering. Application logs come from the injected `logger`, not
-  arbitrary stdout or `console.log`; collection requires resource opt-in and the platform runtime-log gate. Silence does
-  not distinguish an idle resource, a wrong ID, disabled collection, or delayed indexing. Runs until interrupted, output
-  closes, or an error occurs.
+  Optional --trace-id matches the effective stored BT trace ID exactly and case-sensitively. A submitted header may be
+  sanitized by Vault; the CLI does not normalize or trim it. A reused trace ID can match multiple invocations.
+
+  Starts watching from command time, regardless of filters. Supply --since to retrieve initial history before following
+  new logs. Polls every five seconds with a rolling five-minute overlap that never reaches before the requested start.
+  Time windows filter event batches, not individual record occurrence times; a newly arriving batch can contain records
+  that occurred before command start. History is limited by server retention and tenant entitlements; the API clamps
+  unavailable history. Large initial windows may hit bounded work limits and fail with partial output. Visibility is
+  delayed and best-effort; output has no durable resume or global chronological ordering. Application logs come from the
+  injected `logger`, not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform
+  runtime-log gate. Silence does not distinguish an idle resource, a wrong ID or filter, disabled collection, or delayed
+  indexing. Runs until interrupted, output closes, or an error occurs.
 
 EXAMPLES
   $ bt reactors logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca
 
+  $ bt reactors logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42
+
+  $ bt reactors logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42 --since 30m --format json
+
   $ bt reactors logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --since 30m --format json
 ```
 

package/dist/commands/proxies/logs/read.d.ts

@@ -6,6 +6,8 @@ export default class Read extends BaseCommand {
         id: import("@oclif/core/lib/interfaces/parser").Arg<string, Record<string, unknown>>;
     };
     static flags: {
+        'trace-id': import("@oclif/core/lib/interfaces/parser").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        'transform-type': import("@oclif/core/lib/interfaces/parser").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
         since: import("@oclif/core/lib/interfaces/parser").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
         until: import("@oclif/core/lib/interfaces/parser").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
         format: import("@oclif/core/lib/interfaces/parser").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;

package/dist/commands/proxies/logs/read.js

@@ -7,15 +7,20 @@ const time_1 = require("../../../logs/time");
 class Read extends base_1.BaseCommand {
     async run() {
         const now = Date.now();
-        const { flags: { 'management-key': apiKey, 'api-base-url': apiBaseUrl, format, since, until, }, args: { id }, } = await this.parse(Read);
+        const { flags: { 'management-key': apiKey, 'api-base-url': apiBaseUrl, 'trace-id': traceId, 'transform-type': transformType, format, since, until, }, args: { id }, } = await this.parse(Read);
         if (!id.trim()) {
             this.error('Proxy id must not be blank');
         }
+        if (traceId !== undefined && !traceId.trim()) {
+            this.error('--trace-id must not be blank');
+        }
         await (0, runtime_1.readEventLogs)({
             apiKey,
             apiBaseUrl,
             resourceType: 'proxy',
             resourceId: id,
+            traceId,
+            transformType: transformType,
             format: format,
             window: (0, time_1.resolveLogWindow)({
                 since,
@@ -30,8 +35,12 @@ class Read extends base_1.BaseCommand {
 }
 exports.default = Read;
 Read.description = 'Read a fixed window of Proxy runtime logs through Events and exit. Requires `event:read` and runtime logging already enabled.\n\n' +
-    'Defaults to the five minutes preceding --until, or command start when --until is omitted. Explicit relative values use command-start time. Both request and response transforms are included and distinguished. Windows include their start and exclude their end, filtering event batch timestamps rather than individual record occurrence times. Each matching batch is expanded in record sequence; flattened output has no global chronological ordering. History is tenant-limited (24 hours by default, at most 30 days); the API clamps unavailable history. Indexing is asynchronous and pagination is not a snapshot, so empty or exhausted results do not prove complete coverage. Large windows may hit bounded work limits and fail with partial output. Application logs come from the injected `logger`, not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform runtime-log gate. Does not enable logging or open a tunnel.';
+    'Optional --trace-id matches the effective stored BT trace ID exactly and case-sensitively. A submitted header may be sanitized by Vault; the CLI does not normalize or trim it. A reused trace ID can match multiple invocations. --transform-type filters request or response transforms, alone or combined with trace ID using AND; omitting it includes both directions.\n\n' +
+    'Defaults to the five minutes preceding --until, or command start when --until is omitted, regardless of filters. Supply --since, for example --since 30d, to request a larger window. Explicit relative values use command-start time. Windows include their start and exclude their end, filtering event batch timestamps rather than individual record occurrence times. Each matching batch is expanded in record sequence; flattened output has no global chronological ordering. History is limited by server retention and tenant entitlements; the API clamps unavailable history. Indexing is asynchronous and pagination is not a snapshot, so empty or exhausted results do not prove complete coverage. Large windows may hit bounded work limits and fail with partial output. Application logs come from the injected `logger`, not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform runtime-log gate. Does not enable logging or open a tunnel.';
 Read.examples = [
+    '<%= config.bin %> proxies logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42 --since 30d',
+    '<%= config.bin %> proxies logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --transform-type request_transform',
+    '<%= config.bin %> proxies logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42 --transform-type response_transform --since 30m',
     '<%= config.bin %> proxies logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --since 1h --until 30m',
     '<%= config.bin %> proxies logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --since 2026-10-01T10:00:00Z --until 2026-10-01T10:15:00Z --format json',
 ];
@@ -42,6 +51,13 @@ Read.args = {
     }),
 };
 Read.flags = {
+    'trace-id': core_1.Flags.string({
+        description: 'exact, case-sensitive stored BT trace ID; combines with transform direction using AND',
+    }),
+    'transform-type': core_1.Flags.string({
+        description: 'exact transform direction; includes both directions when omitted',
+        options: ['request_transform', 'response_transform'],
+    }),
     since: core_1.Flags.string({
         description: 'window start: positive duration (30s, 5m, 2h, 1d, 1w) or ISO timestamp with timezone; defaults to five minutes before the end',
     }),

package/dist/commands/proxies/logs/tail.d.ts

@@ -6,6 +6,8 @@ export default class Tail extends BaseCommand {
         id: import("@oclif/core/lib/interfaces/parser").Arg<string, Record<string, unknown>>;
     };
     static flags: {
+        'trace-id': import("@oclif/core/lib/interfaces/parser").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
+        'transform-type': import("@oclif/core/lib/interfaces/parser").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
         since: import("@oclif/core/lib/interfaces/parser").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
         format: import("@oclif/core/lib/interfaces/parser").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
     };

package/dist/commands/proxies/logs/tail.js

@@ -7,15 +7,20 @@ const time_1 = require("../../../logs/time");
 class Tail extends base_1.BaseCommand {
     async run() {
         const now = Date.now();
-        const { flags: { 'management-key': apiKey, 'api-base-url': apiBaseUrl, format, since, }, args: { id }, } = await this.parse(Tail);
+        const { flags: { 'management-key': apiKey, 'api-base-url': apiBaseUrl, 'trace-id': traceId, 'transform-type': transformType, format, since, }, args: { id }, } = await this.parse(Tail);
         if (!id.trim()) {
             this.error('Proxy id must not be blank');
         }
+        if (traceId !== undefined && !traceId.trim()) {
+            this.error('--trace-id must not be blank');
+        }
         await (0, runtime_1.followEventLogs)({
             apiKey,
             apiBaseUrl,
             resourceType: 'proxy',
             resourceId: id,
+            traceId,
+            transformType: transformType,
             format: format,
             window: (0, time_1.resolveTailWindow)({ since }, now),
         });
@@ -27,9 +32,13 @@ class Tail extends base_1.BaseCommand {
 }
 exports.default = Tail;
 Tail.description = 'Tail Proxy runtime logs through Events. Requires `event:read` and runtime logging already enabled.\n\n' +
-    'Starts watching from command time. Supply --since to retrieve initial history before following new logs. Polls every five seconds with a rolling five-minute overlap that never reaches before the requested start. Both request and response transforms are included and distinguished. Time windows filter event batches, not individual record occurrence times; a newly arriving batch can contain records that occurred before command start. History is tenant-limited (24 hours by default, at most 30 days); the API clamps unavailable history. Large initial windows may hit bounded work limits and fail with partial output. Visibility is delayed and best-effort; output has no durable resume or global chronological ordering. Application logs come from the injected `logger`, not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform runtime-log gate. Silence does not distinguish an idle resource, a wrong ID, disabled collection, or delayed indexing. Runs until interrupted, output closes, or an error occurs.';
+    'Optional --trace-id matches the effective stored BT trace ID exactly and case-sensitively. A submitted header may be sanitized by Vault; the CLI does not normalize or trim it. A reused trace ID can match multiple invocations. --transform-type filters request or response transforms, alone or combined with trace ID using AND; omitting it includes both directions. Filters apply to initial history and every live poll.\n\n' +
+    'Starts watching from command time, regardless of filters. Supply --since to retrieve initial history before following new logs. Polls every five seconds with a rolling five-minute overlap that never reaches before the requested start. Time windows filter event batches, not individual record occurrence times; a newly arriving batch can contain records that occurred before command start. History is limited by server retention and tenant entitlements; the API clamps unavailable history. Large initial windows may hit bounded work limits and fail with partial output. Visibility is delayed and best-effort; output has no durable resume or global chronological ordering. Application logs come from the injected `logger`, not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform runtime-log gate. Silence does not distinguish an idle resource, a wrong ID or filter, disabled collection, or delayed indexing. Runs until interrupted, output closes, or an error occurs.';
 Tail.examples = [
     '<%= config.bin %> proxies logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca',
+    '<%= config.bin %> proxies logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42',
+    '<%= config.bin %> proxies logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --transform-type request_transform',
+    '<%= config.bin %> proxies logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42 --transform-type response_transform --since 30m --format json',
     '<%= config.bin %> proxies logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --since 30m --format json',
 ];
 Tail.args = {
@@ -39,6 +48,13 @@ Tail.args = {
     }),
 };
 Tail.flags = {
+    'trace-id': core_1.Flags.string({
+        description: 'exact, case-sensitive stored BT trace ID; combines with transform direction using AND',
+    }),
+    'transform-type': core_1.Flags.string({
+        description: 'exact transform direction; includes both directions when omitted',
+        options: ['request_transform', 'response_transform'],
+    }),
     since: core_1.Flags.string({
         description: 'include initial history from a positive duration (30s, 5m, 2h, 1d, 1w) or ISO timestamp with timezone; omitted means watch from command start',
     }),

package/dist/commands/reactors/logs/read.d.ts

@@ -6,6 +6,7 @@ export default class Read extends BaseCommand {
         id: import("@oclif/core/lib/interfaces/parser").Arg<string, Record<string, unknown>>;
     };
     static flags: {
+        'trace-id': import("@oclif/core/lib/interfaces/parser").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
         since: import("@oclif/core/lib/interfaces/parser").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
         until: import("@oclif/core/lib/interfaces/parser").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
         format: import("@oclif/core/lib/interfaces/parser").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;

package/dist/commands/reactors/logs/read.js

@@ -7,15 +7,19 @@ const time_1 = require("../../../logs/time");
 class Read extends base_1.BaseCommand {
     async run() {
         const now = Date.now();
-        const { flags: { 'management-key': apiKey, 'api-base-url': apiBaseUrl, format, since, until, }, args: { id }, } = await this.parse(Read);
+        const { flags: { 'management-key': apiKey, 'api-base-url': apiBaseUrl, 'trace-id': traceId, format, since, until, }, args: { id }, } = await this.parse(Read);
         if (!id.trim()) {
             this.error('Reactor id must not be blank');
         }
+        if (traceId !== undefined && !traceId.trim()) {
+            this.error('--trace-id must not be blank');
+        }
         await (0, runtime_1.readEventLogs)({
             apiKey,
             apiBaseUrl,
             resourceType: 'reactor',
             resourceId: id,
+            traceId,
             format: format,
             window: (0, time_1.resolveLogWindow)({
                 since,
@@ -30,8 +34,10 @@ class Read extends base_1.BaseCommand {
 }
 exports.default = Read;
 Read.description = 'Read a fixed window of Reactor runtime logs through Events and exit. Requires `event:read` and runtime logging already enabled.\n\n' +
-    'Defaults to the five minutes preceding --until, or command start when --until is omitted. Explicit relative values use command-start time. Windows include their start and exclude their end, filtering event batch timestamps rather than individual record occurrence times. Each matching batch is expanded in record sequence; flattened output has no global chronological ordering. History is tenant-limited (24 hours by default, at most 30 days); the API clamps unavailable history. Indexing is asynchronous and pagination is not a snapshot, so empty or exhausted results do not prove complete coverage. Large windows may hit bounded work limits and fail with partial output. Application logs come from the injected `logger`, not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform runtime-log gate. Does not enable logging or open a tunnel.';
+    'Optional --trace-id matches the effective stored BT trace ID exactly and case-sensitively. A submitted header may be sanitized by Vault; the CLI does not normalize or trim it. A reused trace ID can match multiple invocations.\n\n' +
+    'Defaults to the five minutes preceding --until, or command start when --until is omitted, regardless of filters. Supply --since, for example --since 30d, to request a larger window. Explicit relative values use command-start time. Windows include their start and exclude their end, filtering event batch timestamps rather than individual record occurrence times. Each matching batch is expanded in record sequence; flattened output has no global chronological ordering. History is limited by server retention and tenant entitlements; the API clamps unavailable history. Indexing is asynchronous and pagination is not a snapshot, so empty or exhausted results do not prove complete coverage. Large windows may hit bounded work limits and fail with partial output. Application logs come from the injected `logger`, not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform runtime-log gate. Does not enable logging or open a tunnel.';
 Read.examples = [
+    '<%= config.bin %> reactors logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42 --since 30d',
     '<%= config.bin %> reactors logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --since 1h --until 30m',
     '<%= config.bin %> reactors logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --since 2026-10-01T10:00:00Z --until 2026-10-01T10:15:00Z --format json',
 ];
@@ -42,6 +48,9 @@ Read.args = {
     }),
 };
 Read.flags = {
+    'trace-id': core_1.Flags.string({
+        description: 'exact, case-sensitive stored BT trace ID',
+    }),
     since: core_1.Flags.string({
         description: 'window start: positive duration (30s, 5m, 2h, 1d, 1w) or ISO timestamp with timezone; defaults to five minutes before the end',
     }),

package/dist/commands/reactors/logs/tail.d.ts

@@ -6,6 +6,7 @@ export default class Tail extends BaseCommand {
         id: import("@oclif/core/lib/interfaces/parser").Arg<string, Record<string, unknown>>;
     };
     static flags: {
+        'trace-id': import("@oclif/core/lib/interfaces/parser").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
         since: import("@oclif/core/lib/interfaces/parser").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
         format: import("@oclif/core/lib/interfaces/parser").OptionFlag<string, import("@oclif/core/lib/interfaces/parser").CustomOptions>;
     };

package/dist/commands/reactors/logs/tail.js

@@ -7,15 +7,19 @@ const time_1 = require("../../../logs/time");
 class Tail extends base_1.BaseCommand {
     async run() {
         const now = Date.now();
-        const { flags: { 'management-key': apiKey, 'api-base-url': apiBaseUrl, format, since, }, args: { id }, } = await this.parse(Tail);
+        const { flags: { 'management-key': apiKey, 'api-base-url': apiBaseUrl, 'trace-id': traceId, format, since, }, args: { id }, } = await this.parse(Tail);
         if (!id.trim()) {
             this.error('Reactor id must not be blank');
         }
+        if (traceId !== undefined && !traceId.trim()) {
+            this.error('--trace-id must not be blank');
+        }
         await (0, runtime_1.followEventLogs)({
             apiKey,
             apiBaseUrl,
             resourceType: 'reactor',
             resourceId: id,
+            traceId,
             format: format,
             window: (0, time_1.resolveTailWindow)({ since }, now),
         });
@@ -27,9 +31,12 @@ class Tail extends base_1.BaseCommand {
 }
 exports.default = Tail;
 Tail.description = 'Tail Reactor runtime logs through Events. Requires `event:read` and runtime logging already enabled.\n\n' +
-    'Starts watching from command time. Supply --since to retrieve initial history before following new logs. Polls every five seconds with a rolling five-minute overlap that never reaches before the requested start. Time windows filter event batches, not individual record occurrence times; a newly arriving batch can contain records that occurred before command start. History is tenant-limited (24 hours by default, at most 30 days); the API clamps unavailable history. Large initial windows may hit bounded work limits and fail with partial output. Visibility is delayed and best-effort; output has no durable resume or global chronological ordering. Application logs come from the injected `logger`, not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform runtime-log gate. Silence does not distinguish an idle resource, a wrong ID, disabled collection, or delayed indexing. Runs until interrupted, output closes, or an error occurs.';
+    'Optional --trace-id matches the effective stored BT trace ID exactly and case-sensitively. A submitted header may be sanitized by Vault; the CLI does not normalize or trim it. A reused trace ID can match multiple invocations.\n\n' +
+    'Starts watching from command time, regardless of filters. Supply --since to retrieve initial history before following new logs. Polls every five seconds with a rolling five-minute overlap that never reaches before the requested start. Time windows filter event batches, not individual record occurrence times; a newly arriving batch can contain records that occurred before command start. History is limited by server retention and tenant entitlements; the API clamps unavailable history. Large initial windows may hit bounded work limits and fail with partial output. Visibility is delayed and best-effort; output has no durable resume or global chronological ordering. Application logs come from the injected `logger`, not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform runtime-log gate. Silence does not distinguish an idle resource, a wrong ID or filter, disabled collection, or delayed indexing. Runs until interrupted, output closes, or an error occurs.';
 Tail.examples = [
     '<%= config.bin %> reactors logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca',
+    '<%= config.bin %> reactors logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42',
+    '<%= config.bin %> reactors logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42 --since 30m --format json',
     '<%= config.bin %> reactors logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --since 30m --format json',
 ];
 Tail.args = {
@@ -39,6 +46,9 @@ Tail.args = {
     }),
 };
 Tail.flags = {
+    'trace-id': core_1.Flags.string({
+        description: 'exact, case-sensitive stored BT trace ID',
+    }),
     since: core_1.Flags.string({
         description: 'include initial history from a positive duration (30s, 5m, 2h, 1d, 1w) or ISO timestamp with timezone; omitted means watch from command start',
     }),

package/dist/logs/events.d.ts

@@ -25,6 +25,10 @@ interface EventLogRecord {
     outcome?: string;
     duration_ms?: number;
 }
+interface EventLogFilters {
+    traceId?: string;
+    transformType?: EventLogRecord['transform_type'];
+}
 interface EventLogPage {
     batches: EventLogRecord[][];
     next: string | null;
@@ -39,7 +43,7 @@ declare class EventsReadError extends Error {
 }
 /** Resolve and validate the API origin before any credential is sent. */
 declare const resolveEventsOrigin: (apiBaseUrl?: string) => string;
-interface ReadEventPageOptions {
+interface ReadEventPageOptions extends EventLogFilters {
     origin: string;
     apiKey: string;
     resourceType: ResourceType;
@@ -52,5 +56,5 @@ interface ReadEventPageOptions {
 }
 /** Read and validate one Events page. Continuations contain only the opaque cursor. */
 declare const readEventPage: (options: ReadEventPageOptions) => Promise<EventLogPage>;
-export type { EventLogPage, EventLogRecord, ReadEventPageOptions, ResourceType, };
+export type { EventLogFilters, EventLogPage, EventLogRecord, ReadEventPageOptions, ResourceType, };
 export { EventsReadError, readEventPage, resolveEventsOrigin };

package/dist/logs/events.js

@@ -243,6 +243,11 @@ const projectBatch = (input, options) => {
     else if (options.resourceType === 'proxy') {
         return invalidPage();
     }
+    if ((options.traceId !== undefined && input.traceId !== options.traceId) ||
+        (options.transformType !== undefined &&
+            transformType !== options.transformType)) {
+        return invalidPage();
+    }
     if (!nonnegativeSafeInteger(data.sequence_start) ||
         !nonnegativeSafeInteger(data.sequence_end) ||
         data.sequence_start > data.sequence_end ||
@@ -424,10 +429,15 @@ const readEventPage = async (options) => {
         /[\u0000-\u001F\u007F]/u.test(options.apiKey) ||
         !isNonEmptyString(options.resourceId) ||
         (options.resourceType !== 'reactor' && options.resourceType !== 'proxy') ||
+        (options.traceId !== undefined && !isNonEmptyString(options.traceId)) ||
+        (options.transformType !== undefined &&
+            (options.resourceType !== 'proxy' ||
+                (options.transformType !== 'request_transform' &&
+                    options.transformType !== 'response_transform'))) ||
         !Number.isSafeInteger(options.start) ||
-        !Number.isSafeInteger(options.end) ||
         options.start > options.end ||
         !Number.isFinite(new Date(options.start).getTime()) ||
+        !Number.isSafeInteger(options.end) ||
         !Number.isFinite(new Date(options.end).getTime()) ||
         (options.cursor !== undefined &&
             (typeof options.cursor !== 'string' ||
@@ -513,6 +523,7 @@ const readEventPage = async (options) => {
         const page = await bt.events.list(options.cursor === undefined
             ? {
                 type: options.resourceType === 'reactor' ? 'reactor.log' : 'proxy.log',
+                traceId: options.traceId,
                 startDate: new Date(options.start),
                 endDate: new Date(options.end),
                 size: PAGE_SIZE,
@@ -521,7 +532,12 @@ const readEventPage = async (options) => {
             abortSignal: options.signal,
             maxRetries: 0,
             queryParams: options.cursor === undefined
-                ? { [`data.${options.resourceType}.id`]: options.resourceId }
+                ? {
+                    [`data.${options.resourceType}.id`]: options.resourceId,
+                    ...(options.transformType !== undefined
+                        ? { 'data.transform_type': options.transformType }
+                        : {}),
+                }
                 : undefined,
         });
         payload = page.response;
@@ -556,6 +572,8 @@ const readEventPage = async (options) => {
         resourceId: options.resourceId,
         start: options.start,
         end: options.end,
+        traceId: options.traceId,
+        transformType: options.transformType,
     }));
     if (options.signal.aborted) {
         throw new EventsReadError('Events request was interrupted.', {

package/dist/logs/runtime.d.ts

@@ -1,7 +1,7 @@
-import type { ResourceType } from './events';
+import type { EventLogFilters, ResourceType } from './events';
 import type { RuntimeLogFormat } from './format';
 import type { LogWindow } from './time';
-interface RuntimeLogOptions {
+interface RuntimeLogOptions extends EventLogFilters {
     apiKey: string;
     apiBaseUrl?: string;
     resourceType: ResourceType;
@@ -9,7 +9,7 @@ interface RuntimeLogOptions {
     format: RuntimeLogFormat;
     window?: LogWindow;
 }
-/** Retrieve one fixed window, including every continuation, then finish. */
+/** Retrieve one finite query window, including every continuation, then finish. */
 declare const readEventLogs: (options: RuntimeLogOptions & {
     window: LogWindow;
 }) => Promise<void>;

package/dist/logs/runtime.js

@@ -216,6 +216,8 @@ const streamEventLogs = async (options, mode) => {
                                 apiKey: options.apiKey,
                                 resourceType: options.resourceType,
                                 resourceId: options.resourceId,
+                                traceId: options.traceId,
+                                transformType: options.transformType,
                                 start,
                                 end,
                                 cursor,
@@ -352,7 +354,7 @@ const streamEventLogs = async (options, mode) => {
         }
     }
 };
-/** Retrieve one fixed window, including every continuation, then finish. */
+/** Retrieve one finite query window, including every continuation, then finish. */
 const readEventLogs = (options) => streamEventLogs(options, 'read');
 exports.readEventLogs = readEventLogs;
 /** Retrieve initial context, then keep reading overlapping live windows. */

package/oclif.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.3.0",
+  "version": "4.4.0",
   "commands": {
     "applications:create": {
       "id": "applications:create",
@@ -1135,13 +1135,16 @@
     },
     "proxies:logs:read": {
       "id": "proxies:logs:read",
-      "description": "Read a fixed window of Proxy runtime logs through Events and exit. Requires `event:read` and runtime logging already enabled.\n\nDefaults to the five minutes preceding --until, or command start when --until is omitted. Explicit relative values use command-start time. Both request and response transforms are included and distinguished. Windows include their start and exclude their end, filtering event batch timestamps rather than individual record occurrence times. Each matching batch is expanded in record sequence; flattened output has no global chronological ordering. History is tenant-limited (24 hours by default, at most 30 days); the API clamps unavailable history. Indexing is asynchronous and pagination is not a snapshot, so empty or exhausted results do not prove complete coverage. Large windows may hit bounded work limits and fail with partial output. Application logs come from the injected `logger`, not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform runtime-log gate. Does not enable logging or open a tunnel.",
+      "description": "Read a fixed window of Proxy runtime logs through Events and exit. Requires `event:read` and runtime logging already enabled.\n\nOptional --trace-id matches the effective stored BT trace ID exactly and case-sensitively. A submitted header may be sanitized by Vault; the CLI does not normalize or trim it. A reused trace ID can match multiple invocations. --transform-type filters request or response transforms, alone or combined with trace ID using AND; omitting it includes both directions.\n\nDefaults to the five minutes preceding --until, or command start when --until is omitted, regardless of filters. Supply --since, for example --since 30d, to request a larger window. Explicit relative values use command-start time. Windows include their start and exclude their end, filtering event batch timestamps rather than individual record occurrence times. Each matching batch is expanded in record sequence; flattened output has no global chronological ordering. History is limited by server retention and tenant entitlements; the API clamps unavailable history. Indexing is asynchronous and pagination is not a snapshot, so empty or exhausted results do not prove complete coverage. Large windows may hit bounded work limits and fail with partial output. Application logs come from the injected `logger`, not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform runtime-log gate. Does not enable logging or open a tunnel.",
       "strict": true,
       "pluginName": "@basis-theory-labs/cli",
       "pluginAlias": "@basis-theory-labs/cli",
       "pluginType": "core",
       "aliases": [],
       "examples": [
+        "<%= config.bin %> proxies logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42 --since 30d",
+        "<%= config.bin %> proxies logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --transform-type request_transform",
+        "<%= config.bin %> proxies logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42 --transform-type response_transform --since 30m",
         "<%= config.bin %> proxies logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --since 1h --until 30m",
         "<%= config.bin %> proxies logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --since 2026-10-01T10:00:00Z --until 2026-10-01T10:15:00Z --format json"
       ],
@@ -1161,6 +1164,22 @@
           "hidden": true,
           "multiple": false
         },
+        "trace-id": {
+          "name": "trace-id",
+          "type": "option",
+          "description": "exact, case-sensitive stored BT trace ID; combines with transform direction using AND",
+          "multiple": false
+        },
+        "transform-type": {
+          "name": "transform-type",
+          "type": "option",
+          "description": "exact transform direction; includes both directions when omitted",
+          "multiple": false,
+          "options": [
+            "request_transform",
+            "response_transform"
+          ]
+        },
         "since": {
           "name": "since",
           "type": "option",
@@ -1196,7 +1215,7 @@
     },
     "proxies:logs:tail": {
       "id": "proxies:logs:tail",
-      "description": "Tail Proxy runtime logs through Events. Requires `event:read` and runtime logging already enabled.\n\nStarts watching from command time. Supply --since to retrieve initial history before following new logs. Polls every five seconds with a rolling five-minute overlap that never reaches before the requested start. Both request and response transforms are included and distinguished. Time windows filter event batches, not individual record occurrence times; a newly arriving batch can contain records that occurred before command start. History is tenant-limited (24 hours by default, at most 30 days); the API clamps unavailable history. Large initial windows may hit bounded work limits and fail with partial output. Visibility is delayed and best-effort; output has no durable resume or global chronological ordering. Application logs come from the injected `logger`, not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform runtime-log gate. Silence does not distinguish an idle resource, a wrong ID, disabled collection, or delayed indexing. Runs until interrupted, output closes, or an error occurs.",
+      "description": "Tail Proxy runtime logs through Events. Requires `event:read` and runtime logging already enabled.\n\nOptional --trace-id matches the effective stored BT trace ID exactly and case-sensitively. A submitted header may be sanitized by Vault; the CLI does not normalize or trim it. A reused trace ID can match multiple invocations. --transform-type filters request or response transforms, alone or combined with trace ID using AND; omitting it includes both directions. Filters apply to initial history and every live poll.\n\nStarts watching from command time, regardless of filters. Supply --since to retrieve initial history before following new logs. Polls every five seconds with a rolling five-minute overlap that never reaches before the requested start. Time windows filter event batches, not individual record occurrence times; a newly arriving batch can contain records that occurred before command start. History is limited by server retention and tenant entitlements; the API clamps unavailable history. Large initial windows may hit bounded work limits and fail with partial output. Visibility is delayed and best-effort; output has no durable resume or global chronological ordering. Application logs come from the injected `logger`, not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform runtime-log gate. Silence does not distinguish an idle resource, a wrong ID or filter, disabled collection, or delayed indexing. Runs until interrupted, output closes, or an error occurs.",
       "strict": true,
       "pluginName": "@basis-theory-labs/cli",
       "pluginAlias": "@basis-theory-labs/cli",
@@ -1204,6 +1223,9 @@
       "aliases": [],
       "examples": [
         "<%= config.bin %> proxies logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca",
+        "<%= config.bin %> proxies logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42",
+        "<%= config.bin %> proxies logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --transform-type request_transform",
+        "<%= config.bin %> proxies logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42 --transform-type response_transform --since 30m --format json",
         "<%= config.bin %> proxies logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --since 30m --format json"
       ],
       "flags": {
@@ -1222,6 +1244,22 @@
           "hidden": true,
           "multiple": false
         },
+        "trace-id": {
+          "name": "trace-id",
+          "type": "option",
+          "description": "exact, case-sensitive stored BT trace ID; combines with transform direction using AND",
+          "multiple": false
+        },
+        "transform-type": {
+          "name": "transform-type",
+          "type": "option",
+          "description": "exact transform direction; includes both directions when omitted",
+          "multiple": false,
+          "options": [
+            "request_transform",
+            "response_transform"
+          ]
+        },
         "since": {
           "name": "since",
           "type": "option",
@@ -1251,13 +1289,14 @@
     },
     "reactors:logs:read": {
       "id": "reactors:logs:read",
-      "description": "Read a fixed window of Reactor runtime logs through Events and exit. Requires `event:read` and runtime logging already enabled.\n\nDefaults to the five minutes preceding --until, or command start when --until is omitted. Explicit relative values use command-start time. Windows include their start and exclude their end, filtering event batch timestamps rather than individual record occurrence times. Each matching batch is expanded in record sequence; flattened output has no global chronological ordering. History is tenant-limited (24 hours by default, at most 30 days); the API clamps unavailable history. Indexing is asynchronous and pagination is not a snapshot, so empty or exhausted results do not prove complete coverage. Large windows may hit bounded work limits and fail with partial output. Application logs come from the injected `logger`, not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform runtime-log gate. Does not enable logging or open a tunnel.",
+      "description": "Read a fixed window of Reactor runtime logs through Events and exit. Requires `event:read` and runtime logging already enabled.\n\nOptional --trace-id matches the effective stored BT trace ID exactly and case-sensitively. A submitted header may be sanitized by Vault; the CLI does not normalize or trim it. A reused trace ID can match multiple invocations.\n\nDefaults to the five minutes preceding --until, or command start when --until is omitted, regardless of filters. Supply --since, for example --since 30d, to request a larger window. Explicit relative values use command-start time. Windows include their start and exclude their end, filtering event batch timestamps rather than individual record occurrence times. Each matching batch is expanded in record sequence; flattened output has no global chronological ordering. History is limited by server retention and tenant entitlements; the API clamps unavailable history. Indexing is asynchronous and pagination is not a snapshot, so empty or exhausted results do not prove complete coverage. Large windows may hit bounded work limits and fail with partial output. Application logs come from the injected `logger`, not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform runtime-log gate. Does not enable logging or open a tunnel.",
       "strict": true,
       "pluginName": "@basis-theory-labs/cli",
       "pluginAlias": "@basis-theory-labs/cli",
       "pluginType": "core",
       "aliases": [],
       "examples": [
+        "<%= config.bin %> reactors logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42 --since 30d",
         "<%= config.bin %> reactors logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --since 1h --until 30m",
         "<%= config.bin %> reactors logs read 03858bf5-32d3-4a2e-b74b-daeea0883bca --since 2026-10-01T10:00:00Z --until 2026-10-01T10:15:00Z --format json"
       ],
@@ -1277,6 +1316,12 @@
           "hidden": true,
           "multiple": false
         },
+        "trace-id": {
+          "name": "trace-id",
+          "type": "option",
+          "description": "exact, case-sensitive stored BT trace ID",
+          "multiple": false
+        },
         "since": {
           "name": "since",
           "type": "option",
@@ -1312,7 +1357,7 @@
     },
     "reactors:logs:tail": {
       "id": "reactors:logs:tail",
-      "description": "Tail Reactor runtime logs through Events. Requires `event:read` and runtime logging already enabled.\n\nStarts watching from command time. Supply --since to retrieve initial history before following new logs. Polls every five seconds with a rolling five-minute overlap that never reaches before the requested start. Time windows filter event batches, not individual record occurrence times; a newly arriving batch can contain records that occurred before command start. History is tenant-limited (24 hours by default, at most 30 days); the API clamps unavailable history. Large initial windows may hit bounded work limits and fail with partial output. Visibility is delayed and best-effort; output has no durable resume or global chronological ordering. Application logs come from the injected `logger`, not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform runtime-log gate. Silence does not distinguish an idle resource, a wrong ID, disabled collection, or delayed indexing. Runs until interrupted, output closes, or an error occurs.",
+      "description": "Tail Reactor runtime logs through Events. Requires `event:read` and runtime logging already enabled.\n\nOptional --trace-id matches the effective stored BT trace ID exactly and case-sensitively. A submitted header may be sanitized by Vault; the CLI does not normalize or trim it. A reused trace ID can match multiple invocations.\n\nStarts watching from command time, regardless of filters. Supply --since to retrieve initial history before following new logs. Polls every five seconds with a rolling five-minute overlap that never reaches before the requested start. Time windows filter event batches, not individual record occurrence times; a newly arriving batch can contain records that occurred before command start. History is limited by server retention and tenant entitlements; the API clamps unavailable history. Large initial windows may hit bounded work limits and fail with partial output. Visibility is delayed and best-effort; output has no durable resume or global chronological ordering. Application logs come from the injected `logger`, not arbitrary stdout or `console.log`; collection requires resource opt-in and the platform runtime-log gate. Silence does not distinguish an idle resource, a wrong ID or filter, disabled collection, or delayed indexing. Runs until interrupted, output closes, or an error occurs.",
       "strict": true,
       "pluginName": "@basis-theory-labs/cli",
       "pluginAlias": "@basis-theory-labs/cli",
@@ -1320,6 +1365,8 @@
       "aliases": [],
       "examples": [
         "<%= config.bin %> reactors logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca",
+        "<%= config.bin %> reactors logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42",
+        "<%= config.bin %> reactors logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --trace-id customer_Order-42 --since 30m --format json",
         "<%= config.bin %> reactors logs tail 03858bf5-32d3-4a2e-b74b-daeea0883bca --since 30m --format json"
       ],
       "flags": {
@@ -1338,6 +1385,12 @@
           "hidden": true,
           "multiple": false
         },
+        "trace-id": {
+          "name": "trace-id",
+          "type": "option",
+          "description": "exact, case-sensitive stored BT trace ID",
+          "multiple": false
+        },
         "since": {
           "name": "since",
           "type": "option",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basis-theory-labs/cli",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "Basis Theory CLI tool",
   "author": "Davi Aquino @djejaquino",
   "bin": {