Add cli command to get the list of the jobs (#1088)

* Add cli command to get the list of the jobs

This provides a way to get the list of jobs from the studio.

Currently, I selected the following field as table headers. We can modify it as we want.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Fix lint

* Add limit params

* Add documentation

* Add to sidebar

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: amritghimire

docs/commands/job/ls.md

@@ -0,0 +1,84 @@
+# job ls
+
+List jobs in Studio.
+
+## Synopsis
+
+```usage
+usage: datachain job ls [-h] [-v] [-q] [--status STATUS] [--team TEAM] [--limit LIMIT]
+```
+
+## Description
+
+This command lists jobs in Studio. You can filter jobs by their status, specify a team, and limit the number of jobs returned. By default, it shows the 20 most recent jobs.
+
+
+## Options
+
+* `--status STATUS` - Status to filter jobs by
+* `--team TEAM` - Team to list jobs for (default: from config)
+* `--limit LIMIT` - Limit the number of jobs returned (default: 20)
+* `-h`, `--help` - Show the help message and exit
+* `-v`, `--verbose` - Be verbose
+* `-q`, `--quiet` - Be quiet
+
+## Status options
+
+You will be able to filter the job with following status:
+
+* `CREATED` - Job has been created but not yet scheduled
+* `SCHEDULED` - Job is scheduled to run at a future time
+* `QUEUED` - Job is in the queue waiting to be executed
+* `INIT` - Job is initializing and preparing to run
+* `RUNNING` - Job is currently executing
+* `COMPLETE` - Job has finished successfully
+* `FAILED` - Job has failed during execution
+* `CANCELING_SCHEDULED` - A scheduled job is being canceled
+* `CANCELING` - A running job is being canceled
+* `CANCELED` - Job has been canceled
+* `ACTIVE` - Job is in active state.
+* `INACTIVE` - Job is in inactive state.
+
+Note: The following statuses are considered active jobs:
+
+* `CREATED`
+* `SCHEDULED`
+* `QUEUED`
+* `INIT`
+* `RUNNING`
+* `CANCELING_SCHEDULED`
+* `CANCELING`
+
+
+## Examples
+
+1. List all jobs (default limit of 20):
+```bash
+datachain job ls
+```
+
+2. List jobs for a specific team:
+```bash
+datachain job ls --team my-team
+```
+
+3. List jobs with a specific status:
+```bash
+datachain job ls --status complete
+```
+
+4. List more jobs by increasing the limit:
+```bash
+datachain job ls --limit 50
+```
+
+5. List jobs with verbose output:
+```bash
+datachain job ls -v
+```
+
+## Notes
+
+* The default limit of 20 jobs helps manage the output size and performance
+* Jobs are typically listed in reverse chronological order (newest first)
+* Use the `--status` filter to find jobs in specific states (e.g., running, completed, failed)

mkdocs.yml

@@ -96,6 +96,7 @@ nav:
                   - run: commands/job/run.md
                   - logs: commands/job/logs.md
                   - cancel: commands/job/cancel.md
+                  - ls: commands/job/ls.md
       - 📡 Interacting with remote storage: references/remotes.md
       - 🤝 Contributing: contributing.md
 

src/datachain/cli/parser/job.py

@@ -83,6 +83,36 @@ def add_jobs_parser(subparsers, parent_parser) -> None:
         help="Python package requirements",
     )
 
+    studio_ls_help = "List jobs in Studio"
+    studio_ls_description = "List jobs in Studio."
+
+    studio_ls_parser = jobs_subparser.add_parser(
+        "ls",
+        parents=[parent_parser],
+        description=studio_ls_description,
+        help=studio_ls_help,
+        formatter_class=CustomHelpFormatter,
+    )
+
+    studio_ls_parser.add_argument(
+        "--status",
+        action="store",
+        help="Status to filter jobs by",
+    )
+
+    studio_ls_parser.add_argument(
+        "--team",
+        action="store",
+        default=None,
+        help="Team to list jobs for (default: from config)",
+    )
+    studio_ls_parser.add_argument(
+        "--limit",
+        type=int,
+        default=20,
+        help="Limit the number of jobs returned (default: 20)",
+    )
+
     studio_cancel_help = "Cancel a job in Studio"
     studio_cancel_description = "Cancel a running job in Studio."
 

src/datachain/remote/studio.py

@@ -29,7 +29,7 @@
 DatasetExportSignedUrls = Optional[list[str]]
 FileUploadData = Optional[dict[str, Any]]
 JobData = Optional[dict[str, Any]]
-
+JobListData = dict[str, Any]
 logger = logging.getLogger("datachain")
 
 DATASET_ROWS_CHUNK_SIZE = 8192
@@ -402,6 +402,17 @@ def create_job(
         }
         return self._send_request("datachain/job", data)
 
+    def get_jobs(
+        self,
+        status: Optional[str] = None,
+        limit: int = 20,
+    ) -> Response[JobListData]:
+        return self._send_request(
+            "datachain/jobs",
+            {"status": status, "limit": limit} if status else {"limit": limit},
+            method="GET",
+        )
+
     def cancel_job(
         self,
         job_id: str,

src/datachain/studio.py

@@ -3,6 +3,8 @@
 import sys
 from typing import TYPE_CHECKING, Optional
 
+import tabulate
+
 from datachain.config import Config, ConfigLevel
 from datachain.dataset import QUERY_DATASET_PREFIX
 from datachain.error import DataChainError
@@ -44,6 +46,10 @@ def process_jobs_args(args: "Namespace"):
         return cancel_job(args.id, args.team)
     if args.cmd == "logs":
         return show_job_logs(args.id, args.team)
+
+    if args.cmd == "ls":
+        return list_jobs(args.status, args.team, args.limit)
+
     raise DataChainError(f"Unknown command '{args.cmd}'.")
 
 
@@ -240,13 +246,13 @@ async def _run():
         raise DataChainError(response.message)
 
     response_data = response.data
-    if response_data:
+    if response_data and response_data.get("dataset_versions"):
         dataset_versions = response_data.get("dataset_versions", [])
         print("\n\n>>>> Dataset versions created during the job:")
         for version in dataset_versions:
             print(f"    - {version.get('dataset_name')}@v{version.get('version')}")
     else:
-        print("No dataset versions created during the job.")
+        print("\n\nNo dataset versions created during the job.")
 
 
 def create_job(
@@ -337,6 +343,31 @@ def cancel_job(job_id: str, team_name: Optional[str]):
     print(f"Job {job_id} canceled")
 
 
+def list_jobs(status: Optional[str], team_name: Optional[str], limit: int):
+    client = StudioClient(team=team_name)
+    response = client.get_jobs(status, limit)
+    if not response.ok:
+        raise DataChainError(response.message)
+
+    jobs = response.data.get("jobs", [])
+    if not jobs:
+        print("No jobs found")
+        return
+
+    rows = [
+        {
+            "ID": job.get("id"),
+            "Name": job.get("name"),
+            "Status": job.get("status"),
+            "Created at": job.get("created_at"),
+            "Created by": job.get("created_by"),
+        }
+        for job in jobs
+    ]
+
+    print(tabulate.tabulate(rows, headers="keys", tablefmt="grid"))
+
+
 def show_job_logs(job_id: str, team_name: Optional[str]):
     token = Config().read().get("studio", {}).get("token")
     if not token: