Proxies

Commands for managing Pre-Configured Proxies.

List Proxies

bt proxies

Lists all Proxies in your tenant with pagination. When run interactively, selecting a Proxy provides options to view details, stream logs, or delete.

Flags

Flag	Short	Type	Default	Description
--management-key	-x	string	BT_MANAGEMENT_KEY env var	Management API key
--page	-p	integer	1	Page number to fetch

Required Permissions

proxy:read

Example

bt proxies -p 2

---

Create Proxy

bt proxies create

Creates a new Pre-Configured Proxy. When flags are omitted, the CLI will interactively prompt for required values.

Flags

Basic

Flag	Short	Type	Default	Description
--management-key	-x	string	BT_MANAGEMENT_KEY env var	Management API key
--name	-n	string	(prompted)	Name of the Proxy
--destination-url	-u	string	(prompted)	URL to which requests will be proxied
--application-id	-i	string	—	Optional Application ID. Only supported when at least one transform uses node-bt.
--configuration	-c	file path	—	Path to .env format configuration file
--require-auth	-a	boolean	true	Require Basis Theory authentication

Request Transform

The node-bt runtime is deprecated. Use a Node.js runtime image for new Reactors and Proxy code transforms. Migrate away from the node-bt runtime as soon as possible to avoid disruption.

Flag	Short	Type	Default	Description
--request-transform-code	-q	file path	—	Path to JavaScript file with request transform logic
--request-transform-image		string	—	Runtime image. Select a Node.js runtime image for new code transforms.
--request-transform-timeout		integer	10	Timeout in seconds, 10 to 30 (Node.js runtime images only)
--request-transform-warm-concurrency		integer	0	Number of warm instances. The default quota is 0. Request a higher quota if needed. (Node.js runtime images only)
--request-transform-resources		string	standard	Resource tier: standard, large, xlarge (Node.js runtime images only)
--request-transform-package-json		file path	-	Path to a package.json file specifying dependencies (Node.js runtime images only)
--request-transform-permissions		string[]	—	Permission grants, repeatable (Node.js runtime images only)

Response Transform

Flag	Short	Type	Default	Description
--response-transform-code	-s	file path	—	Path to JavaScript file with response transform logic
--response-transform-image		string	—	Runtime image. Select a Node.js runtime image for new code transforms.
--response-transform-timeout		integer	10	Timeout in seconds, 10 to 30 (Node.js runtime images only)
--response-transform-warm-concurrency		integer	0	Number of warm instances. The default quota is 0. Request a higher quota if needed. (Node.js runtime images only)
--response-transform-resources		string	standard	Resource tier: standard, large, xlarge (Node.js runtime images only)
--response-transform-package-json		file path	-	Path to a package.json file specifying dependencies (Node.js runtime images only)
--response-transform-permissions		string[]	—	Permission grants, repeatable (Node.js runtime images only)

Advanced

Flag	Type	Default	Description
--no-wait	boolean	false	Don't wait for the Proxy to be ready (Node.js runtime images only)

The --no-wait flag is only valid when at least one transform uses a Node.js runtime image.

Required Permissions

proxy:create

Examples

Create a Proxy with a node24 request transform:

bt proxies create \
  -n "My Proxy" \
  -u "https://api.example.com" \
  --request-transform-code ./request.js \
  --request-transform-image node24 \
  --request-transform-package-json ./package.json \
  --request-transform-timeout 15

Create a Proxy with the deprecated node-bt runtime:

bt proxies create \
  -n "My Proxy" \
  -u "https://api.example.com" \
  -i "your-application-id" \
  --request-transform-code ./request.js \
  --request-transform-image node-bt

---

Update Proxy

bt proxies update <id>

Updates an existing Proxy.

Arguments

Argument	Required	Description
id	Yes	The Proxy ID to update

Flags

All flags from Create Proxy, plus:

Flag	Short	Type	Default	Description
--watch	-w	boolean	false	Watch code and configuration files for changes and auto-update
--logs	-l	boolean	false	Open the legacy log tunnel after update (deprecated)

For configurable Node.js runtimes, enable runtime-log capture and use logs tail to follow records.

The --watch flag monitors your code and configuration files for changes, automatically redeploying when files are saved. This is useful during development.

Required Permissions

proxy:update

Examples

Update and watch for file changes:

bt proxies update 03858bf5-32d3-4a2e-b74b-daeea0883bca \
  --request-transform-code ./request.js \
  -w

---

Delete Proxy

bt proxies delete <id>

Deletes a Proxy. By default, the CLI will prompt for confirmation before deleting.

Arguments

Argument	Required	Description
id	Yes	The Proxy ID to delete

Flags

Flag	Short	Type	Default	Description
--management-key	-x	string	BT_MANAGEMENT_KEY env var	Management API key
--yes	-y	boolean	false	Skip confirmation prompt

Required Permissions

proxy:delete

Example

bt proxies delete 03858bf5-32d3-4a2e-b74b-daeea0883bca -y

---

Proxy Logs

Use runtime logs to troubleshoot your Proxy code transforms and inspect their execution details. Review captured logs with logs read, or follow new logs with logs tail.

The Proxy code transform must use a supported Node.js runtime image and have logging enabled.

Use a Management API key with the log:read permission.

Read Runtime Logs

Read Proxy Runtime Logs

bt proxies logs read '<PROXY_ID>'

Reads Proxy runtime logs from the last hour by default.

Arguments

Argument	Required	Description
id	Yes	The Proxy ID to read runtime-log records from

Flags

Flag	Short	Type	Default	Description
--management-key	-x	string	BT_MANAGEMENT_KEY environment variable	Management API key. Required unless supplied through BT_MANAGEMENT_KEY. See CLI authentication.
--trace-id	—	string	—	Match the BT trace ID exactly (case-sensitive).
--level	—	string	—	Match one application-log level, such as debug, info, warn, or error. This is not a minimum-severity threshold.
--message-search	—	string	—	Match all query words in one message. See Search Runtime-Log Messages.
--transform-type	—	string	—	Restrict results to request_transform or response_transform. Omit to include both directions.
--since	—	string	One hour before --until	Include logs at or after this time. See Time Formats.
--until	—	string	Now	Include logs before this time. See Time Formats.
--format	—	string	pretty	Output format: pretty, json, or json-pretty. See CLI output formats.

Examples

Read Proxy Logs from the Last Hour

bt proxies logs read '<PROXY_ID>' --since 1h

Read Proxy Logs in a Fixed Time Range

bt proxies logs read '<PROXY_ID>' --since '2026-10-01T10:00:00Z' --until '2026-10-01T10:15:00Z'

Tail Runtime Logs

Tail Proxy Runtime Logs

bt proxies logs tail '<PROXY_ID>'

Follows new Proxy runtime logs. Use --since to include earlier logs when starting. Press Ctrl-C to stop.

Arguments

Argument	Required	Description
id	Yes	The Proxy ID to tail runtime-log records from

Flags

Flag	Short	Type	Default	Description
--management-key	-x	string	BT_MANAGEMENT_KEY environment variable	Management API key. Required unless supplied through BT_MANAGEMENT_KEY. See CLI authentication.
--trace-id	—	string	—	Match the BT trace ID exactly (case-sensitive).
--level	—	string	—	Match one application-log level, such as debug, info, warn, or error. This is not a minimum-severity threshold.
--message-search	—	string	—	Match all query words in one message. See Search Runtime-Log Messages.
--transform-type	—	string	—	Restrict results to request_transform or response_transform. Omit to include both directions.
--since	—	string	New logs only	Include logs from this time before following new records. See Time Formats.
--format	—	string	pretty	Output format: pretty, json, or json-pretty. See CLI output formats.

Tail Renewal

Interactive sessions ask Keep tailing? every 60 minutes. Press Enter to stop or choose Yes to continue. Noninteractive sessions stop after 60 minutes.

Example

Tail Proxy Logs with Filtered Catch-up

bt proxies logs tail '<PROXY_ID>' --trace-id '<TRACE_ID>' --message-search 'payment failed' --transform-type response_transform --since 5m

Time Formats

--since and --until accept either format below. --until is available only with logs read.

Time format	Examples	Details
Relative duration	30m, 1h	Use s for seconds, m for minutes, h for hours, d for days, or w for weeks.
Timestamp	2026-10-01T12:00:00Z	Use an ISO 8601 timestamp with a timezone.

Retrieval Limits

Both logs read and logs tail are subject to retrieval limits. If you reach a limit, add filters or use logs read with a shorter time range.

---

Legacy Live Logs (Deprecated)

The legacy tunnel is deprecated but remains supported for existing workflows. For supported Node.js runtimes, enable runtime logs and use Read Runtime Logs or Tail Runtime Logs instead.

The legacy command opens a local tunnel and modifies the Proxy's logging configuration.

bt proxies logs [id]

If no ID is provided, the CLI prompts you to select a Proxy. The interactive management menu's Logs action and bt proxies update --logs (-l) also open this legacy tunnel.

Arguments

Argument	Required	Description
id	No	The Proxy ID to open the legacy logs tunnel for

Flags

Flag	Short	Type	Default	Description
--management-key	-x	string	BT_MANAGEMENT_KEY environment variable	Management API key
--port	-p	integer	8220	Port for the local logs server

Required Permissions

proxy:update