wandb · johndmulhausen · Jun 4, 2026
@@ -1,3 +1,3 @@
 <Note>
-For a more streamlined approach, create an API key by going directly to [User Settings](https://wandb.ai/settings). Copy the newly created API key immediately and save it in a secure location such as a password manager.
+For a more streamlined approach, create an API key directly in [User Settings](https://wandb.ai/settings). Copy the new API key immediately and save it in a secure location such as a password manager.
 </Note>
@@ -1,7 +1,7 @@
 import ApiKeyViewOnceWarning from "/snippets/_includes/api-key-view-once-warning.mdx";
 import ServiceAccountApiKeyCreate from "/snippets/_includes/service-account-api-key-create-additional.mdx";
 
-To create an API key, select the **Personal API key** or **Service Account API key** tab for details.
+To create an API key, select the **Personal API key** or **Service account API key** tab.
 
 <Tabs>
 <Tab title="Personal API key">

@@ -18,10 +18,10 @@ To find a personal API key owned by your user ID:
 <Tab title="Service account API key">
 To find an API key owned by an organization or team service account:
 
-1. Navigate to the **API Keys** tab in your organization settings.
+1. In your organization settings, navigate to the **API Keys** tab.
 2. Find the API key in the list. You can search or filter the list by owner, key name, or key ID.
 
 </Tab>
 </Tabs>
 
-The API keys table shows the key ID (the first part of each API key) for identification purposes. The full secret API key is only displayed once when you create it. If you need to use an existing key but do not have the full secret stored, you must create a new API key.
+The API keys table shows the key ID (the first part of each API key) for identification. The full secret API key is only displayed once when you create it. If you need to use an existing key but don't have the full secret stored, you must create a new API key.
@@ -1,54 +1,58 @@
 ## Store and handle API keys securely
 
-API keys provide access to your W&B account and should be protected like passwords. Follow these best practices:
+API keys provide access to your W&B account and you must protect them like passwords. The following sections describe recommended storage methods, practices to avoid, and how to handle API keys in your code so that you can reduce the risk of accidental exposure.
 
 ### Recommended storage methods
 
+Choose a storage method based on whether you use the key in production systems or on a local workstation. We recommend the following options:
+
 - **Secrets manager**: Use a dedicated secrets management system such as [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/), [HashiCorp Vault](https://developer.hashicorp.com/vault), [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault), or [Google Secret Manager](https://cloud.google.com/security/products/secret-manager).
 - **Password manager**: Use a reputable password manager application.
-- **OS-level keychains**: Store keys in macOS Keychain, Windows Credential Manager, or Linux secret service. Not suggested for production.
+- **OS-level keychains**: Store keys in macOS Keychain, Windows Credential Manager, or Linux secret service. We don't recommend this option for production.
 
 ### What to avoid
 
-- Never commit API keys to version control systems such as Git.
-- Do not store API keys in plain text configuration files.
-- Do not pass API keys on the command line, because they will be visible in the output of OS commands like `ps`.
-- Avoid sharing API keys through email, chat, or other unencrypted channels.
-- Do not hard-code API keys in your source code.
+The following practices can expose API keys to other users, processes, or public systems. You must not:
+
+- Commit API keys to version control systems such as Git.
+- Store API keys in plain text configuration files.
+- Pass API keys on the command line, because they're visible in the output of OS commands like `ps`.
+- Share API keys through email, chat, or other unencrypted channels.
+- Hard-code API keys in your source code.
 
-If an API key is exposed, delete the API key from your W&B account immediately and contact [support](mailto:support@wandb.ai) or your AISE.
+If an API key is exposed, delete it from your W&B account immediately and contact [support](mailto:support@wandb.ai) or your AISE.
 
 ### Environment variables
 
-When using API keys in your code, pass them through environment variables:
+When you use API keys in your code, pass them through environment variables so that the key stays out of source files and is easier to rotate. Replace `[API-KEY]` with your W&B API key:
 
 ```bash
-export WANDB_API_KEY="your-api-key-here"
+export WANDB_API_KEY="[API-KEY]"
 ```
 
-This approach keeps keys out of your source code and makes it easier to rotate them when needed.
-
 <Warning>
-Avoid setting the environment variable in line with the command, because it will be visible in the output of OS commands like `ps`:
+Avoid setting the environment variable on the same line as the command, because it's visible in the output of OS commands like `ps`. Replace `[API-KEY]` with your W&B API key:
 
 ```bash
 # Avoid this pattern, which can expose the API key in process managers
-export WANDB_API_KEY="your-api-key-here" ./my-script.sh
+export WANDB_API_KEY="[API-KEY]" ./my-script.sh
 ```
 </Warning>
 
 ### SDK version compatibility
 
-New API keys are longer than legacy keys. When authenticating with older versions of the `wandb` or `weave` SDKs, you may encounter an API key length error.
+New API keys are longer than legacy keys. When you authenticate with older versions of the `wandb` or `weave` SDKs, you might encounter an API key length error. To resolve this error, update to a newer SDK version:
 
-**Solution**: Update to a newer SDK version:
-- `wandb` SDK v0.22.3+
+- `wandb` SDK v0.22.3+:
 
     ```bash
     pip install --upgrade wandb==0.22.3
     ```
-- `weave` SDK v0.52.17+
+
+- `weave` SDK v0.52.17+:
+
     ```bash
     pip install --upgrade weave==0.52.17
     ```
-If you cannot upgrade the SDK immediately, set the API key using the `WANDB_API_KEY` environment variable as a workaround.
+
+If you can't upgrade the SDK immediately, set the API key using the `WANDB_API_KEY` environment variable as a workaround.
@@ -1,3 +1,3 @@
 <Warning>
-The full API key is only shown once at creation time. After you close the dialog, you cannot view the full API key again. Only the key ID (first part of the key) is visible in your settings. If you lose the full API key, you must create a new API key.
+The full API key appears only once, when you create it. After you close the dialog, you can't view the full API key again. Your settings show only the key ID (the first part of the key). If you lose the full API key, create a new one.
 </Warning>
@@ -1,5 +1,5 @@
 <Note>
-**This guide applies to all W&B deployment types:**
+This guide applies to all W&B deployment types:
 - **Multi-tenant Cloud**: Team-level BYOB
 - **Dedicated Cloud**: Instance and team-level BYOB
 - **Self-Managed**: Instance and team-level BYOB

@@ -1,10 +1,10 @@
 ### Provision your storage bucket
 
-Before configuring W&B, provision your object storage bucket with proper IAM policies, CORS configuration, and access credentials.
+Before you configure W&B, you must provision your object storage bucket with the appropriate IAM policies, CORS configuration, and access credentials. This ensures that W&B can read from and write to your bucket after you configure the connection.
 
-**See the [Bring Your Own Bucket (BYOB) guide](/platform/hosting/data-security/secure-storage-connector) for detailed step-by-step provisioning instructions for:**
-- Amazon S3 (including IAM policies and bucket policies)
-- Google Cloud Storage (including PubSub notifications)
-- Azure Blob Storage (including managed identities)
-- CoreWeave AI Object Storage
-- S3-compatible storage (MinIO Enterprise, NetApp StorageGRID, and other enterprise solutions)
+See the [Bring Your Own Bucket (BYOB) guide](/platform/hosting/data-security/secure-storage-connector) for step-by-step provisioning instructions for the following storage providers:
+- Amazon S3 (including IAM policies and bucket policies).
+- Google Cloud Storage (including Pub/Sub notifications).
+- Azure Blob Storage (including managed identities).
+- CoreWeave AI Object Storage.
+- S3-compatible storage (MinIO Enterprise, NetApp StorageGRID).
@@ -1,21 +1,23 @@
-# CLI Reference Intro Snippets
+# CLI reference intro snippets
 
-This directory contains introductory content for W&B CLI commands that gets included in the auto-generated CLI reference pages.
+This directory contains introductory content for W&B CLI commands that's included in the auto-generated CLI reference pages. This README is for docs contributors who want to add or update intro content for a CLI command reference page.
 
 ## Purpose
 
-The CLI reference pages (`models/ref/cli/`) are auto-generated from the W&B CLI source code using `scripts/cli-docs-generator.py`. However, some commands benefit from additional context, examples, or explanations beyond what's in the CLI help text. This directory holds that supplementary content.
+The `scripts/cli-docs-generator.py` script auto-generates the CLI reference pages in `models/ref/cli/` from the W&B CLI source code. However, some commands benefit from additional context, examples, or explanations beyond what's in the CLI help text. This directory holds that supplementary content.
 
-## How It Works
+## How it works
 
-1. **Snippet files** are created here with the naming pattern: `wandb-{command}.mdx`
+The generation process works as follows:
+
+1. Create **snippet files** here with the naming pattern `wandb-[COMMAND].mdx`.
    - Example: `wandb-login.mdx`, `wandb-sync.mdx`, `wandb-verify.mdx`
    - For nested commands, use the full command with dashes: `wandb-artifact-get.mdx`
 
-2. **Generation script** automatically detects these snippets and:
-   - Adds an import statement at the top of the generated page
-   - Includes the snippet content right after the front matter, before the Usage section
-   - For pages without snippets, adds a commented-out template showing how to add one
+2. The **generation script** automatically detects these snippets and:
+   - Adds an import statement at the top of the generated page.
+   - Includes the snippet content immediately after the front matter, before the Usage section.
+   - For pages without snippets, adds a commented-out template that shows how to add one.
 
 3. **Generated page structure**:
    ```markdown
@@ -30,19 +32,22 @@ The CLI reference pages (`models/ref/cli/`) are auto-generated from the W&B CLI
    [auto-generated content from CLI]
    ```
 
-## Adding Intro Content for a Command
+## Add intro content for a command
 
-To add introductory content for a command:
+Follow these steps to add introductory content that appears above the auto-generated reference for a CLI command.
 
-1. Create a new snippet with the correct naming: `wandb-{command-name}.mdx`.
-2. Write the intro content in MDX format (can include markdown, code blocks, etc.).
-3. In the generated CLI reference for the command, uncomment the lines to include and use the snippet. No need to regenerate all of the references.
-4. Next time the references are generated, the generator will automatically detect and include your snippet.
+1. Create a new snippet with the correct naming, `wandb-[COMMAND-NAME].mdx`. The generator uses this filename to match the snippet to its command.
+2. Write the intro content in MDX format, which can include Markdown and code blocks.
+3. In the generated CLI reference for the command, uncomment the lines to include and use the snippet. You don't need to regenerate all of the references.
+4. The next time you generate the references, the generator automatically detects and includes your snippet.
 
+Once you complete these steps, the snippet appears on the command's reference page immediately above the Usage section, and persists across subsequent regenerations.
 
 ## Guidelines
 
-- Keep content concise and focused on what users need to know before the command details
-- Use code blocks for examples
-- Avoid duplicating information that's already in the auto-generated command options/arguments
-- Test locally after adding a snippet to ensure it renders correctly
+Apply the following guidelines when authoring snippet content to keep intro sections consistent across CLI reference pages.
+
+- Keep content concise and focused on what users need to know before the command details.
+- Use code blocks for examples.
+- Snippets must avoid duplicating information that's already in the auto-generated command options or arguments.
+- After you add a snippet, test locally to ensure it renders correctly.