From 1577d4ed56699d371fb44e222fc19d8ea677de99 Mon Sep 17 00:00:00 2001
From: joshuabrink <joshua@powersync.com>
Date: Tue, 26 May 2026 14:58:11 +0200
Subject: [PATCH] Document --env flag and shell exports for test-client
 commands

---
 resources/usage-and-billing/usage-and-billing-faq.mdx | 2 ++
 snippets/dev-token-self-hosted-steps.mdx              | 6 ++++++
 2 files changed, 8 insertions(+)

diff --git a/resources/usage-and-billing/usage-and-billing-faq.mdx b/resources/usage-and-billing/usage-and-billing-faq.mdx
index 8dfd0bc3..79a892d8 100644
--- a/resources/usage-and-billing/usage-and-billing-faq.mdx
+++ b/resources/usage-and-billing/usage-and-billing-faq.mdx
@@ -220,6 +220,8 @@ Data hosted can temporarily spike during Sync Rule deployments and defragmentati
      node dist/bin.js fetch-operations --raw --token your-jwt --endpoint https://12345.powersync.journeyapps.com
      ```
 
+     If you generate the token from a config that uses `!env PS_*` tags, the test-client reads them from your shell; pass `--env path/to/.env` to load them from a file instead.
+
      This returns the individual operations for a user in JSON. Example response:
 
      ```bash
diff --git a/snippets/dev-token-self-hosted-steps.mdx b/snippets/dev-token-self-hosted-steps.mdx
index 61b6983a..4c7e658d 100644
--- a/snippets/dev-token-self-hosted-steps.mdx
+++ b/snippets/dev-token-self-hosted-steps.mdx
@@ -106,6 +106,12 @@
         node dist/bin.js generate-token --config path/to/service.yaml --sub test-user
         ```
 
+        If your config uses `!env PS_*` tags to reference environment variables, the test-client reads them from your shell. To load them from a file instead, pass `--env`:
+
+        ```bash
+        node dist/bin.js generate-token --config path/to/service.yaml --env path/to/.env --sub test-user
+        ```
+
         Replace `test-user` with the user ID you want to authenticate:
         - If your Sync Streams aren't filtered by user (same data syncs to all users), you can use any value (e.g., `test-user`).
         - If your data is filtered by <Tooltip tip="Values such as user ID that are used to determine which data syncs to which user.">parameters</Tooltip>, use a user ID that matches a user in your database. PowerSync uses this value (e.g. via `auth.user_id()`) to determine what to sync.