chore: Add usage examples for jig commands (#361)

Author: blainekasten

src/together/lib/cli/__init__.py

@@ -27,20 +27,35 @@
 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 (
+    JIG_HELP_EXAMPLES,
     EVALS_HELP_EXAMPLES,
     FILES_HELP_EXAMPLES,
     MODELS_HELP_EXAMPLES,
+    JIG_LOGS_HELP_EXAMPLES,
+    JIG_PUSH_HELP_EXAMPLES,
     ENDPOINTS_HELP_EXAMPLES,
+    JIG_BUILD_HELP_EXAMPLES,
     TOP_LEVEL_HELP_EXAMPLES,
+    JIG_DEPLOY_HELP_EXAMPLES,
+    JIG_SUBMIT_HELP_EXAMPLES,
     FINE_TUNING_HELP_EXAMPLES,
+    JIG_DESTROY_HELP_EXAMPLES,
+    JIG_SECRETS_HELP_EXAMPLES,
+    JIG_VOLUMES_HELP_EXAMPLES,
     EVALS_CREATE_HELP_EXAMPLES,
     FILES_UPLOAD_HELP_EXAMPLES,
     BETA_CLUSTERS_HELP_EXAMPLES,
     MODELS_UPLOAD_HELP_EXAMPLES,
+    JIG_JOB_STATUS_HELP_EXAMPLES,
+    JIG_SECRETS_SET_HELP_EXAMPLES,
     ENDPOINTS_CREATE_HELP_EXAMPLES,
     ENDPOINTS_UPDATE_HELP_EXAMPLES,
+    JIG_SECRETS_UNSET_HELP_EXAMPLES,
     ENDPOINTS_HARDWARE_HELP_EXAMPLES,
     FINE_TUNING_CREATE_HELP_EXAMPLES,
+    JIG_SECRETS_DELETE_HELP_EXAMPLES,
+    JIG_VOLUMES_CREATE_HELP_EXAMPLES,
+    JIG_VOLUMES_UPDATE_HELP_EXAMPLES,
     BETA_CLUSTERS_CREATE_HELP_EXAMPLES,
     BETA_CLUSTERS_UPDATE_HELP_EXAMPLES,
     FINE_TUNING_DOWNLOAD_HELP_EXAMPLES,
@@ -471,48 +486,103 @@ async def run_command() -> None:
 storage_app.command((f"{_CLI}.beta.clusters.storage.delete:delete"), help="Delete a storage volume", alias="-d")
 
 ### Jig commands
-jig_app = beta_app.command(App(name="jig", help="Build, deploy, and manage custom containers"))
+jig_app = beta_app.command(
+    App(name="jig", help="Build, deploy, and manage custom containers", help_epilogue=JIG_HELP_EXAMPLES)
+)
 jig_app.command((f"{_CLI}.beta.jig.jig:init"), help="Initialize configuration for a Jig deployment")
 jig_app.command(
     (f"{_CLI}.beta.jig.jig:dockerfile_cli"), name="dockerfile", help="Generate Dockerfile from jig configuration"
 )
-jig_app.command((f"{_CLI}.beta.jig.jig:build_cli"), name="build", help="Build container image")
-jig_app.command((f"{_CLI}.beta.jig.jig:push_cli"), name="push", help="Push image to registry")
-jig_app.command((f"{_CLI}.beta.jig.jig:deploy_cli"), name="deploy", help="Deploy model to Together")
+jig_app.command(
+    (f"{_CLI}.beta.jig.jig:build_cli"),
+    name="build",
+    help="Build container image",
+    help_epilogue=JIG_BUILD_HELP_EXAMPLES,
+)
+jig_app.command(
+    (f"{_CLI}.beta.jig.jig:push_cli"), name="push", help="Push image to registry", help_epilogue=JIG_PUSH_HELP_EXAMPLES
+)
+jig_app.command(
+    (f"{_CLI}.beta.jig.jig:deploy_cli"),
+    name="deploy",
+    help="Deploy model to Together",
+    help_epilogue=JIG_DEPLOY_HELP_EXAMPLES,
+)
 jig_app.command((f"{_CLI}.beta.jig.jig:status_cli"), name="status", help="Get deployment status")
 jig_app.command((f"{_CLI}.beta.jig.jig:endpoint_cli"), name="endpoint", help="Get deployment endpoint URL")
-jig_app.command((f"{_CLI}.beta.jig.jig:logs_cli"), name="logs", help="Get deployment logs")
-jig_app.command((f"{_CLI}.beta.jig.jig:destroy_cli"), name="destroy", help="Destroy deployment")
-jig_app.command((f"{_CLI}.beta.jig.jig:submit_cli"), name="submit", help="Submit a job to the deployment")
-jig_app.command((f"{_CLI}.beta.jig.jig:job_status_cli"), name="job-status", help="Get status of a specific job")
+jig_app.command(
+    (f"{_CLI}.beta.jig.jig:logs_cli"), name="logs", help="Get deployment logs", help_epilogue=JIG_LOGS_HELP_EXAMPLES
+)
+jig_app.command(
+    (f"{_CLI}.beta.jig.jig:destroy_cli"),
+    name="destroy",
+    help="Destroy deployment",
+    help_epilogue=JIG_DESTROY_HELP_EXAMPLES,
+)
+jig_app.command(
+    (f"{_CLI}.beta.jig.jig:submit_cli"),
+    name="submit",
+    help="Submit a job to the deployment",
+    help_epilogue=JIG_SUBMIT_HELP_EXAMPLES,
+)
+jig_app.command(
+    (f"{_CLI}.beta.jig.jig:job_status_cli"),
+    name="job-status",
+    help="Get status of a specific job",
+    help_epilogue=JIG_JOB_STATUS_HELP_EXAMPLES,
+)
 jig_app.command(
     (f"{_CLI}.beta.jig.jig:queue_status_cli"), name="queue-status", help="Get queue metrics for the deployment"
 )
 jig_app.command((f"{_CLI}.beta.jig.jig:list_deployments_cli"), name="list", alias="ls", help="List all deployments")
 
-secrets_app = jig_app.command(App(name="secrets", help="Manage deployment secrets", group="Subcommands"))
-secrets_app.command((f"{_CLI}.beta.jig.jig:secrets_set_cli"), name="set", help="Set a secret (create or update)")
-secrets_app.command((f"{_CLI}.beta.jig.jig:secrets_unset_cli"), name="unset", help="Remove a secret from local state")
+secrets_app = jig_app.command(
+    App(name="secrets", help="Manage deployment secrets", group="Subcommands", help_epilogue=JIG_SECRETS_HELP_EXAMPLES)
+)
+secrets_app.command(
+    (f"{_CLI}.beta.jig.jig:secrets_set_cli"),
+    name="set",
+    help="Set a secret (create or update)",
+    help_epilogue=JIG_SECRETS_SET_HELP_EXAMPLES,
+)
+secrets_app.command(
+    (f"{_CLI}.beta.jig.jig:secrets_unset_cli"),
+    name="unset",
+    help="Remove a secret from local state",
+    help_epilogue=JIG_SECRETS_UNSET_HELP_EXAMPLES,
+)
 secrets_app.command(
     (f"{_CLI}.beta.jig.jig:secrets_delete_cli"),
     name="delete",
     help="Delete a secret and unset it locally",
     alias="-d",
+    help_epilogue=JIG_SECRETS_DELETE_HELP_EXAMPLES,
 )
 secrets_app.command(
     (f"{_CLI}.beta.jig.jig:secrets_list_cli"), name="list", alias="ls", help="List all secrets with sync status"
 )
 
 ### Jig > volumes
-storage_app = jig_app.command(App(name="volumes", help="Manage volumes for Jig deployments", group="Subcommands"))
+storage_app = jig_app.command(
+    App(
+        name="volumes",
+        help="Manage volumes for Jig deployments",
+        group="Subcommands",
+        help_epilogue=JIG_VOLUMES_HELP_EXAMPLES,
+    )
+)
 storage_app.command(
     (f"{_CLI}.beta.jig.jig:jig_volumes_create_cli"),
     name="create",
     alias="-c",
     help="Create a new volume for a Jig deployment",
+    help_epilogue=JIG_VOLUMES_CREATE_HELP_EXAMPLES,
 )
 storage_app.command(
-    (f"{_CLI}.beta.jig.jig:jig_volumes_update_cli"), name="update", help="Update a volume and re-upload files"
+    (f"{_CLI}.beta.jig.jig:jig_volumes_update_cli"),
+    name="update",
+    help="Update a volume and re-upload files",
+    help_epilogue=JIG_VOLUMES_UPDATE_HELP_EXAMPLES,
 )
 storage_app.command((f"{_CLI}.beta.jig.jig:jig_volumes_delete_cli"), name="delete", help="Delete a volume", alias="-d")
 storage_app.command(

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

@@ -328,3 +328,140 @@
 [dim]-[/dim] Grow a volume to 4 TiB:
   [primary]tg beta clusters storage update <volume-id> --size-tib 4[/primary]
 """
+
+## Beta > Jig commands
+
+JIG_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Bootstrap config and deploy from the current directory:
+  [primary]tg beta jig init[/primary]
+  [primary]tg beta jig deploy[/primary]
+
+[dim]-[/dim] Inspect a deployment and stream logs:
+  [primary]tg beta jig status[/primary]
+  [primary]tg beta jig logs --follow[/primary]
+
+[dim]-[/dim] List deployments or tear one down:
+  [primary]tg beta jig list[/primary]
+  [primary]tg beta jig destroy[/primary]
+"""
+
+JIG_SECRETS_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Add or rotate a secret for this deployment:
+  [primary]tg beta jig secrets set HF_TOKEN "$HF_TOKEN"[/primary]
+
+[dim]-[/dim] List secrets and sync status:
+  [primary]tg beta jig secrets list[/primary]
+
+[dim]-[/dim] Remove a secret remotely and locally:
+  [primary]tg beta jig secrets delete OLD_KEY[/primary]
+"""
+
+JIG_VOLUMES_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Create a volume and upload a directory:
+  [primary]tg beta jig volumes create --name model-weights --source ./weights[/primary]
+
+[dim]-[/dim] List volumes for the deployment:
+  [primary]tg beta jig volumes list[/primary]
+
+[dim]-[/dim] Refresh volume contents from disk:
+  [primary]tg beta jig volumes update --name model-weights --source ./weights[/primary]
+"""
+
+JIG_BUILD_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Build with default tag ([primary]latest[/primary]):
+  [primary]tg beta jig build[/primary]
+
+[dim]-[/dim] Build a tagged image with warmup (torch compile cache):
+  [primary]tg beta jig build --tag v1 --warmup[/primary]
+
+[dim]-[/dim] Pass extra Docker build arguments:
+  [primary]tg beta jig build --docker-args '--no-cache'[/primary]
+"""
+
+JIG_PUSH_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Push the default ([primary]latest[/primary]) image:
+  [primary]tg beta jig push[/primary]
+
+[dim]-[/dim] Push a specific tag:
+  [primary]tg beta jig push --tag v1[/primary]
+"""
+
+JIG_DEPLOY_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Build, push, and deploy from config in the current directory:
+  [primary]tg beta jig deploy[/primary]
+
+[dim]-[/dim] Deploy using an image that is already in the registry (skip build/push):
+  [primary]tg beta jig deploy --image my-registry.example.com/my-org/my-model:abc123[/primary]
+
+[dim]-[/dim] Only build and push; do not update the deployment:
+  [primary]tg beta jig deploy --build-only[/primary]
+
+[dim]-[/dim] Start deploy and return immediately without waiting:
+  [primary]tg beta jig deploy --detach[/primary]
+"""
+
+JIG_DESTROY_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Tear down the deployment for this project ([primary]jig.toml[/primary] / [primary]pyproject.toml[/primary]):
+  [primary]tg beta jig destroy[/primary]
+"""
+
+JIG_LOGS_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Print recent logs once:
+  [primary]tg beta jig logs[/primary]
+
+[dim]-[/dim] Stream logs ([primary]Ctrl+C[/primary] to stop):
+  [primary]tg beta jig logs --follow[/primary]
+"""
+
+JIG_SUBMIT_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Submit a simple prompt job:
+  [primary]tg beta jig submit --prompt "Hello, world!"[/primary]
+
+[dim]-[/dim] Submit with a JSON payload (advanced request body):
+  [primary]tg beta jig submit --payload '{"prompt":"Explain transformers","max_tokens":256}'[/primary]
+
+[dim]-[/dim] Submit and poll until the job finishes:
+  [primary]tg beta jig submit --prompt "Summarize this README." --watch[/primary]
+"""
+
+JIG_JOB_STATUS_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Look up a job by request ID (from submit output):
+  [primary]tg beta jig job-status --request-id <request-id>[/primary]
+
+[dim]-[/dim] Machine-readable status:
+  [primary]tg beta jig job-status --request-id <request-id> --json[/primary]
+"""
+
+JIG_SECRETS_SET_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Create or update a secret from the shell:
+  [primary]tg beta jig secrets set HF_TOKEN "$HF_TOKEN"[/primary]
+
+[dim]-[/dim] Set a secret with a description (shown in listings):
+  [primary]tg beta jig secrets set API_KEY "$API_KEY" --description "Third-party API credentials"[/primary]
+"""
+
+JIG_SECRETS_UNSET_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Drop a secret from local state only (does not delete remotely):
+  [primary]tg beta jig secrets unset OLD_KEY[/primary]
+"""
+
+JIG_SECRETS_DELETE_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Delete the secret on the server and remove it locally:
+  [primary]tg beta jig secrets delete REVOKED_KEY[/primary]
+"""
+
+JIG_VOLUMES_CREATE_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Create a volume and upload files from a directory:
+  [primary]tg beta jig volumes create --name model-weights --source ./weights[/primary]
+
+[dim]-[/dim] Same using positional arguments:
+  [primary]tg beta jig volumes create model-weights ./weights[/primary]
+"""
+
+JIG_VOLUMES_UPDATE_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Upload a new directory tree as the next volume version:
+  [primary]tg beta jig volumes update --name model-weights --source ./weights[/primary]
+
+[dim]-[/dim] Positional form:
+  [primary]tg beta jig volumes update model-weights ./weights[/primary]
+"""