chore: Add example usage for file commands (#359)

Author: blainekasten

src/together/lib/cli/__init__.py

@@ -28,17 +28,20 @@
 from together.lib.cli.utils._completion import install_completion
 from together.lib.cli.utils._help_examples import (
     EVALS_HELP_EXAMPLES,
+    FILES_HELP_EXAMPLES,
     MODELS_HELP_EXAMPLES,
     ENDPOINTS_HELP_EXAMPLES,
     TOP_LEVEL_HELP_EXAMPLES,
     FINE_TUNING_HELP_EXAMPLES,
     EVALS_CREATE_HELP_EXAMPLES,
+    FILES_UPLOAD_HELP_EXAMPLES,
     MODELS_UPLOAD_HELP_EXAMPLES,
     ENDPOINTS_CREATE_HELP_EXAMPLES,
     ENDPOINTS_UPDATE_HELP_EXAMPLES,
     ENDPOINTS_HARDWARE_HELP_EXAMPLES,
     FINE_TUNING_CREATE_HELP_EXAMPLES,
     FINE_TUNING_DOWNLOAD_HELP_EXAMPLES,
+    FILES_RETRIEVE_CONTENT_HELP_EXAMPLES,
 )
 from together.lib.cli.utils._help_formatter import help_formatter
 from together.lib.cli.utils._preparse_tokens import preparse_tokens
@@ -308,11 +311,21 @@ async def run_command() -> None:
 _CLI = "together.lib.cli.api"
 
 ## Files API commands
-files_app = app.command(App(name="files", help="Upload and manage files"))
-files_app.command(f"{_CLI}.files.upload:upload", help="Upload a file for fine-tuning, evals, or inference")
+files_app = app.command(App(name="files", help="Upload and manage files", help_epilogue=FILES_HELP_EXAMPLES))
+files_app.command(
+    f"{_CLI}.files.upload:upload",
+    help="Upload a file for fine-tuning, evals, or inference",
+    help_epilogue=FILES_UPLOAD_HELP_EXAMPLES,
+)
 files_app.command(f"{_CLI}.files.list:list", alias="ls", help="List your files")
 files_app.command(f"{_CLI}.files.retrieve:retrieve", help="Get file details")
-files_app.command(f"{_CLI}.files.retrieve_content:retrieve_content", help="Download file contents")
+files_app.command(f"{_CLI}.files.retrieve_content:retrieve_content", help="Download file contents", show=False)
+files_app.command(
+    f"{_CLI}.files.retrieve_content:retrieve_content",
+    name="download",
+    help="Download file contents",
+    help_epilogue=FILES_RETRIEVE_CONTENT_HELP_EXAMPLES,
+)
 files_app.command(f"{_CLI}.files.delete:delete", alias="-d", help="Delete a file")
 files_app.command(f"{_CLI}.files.check:check", help="Check a local file for issues")
 

src/together/lib/cli/api/files/upload.py

@@ -19,7 +19,7 @@
 async def upload(
     file: Annotated[Path, Parameter(required=True, help="The file to upload")],
     purpose: Annotated[Optional[FilePurpose], Parameter(help="The purpose of the file")] = "fine-tune",
-    check: Annotated[Optional[bool], Parameter(help="Whether to check the file")] = True,
+    no_check: Annotated[Optional[bool], Parameter(negative=(), help="Skip checking the file for issues")] = False,
     *,
     config: CLIConfigParameter,
 ) -> None:
@@ -28,7 +28,7 @@ async def upload(
         os.environ.setdefault("TOGETHER_DISABLE_TQDM", "true")
 
     # Manually handle check here so we can exit and provide the user good error messages
-    if check:
+    if not no_check:
         report = check_file(file)
         if report["is_check_passed"] is False:
             if config.json:

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

@@ -11,6 +11,41 @@
   [primary]tg models upload --model-name my-org/my-model --model-source s3-or-hugging-face[/primary]
 """
 
+## Files API commands
+
+FILES_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Upload a file for fine-tuning:
+  [primary]tg files upload ./my-dataset.jsonl --purpose fine-tune[/primary]
+
+[dim]-[/dim] Check a local file for issues:
+  [primary]tg files check ./my-dataset.jsonl[/primary]
+
+[dim]-[/dim] Remove a file from Together:
+  [primary]tg files delete <file-id>[/primary]
+
+[dim]-[/dim] Download a file:
+  [primary]tg files download <file-id> --output ./datasets[/primary]
+"""
+
+FILES_UPLOAD_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Upload a file for fine-tuning:
+  [primary]tg files upload ./my-dataset.jsonl --purpose fine-tune[/primary]
+
+[dim]-[/dim] Upload a file for evals:
+  [primary]tg files upload ./my-dataset.jsonl --purpose evals[/primary]
+
+[dim]-[/dim] Skip file checks:
+  [primary]tg files upload ./my-dataset.jsonl --no-check[/primary]
+"""
+
+FILES_RETRIEVE_CONTENT_HELP_EXAMPLES = """[dim]Examples:[/dim]
+[dim]-[/dim] Download a file:
+  [primary]tg files download <file-id> --output ./datasets[/primary]
+
+[dim]-[/dim] Print file contents to stdout:
+  [primary]tg files download <file-id> --stdout[/primary]
+"""
+
 ## Models API commands
 MODELS_HELP_EXAMPLES = """[dim]Examples:[/dim]
 [dim]-[/dim] List all models:

tests/cli/test_files.py

@@ -197,17 +197,3 @@ def test_upload_does_not_check_if_disabled(self, tmp_path: Path, cli_runner: Cli
         call_kw = upload_mock.call_args.kwargs
         assert call_kw["check"] is False
         assert "uploaded-id" in result.output
-
-    def test_upload_does_check_if_enabled(self, tmp_path: Path, cli_runner: CliRunner) -> None:
-        f = tmp_path / "data.jsonl"
-        f.write_text("{}\n")
-        uploaded = _file_response()
-        with patch.object(_files_upload_cli, "check_file") as check_mock, patch(
-            "together.resources.files.AsyncFilesResource.upload", new_callable=AsyncMock
-        ) as upload_mock:
-            upload_mock.return_value = uploaded
-            check_mock.return_value = {"is_check_passed": True, "message": "Checks passed"}
-            result = cli_runner.invoke(["files", "upload", str(f), "--check"])
-        assert result.exit_code == 0
-        check_mock.assert_called_once()
-        upload_mock.assert_called_once()