# deepset CLI

<a id="cli"></a>

# Module cli

The CLI for the deepset AI Platform SDK.

<a id="cli.upload"></a>

#### upload

```python
@cli_app.command()
def upload(paths: List[Path],
           api_key: Optional[str] = None,
           api_url: Optional[str] = None,
           workspace_name: str = DEFAULT_WORKSPACE_NAME,
           write_mode: WriteMode = WriteMode.KEEP,
           blocking: bool = True,
           timeout_s: Optional[int] = None,
           show_progress: bool = True,
           recursive: bool = False,
           use_type: Optional[List[str]] = None,
           enable_parallel_processing: bool = False,
           safe_mode: bool = False) -> None
```

Upload a folder to deepset AI Platform.

**Arguments**:

- `paths`: Path to the folder to upload. If the folder contains unsupported file types, they're skipped.
deepset supports CSV, DOCX, HTML, JSON, MD, TXT, PDF, PPTX, XLSX, XML.
- `api_key`: deepset API key to use for authentication.
- `api_url`: API URL to use for authentication.
- `workspace_name`: Name of the workspace to upload the files to. It uses the workspace from the .ENV file by default.
- `write_mode`: Specifies what to do when a file with the same name already exists in the workspace.
Possible options are:
KEEP - uploads the file with the same name and keeps both files in the workspace.
OVERWRITE - overwrites the file that is in the workspace.
FAIL - fails to upload the file with the same name.
- `blocking`: Whether to wait for the files to be uploaded and displayed in deepset AI Platform.
- `timeout_s`: Timeout in seconds for the `blocking` parameter.
- `show_progress`: Shows the upload progress.
- `recursive`: Uploads files from subfolders as well.
- `use_type`: A comma-separated string of allowed file types to upload.
- `enable_parallel_processing`: If `True`, deepset AI Platform ingests the files in parallel.
Use this to speed up the upload process. Make sure you are not running concurrent uploads for the same files.
- `safe_mode`: If `True`, disables ingesting files in parallel.

<a id="cli.download"></a>

#### download

```python
@cli_app.command()
def download(workspace_name: str = DEFAULT_WORKSPACE_NAME,
             file_dir: Optional[str] = None,
             name: Optional[str] = None,
             odata_filter: Optional[str] = None,
             include_meta: bool = True,
             batch_size: int = 50,
             api_key: Optional[str] = None,
             api_url: Optional[str] = None,
             show_progress: bool = True,
             safe_mode: bool = False) -> None
```

Download files from deepset AI Platform to your local machine.

**Arguments**:

- `workspace_name`: Name of the workspace to download the files from. Uses the workspace from the .ENV file by default.
- `file_dir`: Path to the folder where you want to download the files.
- `name`: Name of the file to odata_filter for.
- `odata_filter`: odata_filter to apply to the file list.
- `include_meta`: Downloads metadata of the files.
- `batch_size`: Batch size for file listing.
- `api_key`: API key to use for authentication.
- `api_url`: API URL to use for authentication.
- `show_progress`: Shows the upload progress.
- `safe_mode`: If `True`, disables ingesting files in parallel.

<a id="cli.login"></a>

#### login

```python
@cli_app.command()
def login() -> None
```

Log in to deepset AI Platform.

Run `deepset-cloud login` before performing any tasks in deepset AI platform using the SDK or CLI,
unless you already created the .ENV file.

This command guides you through creating a global .env file at ~/.deepset-cloud/.env with your
deepset AI Platform `API_KEY`, `API_URL` and `DEFAULT_WORKSPACE_NAME` used for all operations.

The SDK uses a cascading configuration model with the following precedence:
1. Explicit parameters (passed via code or CLI)
2. Environment variables
3. Local .env file in project root
4. Global ~/.deepset-cloud/.env file (supplements local .env)
5. Built-in defaults

<a id="cli.logout"></a>

#### logout

```python
@cli_app.command()
def logout() -> None
```

Log out of deepset AI Platform. This command deletes the .ENV file created during login.

**Example**:

  `deepset-cloud logout`

<a id="cli.list_files"></a>

#### list\_files

```python
@cli_app.command()
def list_files(api_key: Optional[str] = None,
               api_url: Optional[str] = None,
               name: Optional[str] = None,
               odata_filter: Optional[str] = None,
               workspace_name: str = DEFAULT_WORKSPACE_NAME,
               batch_size: int = 10,
               timeout_s: Optional[int] = None) -> None
```

List files that exist in the specified deepset workspace.

**Arguments**:

- `api_key`: deepset API key to use for authentication.
- `api_url`: API URL to use for authentication.
- `workspace_name`: Name of the workspace to list the files from. Uses the workspace from the .ENV file by default.
- `name`: Name of the file to odata_filter for.
- `odata_filter`: odata_filter to apply to the file list.
- `batch_size`: Batch size to use for the file list.
- `timeout_s`: The timeout for this request, in seconds.
Example:
`deepset-cloud list-files --batch-size 10`

Example using an odata filter to show only files whose category is "news":
`deepset-cloud list-files --odata-filter 'category eq "news"'`

<a id="cli.list_upload_sessions"></a>

#### list\_upload\_sessions

```python
@cli_app.command()
def list_upload_sessions(api_key: Optional[str] = None,
                         api_url: Optional[str] = None,
                         is_expired: Optional[bool] = False,
                         workspace_name: str = DEFAULT_WORKSPACE_NAME,
                         batch_size: int = 10,
                         timeout_s: Optional[int] = None) -> None
```

List the details of all upload sessions for the specified workspace, including closed sessions.

**Arguments**:

- `api_key`: deepset API key to use for authentication.
- `api_url`: API URL to use for authentication.
- `workspace_name`: Name of the workspace to list the files from. Uses the workspace from the .ENV file by default.
- `is_expired`: Whether to list expired upload sessions.
- `batch_size`: Batch size to use for the file list.
- `timeout_s`: Timeout in seconds for the API requests.
Example:
`deepset-cloud list-upload-sessions --workspace-name default`

<a id="cli.get_upload_session"></a>

#### get\_upload\_session

```python
@cli_app.command()
def get_upload_session(session_id: UUID,
                       api_key: Optional[str] = None,
                       api_url: Optional[str] = None,
                       workspace_name: str = DEFAULT_WORKSPACE_NAME) -> None
```

Fetch an upload session from deepset AI Platform. This method is useful for checking

the status of an upload session after uploading files to deepset.

**Arguments**:

- `session_id`: ID of the upload session whose status you want to check.
- `api_key`: deepset API key to use for authentication.
- `api_url`: API URL to use for authentication.
- `workspace_name`: Name of the workspace where you upload your files. Uses the workspace from the .ENV file by default.
Example:
`deepset-cloud get-upload-session --workspace-name default`

<a id="cli.version_callback"></a>

#### version\_callback

```python
def version_callback(value: bool) -> None
```

Show the SDK version and exit.

**Arguments**:

- `value`: Value of the version option.
Example:
`deepset-cloud --version`

<a id="cli.main"></a>

#### main

```python
@cli_app.callback()
def main(_: Optional[bool] = typer.Option(
    None,
    "--version",
    callback=version_callback,
    is_eager=True,
    help="Show the SDK version and exit.")) -> None
```

The CLI for the deepset SDK.

This documentation uses Python type hints to provide information about the arguments and return values.
Typer turns these type hints into a CLI interface. To see how these arguments are used in the CLI, check the
Typer documentation: https://typer.tiangolo.com/tutorial/arguments/optional or run
`deepset-cloud <command> --help` to see the arguments for a specific command.

Boolean values are converted to `-no-<variable>` or `-<variable>` flags in the CLI. For example, to disable
the progress bar, use `--no-show-progress`.

Lists can be passed by using the same flag multiple times. For example, to scan only `.txt` and `.pdf` files,
when uploading use `--use-type .txt --use-type .pdf`.

<a id="cli.run_packaged"></a>

#### run\_packaged

```python
def run_packaged() -> None
```

Run the packaged CLI.

This is the entrypoint for the package to enable running the CLI using typer.

**Example**:

  `deepset cloud run-packaged`