[Yandex Cloud documentation](../../../index.md) > [Yandex DataSphere](../../index.md) > [Concepts](../index.md) > [DataSphere Jobs](index.md) > DataSphere CLI

# DataSphere CLI

You run DataSphere Jobs jobs using the DataSphere CLI utility.

To install DataSphere CLI, in a [Python virtual environment](https://docs.python.org/3.10/library/venv.html), run the following command:

```python
pip install datasphere
```

As soon as the installation is complete, you can view help by running this command with the `-h` flag:

```bash
datasphere -h
```

Result:

```bash
usage: datasphere [-h] [-t TOKEN] [-l {ERROR,WARNING,INFO,DEBUG}] [--log-config LOG_CONFIG] [--log-dir LOG_DIR] [--profile PROFILE] {version,changelog,project,generate-requirements} ...

positional arguments:
  {version,changelog,project,generate-requirements}
    version             Show version
    changelog           Show changelog
    generate-requirements
                        Generate requirements for specified root module(s)

options:
  -h, --help            show this help message and exit
  -t TOKEN, --token TOKEN
                        YC OAuth token, see https://yandex.cloud/en/docs/iam/concepts/authorization/oauth-token
  -l {ERROR,WARNING,INFO,DEBUG}, --log-level {ERROR,WARNING,INFO,DEBUG}
                        Logging level
  --log-config LOG_CONFIG
                        Custom logging config
  --log-dir LOG_DIR     Logs directory (temporary directory by default)
  --profile PROFILE     `yc` utility profile
```

## DataSphere CLI commands {#commands}

Use the following commands to manage jobs and the utility:

* [Running](#execute) and restoring a job session.
* [Viewing](#list) job information.
* [Canceling](#cancel) a job.
* [Setting](#set-data-ttl) job data lifetime.
* [Generating](#generate-requirements) job environment parameters.
* [Getting](#projects-list) a list of community projects.
* [Getting](#project-get) information about a project.
* [Viewing](#version) DataSphere CLI version.
* [Viewing](#changelog) DataSphere CLI changelogs.

### Running jobs {#execute}

To run the job, run the following command:

```bash
datasphere project job execute -p <project_ID> -c <configuration_file>
```

Where:

* `<project_ID>`: ID of the DataSphere project in which you are going to run the job.
* `<configuration_file>`: Path to the [job configuration file](index.md#config).

To run jobs under a service account, [authenticate](../../../cli/operations/authentication/service-account.md) in the Yandex Cloud CLI as this service account and [add](../../operations/projects/update.md) it to the DataSphere project's member list with the `datasphere.community-projects.developer` [role](../../security/index.md). If you run a job with the [Yandex Compute Cloud](../../../compute/index.md) VM, [link](../../../compute/operations/vm-connect/auth-inside-vm.md#link-sa-with-instance) the service account to it.

Running a job locks the shell session until the job completes. The job code operation [logs](#logs) will be output to the standard `stdout` output and `stderr` error streams. The job execution system logs will be written to a separate file in the user's working directory.

If the shell session is interrupted during job execution, the job will continue to run in DataSphere, but the execution logs will not be saved. To resume logging, recover the session by running the following command:

```bash
datasphere project job attach --id <job_ID>
```

You can find out the job ID in the DataSphere UI under the DataSphere Jobs tab on the project page.

Tracking and logging will resume after the job session is restored.

To [rerun](fork.md) the job, run the following command:

```bash
datasphere project job fork
```

### Viewing job information {#list}

You can view all past and current project jobs by running the following command:

```bash
datasphere project job list -p <project_ID>
```

The response will return a table with the following fields:

* Job ID.
* Name.
* Description.
* Status.
* Job start and end date (if already completed).
* Name of the user who ran the job.

To view information about a specific job, run the following command:

```bash
datasphere project job get --id <job_ID>
```

### Canceling a job {#cancel}

You can stop and cancel a job in two ways:

1. If you have a shell session running with a job in progress, click **Ctrl** + **C**.
1. If you want to stop a job that is not related with an active shell session, run the following command:

   ```bash
   datasphere project job cancel --id <job_ID>
   ```

The running job will be stopped.

### Setting job data lifetime {#set-data-ttl}

You can set the job data lifetime by running the command below:

```bash
datasphere project job set-data-ttl --id <job_ID> --days <number_of_days>
```

Where `--days` is the number of days after which the job data will be deleted (14 days by default).

### Generating job environment parameters {#generate-requirements}

To generate the environment parameters for your job, run the following command:

```bash
datasphere generate-requirements <root_module>
```

Where `<root_module>` is the job root module.

The response will return a file named `requirements.txt` with the list of environment parameters for the specified module. You can use the list in the job [configuration file](index.md#config) to explicitly specify dependencies.

### Getting a list of community projects {#project-list}

To view all the community projects, run this command:

```bash
datasphere project list -c <community_ID>
```

The response will return a table with the following fields:

* Project ID
* Project name
* Community ID

### Getting information about a project {#project-get}

To view information about a specific project, run the following command:

```bash
datasphere project get --id <project_ID>
```

The response will return a table with the following fields:

* Project ID
* Project name
* Community ID

### Viewing DataSphere CLI version {#version}

To view the current DataSphere CLI version, run this command:

```bash
datasphere version
```

{% note info %}

Each time you use DataSphere CLI, a version check is performed. If a new version is out, the utility will notify you accordingly. To avoid compatibility issues, upgrade DataSphere CLI as new versions become available.

{% endnote %}

### Viewing the DataSphere CLI changelog {#changelog}

To view the changes in the current DataSphere CLI version, run this command:

```bash
datasphere changelog
```

## Job logs {#logs}

When running a job through DataSphere CLI, the shell first notifies the user to save the logs in the user's working directory. For example:

```bash
2024-05-16 12:42:35,447 - [INFO] - logs file path: C:\Temp\datasphere\job_2024-05-16T12-42-35.427056
```

After running the job, you can find the following files in the user's working directory:

* `stdout.txt`: Standard output stream of the user program.
* `stderr.txt`: Standard error message stream.
* `system.log`: System log of the VM configuration and environment package installation.
* `log.txt`: General DataSphere CLI log which records the progress of the job.
* `docker_stats.tsv`: Log of the resources consumed by the [Docker image](../docker.md), such as utilized CPU power, read and write speeds, used RAM, and boot speed. You can also get this information by running the `docker stats` [command](https://docs.docker.com/reference/cli/docker/container/stats/).
* `gpu_stats.tsv`: Log of GPU utilization, which includes the number of cores, utilized power, and video memory.

To change the directory for storing logs, use the following command:

```bash
datasphere --log-dir <new_directory>
```

You can upload your job [results](../../operations/projects/use-job-results.md) by running this command:

```bash
datasphere project job download-files --id <job_ID>
```

#### Useful links {#see-also}

* [Running jobs in DataSphere Jobs](../../operations/projects/work-with-jobs.md)
* [Using results of completed jobs](../../operations/projects/use-job-results.md)