docs: update ODS documentation for friendly sandbox ID format

Add documentation for the realm-instance friendly ID format (e.g., zzzv-123)
to the ODS skill and CLI reference. Also refactor OdsCommand to inline the
lookup logic with user-facing log messages.

Author: clavery

docs/cli/ods.md

@@ -6,6 +6,23 @@ description: Commands for creating, managing, starting, stopping, and deleting O
 
 Commands for managing On-Demand Sandboxes (ODS).
 
+## Sandbox ID Formats
+
+Commands that operate on a specific sandbox (`get`, `start`, `stop`, `restart`, `delete`) accept two ID formats:
+
+| Format | Example | Description |
+|--------|---------|-------------|
+| UUID | `abc12345-1234-1234-1234-abc123456789` | Full sandbox UUID |
+| Friendly ID | `zzzv-123` or `zzzv_123` | Realm-instance format |
+
+The friendly ID format uses the 4-character realm code followed by a dash (`-`) or underscore (`_`) and the instance identifier. When using a friendly ID, the CLI automatically looks up the corresponding sandbox UUID.
+
+```bash
+# These are equivalent (assuming zzzv-123 resolves to the UUID)
+b2c ods get abc12345-1234-1234-1234-abc123456789
+b2c ods get zzzv-123
+```
+
 ## Global ODS Flags
 
 These flags are available on all ODS commands:
@@ -176,16 +193,19 @@ b2c ods get <SANDBOXID>
 
 | Argument | Description | Required |
 |----------|-------------|----------|
-| `SANDBOXID` | Sandbox ID (UUID) | Yes |
+| `SANDBOXID` | Sandbox ID (UUID or realm-instance, e.g., `zzzv-123`) | Yes |
 
 ### Examples
 
 ```bash
-# Get sandbox details
+# Get sandbox details using UUID
 b2c ods get abc12345-1234-1234-1234-abc123456789
 
+# Get sandbox details using friendly ID
+b2c ods get zzzv-123
+
 # Output as JSON
-b2c ods get abc12345-1234-1234-1234-abc123456789 --json
+b2c ods get zzzv_123 --json
 ```
 
 ### Output
@@ -244,16 +264,19 @@ b2c ods start <SANDBOXID>
 
 | Argument | Description | Required |
 |----------|-------------|----------|
-| `SANDBOXID` | Sandbox ID (UUID) | Yes |
+| `SANDBOXID` | Sandbox ID (UUID or realm-instance, e.g., `zzzv-123`) | Yes |
 
 ### Examples
 
 ```bash
-# Start a sandbox
+# Start a sandbox using UUID
 b2c ods start abc12345-1234-1234-1234-abc123456789
 
+# Start a sandbox using friendly ID
+b2c ods start zzzv-123
+
 # Output as JSON
-b2c ods start abc12345-1234-1234-1234-abc123456789 --json
+b2c ods start zzzv_123 --json
 ```
 
 ---
@@ -272,16 +295,19 @@ b2c ods stop <SANDBOXID>
 
 | Argument | Description | Required |
 |----------|-------------|----------|
-| `SANDBOXID` | Sandbox ID (UUID) | Yes |
+| `SANDBOXID` | Sandbox ID (UUID or realm-instance, e.g., `zzzv-123`) | Yes |
 
 ### Examples
 
 ```bash
-# Stop a sandbox
+# Stop a sandbox using UUID
 b2c ods stop abc12345-1234-1234-1234-abc123456789
 
+# Stop a sandbox using friendly ID
+b2c ods stop zzzv-123
+
 # Output as JSON
-b2c ods stop abc12345-1234-1234-1234-abc123456789 --json
+b2c ods stop zzzv_123 --json
 ```
 
 ---
@@ -300,16 +326,19 @@ b2c ods restart <SANDBOXID>
 
 | Argument | Description | Required |
 |----------|-------------|----------|
-| `SANDBOXID` | Sandbox ID (UUID) | Yes |
+| `SANDBOXID` | Sandbox ID (UUID or realm-instance, e.g., `zzzv-123`) | Yes |
 
 ### Examples
 
 ```bash
-# Restart a sandbox
+# Restart a sandbox using UUID
 b2c ods restart abc12345-1234-1234-1234-abc123456789
 
+# Restart a sandbox using friendly ID
+b2c ods restart zzzv-123
+
 # Output as JSON
-b2c ods restart abc12345-1234-1234-1234-abc123456789 --json
+b2c ods restart zzzv_123 --json
 ```
 
 ---
@@ -328,7 +357,7 @@ b2c ods delete <SANDBOXID>
 
 | Argument | Description | Required |
 |----------|-------------|----------|
-| `SANDBOXID` | Sandbox ID (UUID) | Yes |
+| `SANDBOXID` | Sandbox ID (UUID or realm-instance, e.g., `zzzv-123`) | Yes |
 
 ### Flags
 
@@ -339,11 +368,14 @@ b2c ods delete <SANDBOXID>
 ### Examples
 
 ```bash
-# Delete a sandbox (with confirmation prompt)
+# Delete a sandbox using UUID (with confirmation prompt)
 b2c ods delete abc12345-1234-1234-1234-abc123456789
 
+# Delete a sandbox using friendly ID
+b2c ods delete zzzv-123
+
 # Delete without confirmation
-b2c ods delete abc12345-1234-1234-1234-abc123456789 --force
+b2c ods delete zzzv_123 --force
 ```
 
 ### Notes

packages/b2c-tooling-sdk/src/cli/ods-command.ts

@@ -7,7 +7,7 @@ import {Command, Flags} from '@oclif/core';
 import {OAuthCommand} from './oauth-command.js';
 import {createOdsClient, type OdsClient} from '../clients/ods.js';
 import {DEFAULT_ODS_HOST} from '../defaults.js';
-import {resolveSandboxId, SandboxNotFoundError} from '../operations/ods/sandbox-lookup.js';
+import {isUuid, parseFriendlySandboxId, SandboxNotFoundError} from '../operations/ods/sandbox-lookup.js';
 
 /**
  * Base command for ODS (On-Demand Sandbox) operations.
@@ -89,7 +89,7 @@ export abstract class OdsCommand<T extends typeof Command> extends OAuthCommand<
    *
    * Supports both UUID format and friendly format (realm-instance, e.g., "abcd-123" or "abcd_123").
    * If given a UUID, returns it directly. If given a friendly format, queries the API to find
-   * the matching sandbox.
+   * the matching sandbox and logs the resolution.
    *
    * @param identifier - Sandbox identifier (UUID or friendly format)
    * @returns The sandbox UUID
@@ -102,13 +102,43 @@ export abstract class OdsCommand<T extends typeof Command> extends OAuthCommand<
    * ```
    */
   protected async resolveSandboxId(identifier: string): Promise<string> {
-    try {
-      return await resolveSandboxId(this.odsClient, identifier);
-    } catch (error) {
-      if (error instanceof SandboxNotFoundError) {
-        this.error(error.message);
-      }
-      throw error;
+    // If already a UUID, return directly
+    if (isUuid(identifier)) {
+      return identifier;
     }
+
+    // Try to parse as friendly ID
+    const parsed = parseFriendlySandboxId(identifier);
+    if (!parsed) {
+      // Not a UUID and not a friendly ID - pass through as-is
+      // (let the API return an appropriate error)
+      return identifier;
+    }
+
+    // Log that we're looking up the sandbox
+    this.log(`Looking up sandbox ${identifier}...`);
+
+    // Query sandboxes filtered by realm
+    const {data, error} = await this.odsClient.GET('/sandboxes', {
+      params: {
+        query: {
+          filter_params: `realm=${parsed.realm}`,
+        },
+      },
+    });
+
+    if (error || !data?.data) {
+      this.error(new SandboxNotFoundError(identifier, parsed.realm, parsed.instance).message);
+    }
+
+    // Find sandbox with matching instance
+    const sandbox = data.data.find((s) => s.instance?.toLowerCase() === parsed.instance);
+
+    if (!sandbox?.id) {
+      this.error(new SandboxNotFoundError(identifier, parsed.realm, parsed.instance).message);
+    }
+
+    this.log(`Resolved ${identifier} to sandbox ${sandbox.id}`);
+    return sandbox.id;
   }
 }

plugins/b2c-cli/skills/b2c-ods/SKILL.md

@@ -7,6 +7,15 @@ description: Create and manage on-demand sandboxes (ODS). Use when provisioning
 
 Use the `b2c` CLI plugin to manage Salesforce B2C Commerce On-demand sandboxes (ODS). Only create or delete a sandbox if explicitly asked as this may be a billable or destructible action.
 
+## Sandbox ID Formats
+
+Commands that operate on a specific sandbox accept two ID formats:
+
+- **UUID**: The full sandbox UUID (e.g., `abc12345-1234-1234-1234-abc123456789`)
+- **Friendly ID**: The realm-instance format (e.g., `zzzv-123` or `zzzv_123`)
+
+The friendly ID format uses the 4-character realm code followed by a dash or underscore and the instance number. When using a friendly ID, the CLI will automatically look up the corresponding UUID.
+
 ## Examples
 
 ### List ODS Sandboxes
@@ -36,6 +45,24 @@ b2c ods create --realm zzpq --profile large
 b2c ods create --realm zzpq --log-level trace
 ```
 
+### Get/Start/Stop/Restart/Delete Sandbox
+
+Commands that operate on a specific sandbox support both UUID and friendly ID formats:
+
+```bash
+# Using UUID
+b2c ods get abc12345-1234-1234-1234-abc123456789
+b2c ods start abc12345-1234-1234-1234-abc123456789
+b2c ods stop abc12345-1234-1234-1234-abc123456789
+
+# Using friendly ID (realm-instance)
+b2c ods get zzzv-123
+b2c ods start zzzv_123
+b2c ods stop zzzv-123
+b2c ods restart zzzv-123
+b2c ods delete zzzv-123 --force
+```
+
 ### More Commands
 
 See `b2c ods --help` for a full list of available commands and options in the `ods` topic.