chore: Add examples to the CLI help output for endpoint commands (#354)

Author: blainekasten

src/together/lib/cli/__init__.py

@@ -26,6 +26,13 @@
 from together.lib.cli.utils._console import console
 from together.lib.cli.utils._api_error import try_handle_server_error_message
 from together.lib.cli.utils._completion import install_completion
+from together.lib.cli.utils._help_examples import (
+    ENDPOINTS_HELP_EXAMPLES,
+    TOP_LEVEL_HELP_EXAMPLES,
+    ENDPOINTS_CREATE_HELP_EXAMPLES,
+    ENDPOINTS_UPDATE_HELP_EXAMPLES,
+    ENDPOINTS_HARDWARE_HELP_EXAMPLES,
+)
 from together.lib.cli.utils._help_formatter import help_formatter
 from together.lib.cli.utils._preparse_tokens import preparse_tokens
 
@@ -326,17 +333,28 @@ async def run_command() -> None:
 ## Endpoints API commands
 endpoints_app = app.command(App(name="endpoints", help="Deploy and manage dedicated endpoints"))
 endpoints_app.command(
-    (f"{_CLI}.endpoints.hardware:hardware"), help="List available hardware configurations for deploying models"
+    (f"{_CLI}.endpoints.hardware:hardware"),
+    help="List available hardware configurations for deploying models",
+    help_epilogue=ENDPOINTS_HARDWARE_HELP_EXAMPLES,
+)
+endpoints_app.command(
+    (f"{_CLI}.endpoints.create:create"),
+    alias="-c",
+    help="Create a new endpoint",
+    help_epilogue=ENDPOINTS_CREATE_HELP_EXAMPLES,
 )
-endpoints_app.command((f"{_CLI}.endpoints.create:create"), alias="-c", help="Create a new endpoint")
-endpoints_app.command((f"{_CLI}.endpoints.retrieve:retrieve"), help="Get endpoint details")
-endpoints_app.command((f"{_CLI}.endpoints.stop:stop"), help="Stop an endpoint")
-endpoints_app.command((f"{_CLI}.endpoints.start:start"), help="Start an endpoint")
-endpoints_app.command((f"{_CLI}.endpoints.delete:delete"), alias="-d", help="Delete an endpoint")
-endpoints_app.command((f"{_CLI}.endpoints.list:list"), alias="ls", help="List your endpoints")
-endpoints_app.command((f"{_CLI}.endpoints.update:update"), help="Update an endpoint")
+endpoints_app.command((f"{_CLI}.endpoints.retrieve:retrieve"), help="Get endpoint details", help_epilogue="")
+endpoints_app.command((f"{_CLI}.endpoints.stop:stop"), help="Stop an endpoint", help_epilogue="")
+endpoints_app.command((f"{_CLI}.endpoints.start:start"), help="Start an endpoint", help_epilogue="")
+endpoints_app.command((f"{_CLI}.endpoints.delete:delete"), alias="-d", help="Delete an endpoint", help_epilogue="")
+endpoints_app.command((f"{_CLI}.endpoints.list:list"), alias="ls", help="List your endpoints", help_epilogue="")
 endpoints_app.command(
-    (f"{_CLI}.endpoints.availability_zones:availability_zones"), help="List availability zones for deploying models"
+    (f"{_CLI}.endpoints.update:update"), help="Update an endpoint", help_epilogue=ENDPOINTS_UPDATE_HELP_EXAMPLES
+)
+endpoints_app.command(
+    (f"{_CLI}.endpoints.availability_zones:availability_zones"),
+    help="List availability zones for deploying models",
+    help_epilogue="",
 )
 
 ## Evals API commands
@@ -435,6 +453,9 @@ async def run_command() -> None:
     (f"{_CLI}.beta.jig.jig:jig_volumes_list"), name="list", alias="ls", help="List volumes for a Jig deployment"
 )
 
+app.help_epilogue = TOP_LEVEL_HELP_EXAMPLES
+endpoints_app.help_epilogue = ENDPOINTS_HELP_EXAMPLES
+
 
 def main() -> None:
     install_completion(app)

src/together/lib/cli/api/endpoints/hardware.py

@@ -14,7 +14,9 @@
 
 async def hardware(
     model: Annotated[Optional[str], Parameter(help="Show only hardware compatible with the given model")] = None,
-    available: Annotated[bool, Parameter(help="Show only available hardware for the given model")] = False,
+    available: Annotated[
+        bool, Parameter(help="Show only available hardware for the given model", negative=False)
+    ] = False,
     *,
     config: CLIConfigParameter,
 ) -> None:

src/together/lib/cli/utils/_help_examples.py

@@ -0,0 +1,67 @@
+## Top-level commands
+
+TOP_LEVEL_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Fine tune a model for your dataset:
+  [primary]tg ft create --model Qwen/Qwen2-1.5B --training-file ./my-dataset.jsonl --lora[/primary]
+
+[dim]-[/dim] Deploy a model to a dedicated endpoint:
+  [primary]tg endpoints create --model Qwen/Qwen2.5-7B --hardware 2x_nvidia_h100_80gb_sxm --wait[/primary]
+
+[dim]-[/dim] Upload an external model to Together:
+  [primary]tg models upload --model-name my-org/my-model --model-source s3-or-hugging-face[/primary]
+"""
+
+## Endpoints API commands
+
+ENDPOINTS_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Create a new endpoint:
+  [primary]tg endpoints create --model Qwen/Qwen2.5-7B --hardware 2x_nvidia_h100_80gb_sxm --wait[/primary]
+
+[dim]-[/dim] Lookup available hardware for a model:
+  [primary]tg endpoints hardware --model Qwen/Qwen2.5-7B --available[/primary]
+
+[dim]-[/dim] List your endpoints:
+  [primary]tg endpoints list[/primary]
+
+[dim]-[/dim] Get details of an endpoint:
+  [primary]tg endpoints retrieve <endpoint-id>[/primary]
+
+[dim]-[/dim] Stop an endpoint:
+  [primary]tg endpoints stop <endpoint-id>[/primary]
+
+[dim]-[/dim] Change the autoscaling configuration for an endpoint:
+  [primary]tg endpoints update <endpoint-id> --min-replicas 4 --max-replicas 8[/primary]
+"""
+
+ENDPOINTS_HARDWARE_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] List all hardware configurations:
+  [primary]tg endpoints hardware[/primary]
+
+[dim]-[/dim] List all hardware configurations for a model:
+  [primary]tg endpoints hardware --model Qwen/Qwen2.5-7B[/primary]
+
+[dim]-[/dim] List all available hardware configurations for a model:
+  [primary]tg endpoints hardware --model Qwen/Qwen2.5-7B --available[/primary]
+
+[dim]-[/dim] Grab the cheapest hardware configuration for a model:
+  [primary]tg endpoints hardware --model meta-llama/Meta-Llama-3-8B-Instruct --available --json | jq -r 'sort_by(.pricing.cents_per_minute) | .[0].id'[/primary]
+"""
+
+ENDPOINTS_CREATE_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Deploy your model with specific autoscaling configuration:
+  [primary]tg endpoints create --model MODEL --hardware HARDWARE --min-replicas 2 --max-replicas 4[/primary]
+
+[dim]-[/dim] Deploy your fine tuned model:
+  [primary]tg endpoints create --model $(tg ft $MY_FT_JOB_ID --json | jq -r '.model_output_name') --hardware HARDWARE[/primary]
+
+[dim]-[/dim] Create an endpoint to be started later:
+  [primary]tg endpoints create --model MODEL --hardware HARDWARE --no-auto-start[/primary]
+"""
+
+ENDPOINTS_UPDATE_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Change the autoscaling configuration for an endpoint:
+  [primary]tg endpoints update ENDPOINT_ID --min-replicas 4 --max-replicas 8[/primary]
+
+[dim]-[/dim] Change the auto-stop timeout for an endpoint:
+  [primary]tg endpoints update ENDPOINT_ID --inactive-timeout 30[/primary]
+"""