From 60593a899a945c31445a8f4c471771c62e31b5a4 Mon Sep 17 00:00:00 2001 From: Felipe Fumero Date: Wed, 23 Sep 2026 15:22:28 -0600 Subject: [PATCH 1/4] docs: document B2_ENVIRONMENT --- README.md | 2 ++ b2/_internal/console_tool.py | 4 ++++ changelog.d/1162.doc.md | 1 + test/unit/console_tool/test_help.py | 2 +- 4 files changed, 8 insertions(+), 1 deletion(-) create mode 100644 changelog.d/1162.doc.md diff --git a/README.md b/README.md index 1f4918bb7..967d13692 100644 --- a/README.md +++ b/README.md @@ -80,6 +80,8 @@ b2 version Print the version number of this tool. The environment variable `B2_ACCOUNT_INFO` specifies the SQLite file to use for caching authentication information. The default file to use is: `~/.b2_account_info`. +The optional environment variable `B2_ENVIRONMENT` selects the authorization realm; leave it +unset for production, or set it to a known realm name or a custom API endpoint URL. To get more details on a specific command use `b2 --help`. diff --git a/b2/_internal/console_tool.py b/b2/_internal/console_tool.py index 130fc8fba..b6f0d0eb6 100644 --- a/b2/_internal/console_tool.py +++ b/b2/_internal/console_tool.py @@ -1273,6 +1273,10 @@ class B2(Command): A string provided via an optional environment variable ``{B2_USER_AGENT_APPEND_ENV_VAR}`` will be appended to the User-Agent. + + The optional environment variable ``{B2_ENVIRONMENT_ENV_VAR}`` selects the authorization + realm. Leave it unset for production, or set it to a known realm name or a custom API + endpoint URL. """ REQUIRES_AUTH = False diff --git a/changelog.d/1162.doc.md b/changelog.d/1162.doc.md new file mode 100644 index 000000000..ae9c0c9b3 --- /dev/null +++ b/changelog.d/1162.doc.md @@ -0,0 +1 @@ +Document the ``B2_ENVIRONMENT`` authorization-realm environment variable. diff --git a/test/unit/console_tool/test_help.py b/test/unit/console_tool/test_help.py index 0d72c1b8c..5f0986e25 100644 --- a/test/unit/console_tool/test_help.py +++ b/test/unit/console_tool/test_help.py @@ -16,7 +16,7 @@ # --help shouldn't show deprecated commands ( '--help', - [' b2 file ', '-h', '--help-all'], + [' b2 file ', '-h', '--help-all', 'B2_ENVIRONMENT'], [' b2 download-file-by-name ', '(DEPRECATED)'], ), # --help-all should show deprecated commands, but marked as deprecated From 2af816fd9361ebce77025bb1ebd083983e8de515 Mon Sep 17 00:00:00 2001 From: Felipe Fumero Date: Thu, 24 Sep 2026 11:21:51 -0600 Subject: [PATCH 2/4] docs: drop B2_ENVIRONMENT from main --help (PR #1163 review) --- b2/_internal/console_tool.py | 4 ---- test/unit/console_tool/test_help.py | 2 +- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/b2/_internal/console_tool.py b/b2/_internal/console_tool.py index b6f0d0eb6..130fc8fba 100644 --- a/b2/_internal/console_tool.py +++ b/b2/_internal/console_tool.py @@ -1273,10 +1273,6 @@ class B2(Command): A string provided via an optional environment variable ``{B2_USER_AGENT_APPEND_ENV_VAR}`` will be appended to the User-Agent. - - The optional environment variable ``{B2_ENVIRONMENT_ENV_VAR}`` selects the authorization - realm. Leave it unset for production, or set it to a known realm name or a custom API - endpoint URL. """ REQUIRES_AUTH = False diff --git a/test/unit/console_tool/test_help.py b/test/unit/console_tool/test_help.py index 5f0986e25..0d72c1b8c 100644 --- a/test/unit/console_tool/test_help.py +++ b/test/unit/console_tool/test_help.py @@ -16,7 +16,7 @@ # --help shouldn't show deprecated commands ( '--help', - [' b2 file ', '-h', '--help-all', 'B2_ENVIRONMENT'], + [' b2 file ', '-h', '--help-all'], [' b2 download-file-by-name ', '(DEPRECATED)'], ), # --help-all should show deprecated commands, but marked as deprecated From 2c81fda6aa39ea0979432034e9afc1b17f5ccb8a Mon Sep 17 00:00:00 2001 From: Felipe Fumero Date: Thu, 24 Sep 2026 11:30:45 -0600 Subject: [PATCH 3/4] docs: point account-info location to b2 account get (PR #1163 review) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 967d13692..21b21246c 100644 --- a/README.md +++ b/README.md @@ -79,7 +79,7 @@ b2 version Print the version number of this tool. The environment variable `B2_ACCOUNT_INFO` specifies the SQLite file to use for caching authentication information. -The default file to use is: `~/.b2_account_info`. +Run `b2 account get` to see the file currently in use; its location depends on your profile and environment (see `b2 --help` for the resolution rules). The optional environment variable `B2_ENVIRONMENT` selects the authorization realm; leave it unset for production, or set it to a known realm name or a custom API endpoint URL. From c3943d670f9c3e18ee53b11644c33433ca39cb6c Mon Sep 17 00:00:00 2001 From: Felipe Fumero Date: Thu, 24 Sep 2026 11:37:17 -0600 Subject: [PATCH 4/4] docs: move B2_ENVIRONMENT to a dedicated advanced/dev doc (PR #1163 review) --- README.md | 3 +-- doc/authorization_realm.md | 12 ++++++++++++ 2 files changed, 13 insertions(+), 2 deletions(-) create mode 100644 doc/authorization_realm.md diff --git a/README.md b/README.md index 21b21246c..820fe37ff 100644 --- a/README.md +++ b/README.md @@ -80,8 +80,6 @@ b2 version Print the version number of this tool. The environment variable `B2_ACCOUNT_INFO` specifies the SQLite file to use for caching authentication information. Run `b2 account get` to see the file currently in use; its location depends on your profile and environment (see `b2 --help` for the resolution rules). -The optional environment variable `B2_ENVIRONMENT` selects the authorization realm; leave it -unset for production, or set it to a known realm name or a custom API endpoint URL. To get more details on a specific command use `b2 --help`. @@ -167,3 +165,4 @@ Please refer to the [changelog](CHANGELOG.md). ## Developer Info Please see our [contributing guidelines](CONTRIBUTING.md). +See [Authorization realm](doc/authorization_realm.md) for `B2_ENVIRONMENT` and related development flags. diff --git a/doc/authorization_realm.md b/doc/authorization_realm.md new file mode 100644 index 000000000..0616b7206 --- /dev/null +++ b/doc/authorization_realm.md @@ -0,0 +1,12 @@ +# Authorization realm (advanced / Backblaze development) + +By default, the B2 CLI talks to the production Backblaze B2 authorization realm. The controls +below exist mainly for Backblaze development and testing. + +- `B2_ENVIRONMENT` selects the Backblaze authorization realm. Leave it unset for production, or + set it to a known realm name or a full B2 API endpoint URL. +- The hidden flags `--environment `, `--dev`, and `--staging` provide equivalent + realm-selection controls for the same purpose. + +> **Note:** These controls select which Backblaze realm the CLI authenticates against. They are +> not a way to namespace your own data or point the CLI at your own testing or staging server.