SAP-Datasphere-CLI

An interactive CLI that uses the internal SAP Datasphere API to automate various tasks such as managing analytical models, remote tables, task chains and views.

Table of Contents

• Overview
• Features
• Prerequisites
• Installation
• Configuration
• Usage
• Detailed Function Overview
• Development
• Notes
• Disclaimer

Overview

This program enables the automation of recurring tasks in SAP Datasphere. It provides scripts for managing:

• Analytical Models
• Remote Tables
• Task Chains
• Views

Features

Analytical Models

• Get analytical-model dependencies and their views
• Measure analytical-model view persistence
• Measure persistence for all views of analytical models

Remote Tables

• Create statistics (Record Count, Simple Statistics, Histogram)
• Refresh existing statistics

Task Chains

• Run task chains

Views

• Find views reaching at least a minimum persistence score
• Find views with an attribute containing a specific substring
• Create partitions by year
• Remove partitions
• Lock partitions up to a specific year
• Unlock partitions
• Persist views
• Unpersist views

Prerequisites

• Python: Version 3.12 or newer
• Package Installer: uv or pipx

Installation

Quick Start

1. Install the CLI as a tool with uv:

   uv tool install datasphere-cli
   

   or with pipx:

   pipx install datasphere-cli
   

2. Run it from the terminal:

   datasphere
   

Update to the latest release with uv tool upgrade datasphere-cli / pipx upgrade datasphere-cli.

Shared Command Layer

datasphere-core is the shared, presentation-independent command layer used by the CLI and Datasphere-MCP. It contains typed commands, batch orchestration, bounded concurrency, progress handling, and shared local session handling. It can be installed without Textual or Rich:

pip install datasphere-core

Every command is a plain async function taking a CommandContext and a typed request:

from datasphere_core import CommandContext
from datasphere_core.commands.views import persist_view_batch
from datasphere_core.models.views import PersistViewBatchRequest, PersistViewRequest

result = await persist_view_batch(
    CommandContext(client=session.client),
    PersistViewBatchRequest(
        requests=(PersistViewRequest(view="V_SALES", space="DEV"),),
        max_concurrency=4,
    ),
)
print(result.summary)

See docs/datasphere-core-execution.md for the execution model, progress callbacks, and the error contract.

The full datasphere-cli package includes the TUI and uses this shared layer.

Direct Commands

Providing no arguments opens the TUI. The canonical direct task-chain command is:

datasphere task-chains run TC_TEST_DEV --space DEV
datasphere task-chains run TC_TEST_DEV --space DEV --timeout 600
datasphere task-chains run TC_TEST_DEV --space DEV --output json

The task-chain command waits for the terminal SAP status. It exits with code zero only when the run completes successfully. JSON output is written only to stdout; errors are written to stderr.

Install from Git (all platforms)

1. Clone the repository:

   git clone https://github.com/peterschwps/SAP-Datasphere-CLI.git
   cd SAP-Datasphere-CLI
   

2. Install with uv (recommended):

   uv sync --all-packages
   

3. Install the required browsers for Playwright:

   uv run playwright install chrome msedge
   

   Docs: https://playwright.dev/docs/intro.

For Developers

See Developer Setup for development dependencies, Git hooks, browser installation, and validation commands.

Configuration

The configuration is quite similar to the official SAP Datasphere CLI. In Datasphere you need to create an OAuth Client for Interactive Usage. This client will be used to authenticate and execute commands on SAP Datasphere. The full configuration of the settings file (settings.toml) is described down below.

[!IMPORTANT] Please set the Redirect URI to http://localhost:8080 when creating the OAuth Client. This is the default port that the CLI listens on to retrieve the callback code.

This is how your OAuth Client should look like:

Creating settings.toml

In order to create the settings file you need to run the CLI once. This will create a settings.toml in your user configuration directory:

• macOS: ~/Library/Application Support/Datasphere/settings.toml
• Linux: ~/.config/Datasphere/settings.toml
• Windows: %LOCALAPPDATA%\Datasphere\settings.toml

[!NOTE] Version 0.4.0 replaced the previous settings.ini with a validated settings.toml. If you are upgrading, run the CLI once and copy your values into the new file.

Configuring settings.toml

Open the settings.toml file and configure the following settings:

[setup]
# Your SAP Datasphere URL
# (System > Administration > Tenant Links: SAP Datasphere URL)
datasphere_url = "https://example.eu10.hcs.cloud.sap"

# The Authorization URL for OAuth Clients
# (System > Administration > App Integration: Authorization URL)
authorization_url = "https://example.authentication.eu10.hana.ondemand.com/oauth/authorize"

# The Token URL for OAuth Clients
# (System > Administration > App Integration: Token URL)
token_url = "https://example.authentication.eu10.hana.ondemand.com/oauth/token"

# Browser to use for the initial authentication: 'CHROME' or 'EDGE'
browser_to_use = "EDGE"

[credentials]
# OAuth Client ID of your Configured Client
# (System > Administration > App Integration: Configured Clients)
client_id = ""

# Secret of your Configured Client
# Must be provided here or with the environment variable 'SECRET'.
secret = ""

Usage

Execution

Run it from the terminal:

datasphere

First Run / Expired Tokens

On first execution (or if your refresh token has expired), the CLI will open a browser window. After logging in the site will automatically redirect to http://localhost:8080, fetch the callback code and close the browser window.

This will create a login session which can be refreshed automatically in the future.

Menu Navigation

The program starts with an interactive menu:

1. Select a category
2. Choose a function
3. Enter the required parameters
4. Optionally select the number of threads for parallel execution

Directory Structure

The datasphere/ folder is created in the directory where you run the program. It contains two workspace directories:

• datasphere/tasks/: CSV input files that specify what should be processed. Missing task templates are created with their required headers.
• datasphere/results/: CSV and JSON results written by command adapters. Existing files are preserved at startup and replaced only when a command writes its complete result.

datasphere/http.jsonl appears next to them only while the HTTP logging is switched on, see HTTP Logging.

Threading

For time-intensive tasks, threads can be used to process multiple tasks in "parallel" using asynchronous requests. This can significantly improve performance but should be used with caution to avoid triggering rate limits. A thread count of 5-10 has proven to work well.

Stopping the Program

You can stop program execution at any time by pressing Ctrl + C.

Detailed Function Overview

1. Analytical Models

{
    "results": [
        {
            "analytical_model": "Sales Analytical Model",
            "space": "SALES_DEPARTMENT",
            "status": "completed",
            "analytical_model_id": "6BB18AB407AC02FH23804E421859F129",
            "dependencies": [
                {
                    "view_id": "606E8AB407FG02FB18004E438092F770",
                    "view": "Sales2025",
                    "space": "SALES_DEPARTMENT",
                    "status": "completed"
                }
            ]
        }
    ],
    "summary": {"total": 1, "succeeded": 1, "failed": 0,
                 "skipped": 0, "timed_out": 0}
}

{
    "results": [
        {
            "analytical_model": "Sales Analytical Model",
            "space": "SALES_DEPARTMENT",
            "status": "completed",
            "analytical_model_id": "6BB18AB407AC02FH23804E421859F129",
            "dependencies": []
        }
    ],
    "summary": {"total": 1, "succeeded": 1, "failed": 0,
                 "skipped": 0, "timed_out": 0}
}

{
    "results": [
        {
            "analytical_model": "Sales Analytical Model",
            "space": "SALES_DEPARTMENT",
            "status": "completed",
            "analytical_model_id": "6BB18AB407AC02FH23804E421859F129",
            "dependencies": [
                {
                    "view_id": "606E8AB407FG02FB18004E438092F770",
                    "view": "Sales2025",
                    "space": "SALES_DEPARTMENT",
                    "status": "completed",
                    "previously_persisted": true,
                    "runtime_seconds": 78,
                    "persistence_log_status": "COMPLETED",
                    "persistence_log_id": "operation-1",
                    "cleanup_log_status": "COMPLETED",
                    "cleanup_log_id": "operation-2",
                    "persistence_removed": false,
                    "manual_intervention": false
                }
            ]
        }
    ],
    "summary": {"total": 1, "succeeded": 1, "failed": 0,
                 "skipped": 0, "timed_out": 0}
}

2. Remote Tables

3. Task Chains

task_chain,space,status,log_status,log_id,runtime_seconds
AnalyzeSales2025,SALES_DEPARTMENT,completed,COMPLETED,operation-1,1025

4. Views

source_view,source_space,view,space,business_name,score,is_persisted,status,log_id
Sales2025,SALES_DEPARTMENT,Sales2025,SALES_DEPARTMENT,Sales (2025),10,false,completed,operation-1

view,space,business_name,attribute,status
Sales2025,SALES_DEPARTMENT,Sales (2025),FISCAL_YEAR,completed
Customers,SALES_DEPARTMENT,All Customers,YEAR,completed

view,space,attribute,status
Sales2025,SALES_DEPARTMENT,FISCAL_YEAR,created
Customers,SALES_DEPARTMENT,YEAR,created

view,space,status
Sales2025,SALES_DEPARTMENT,deleted

view,space,status
Sales2025,SALES_DEPARTMENT,locked

view,space,status
Sales2025,SALES_DEPARTMENT,unlocked

view,space,status,log_status,log_id,runtime_seconds
Sales2025,SALES_DEPARTMENT,completed,COMPLETED,operation-1,37
Customers,SALES_DEPARTMENT,completed,COMPLETED,operation-2,9

view,space,status,log_status,log_id,runtime_seconds
Sales2025,SALES_DEPARTMENT,completed,COMPLETED,operation-1,37

Development

See the Contribution Guide for branch, commit, pull-request, release, and sensitive-data requirements. See Developer Setup for the toolchain, environment setup, checks, and Textual development workflow.

Logging

The program uses logging. Log files are created for each day in the .logs/ directory below the current working directory.

Every unit of work announces its start and reports its outcome, so a long run never stays silent. The level says what a line means:

• DEBUG: Diagnostics such as the raw response of a failed request. Written to the log file only, never shown.
• INFO: Announcements such as Starting task chain '...'..., skipped items and the closing Results: ... counts.
• SUCCESS: Successful outcomes, always starting with Successfully. These are the only lines shown in green.
• WARNING: The run continues, but not as intended.
• ERROR: Failed and timed out items.

HTTP Logging

The program can log every request it sends to the tenant and every response it receives. This is switched off by default and is enabled through an environment variable:

DATASPHERE_HTTP_LOGGING=1 datasphere

The requests are written to datasphere/http.jsonl, one JSON object per line. Each line is written immediately, so an interrupted run keeps everything that was logged until then. The file only contains one run, meaning the next run will replace it.

• DATASPHERE_HTTP_LOGGING: Set it to 1 to enable the logging. Every other value leaves it switched off.
• DATASPHERE_HTTP_LOGGING_FILE: Writes the file somewhere else than the workspace.

Every line carries version, sequence, timestamp, event and run_id. The events are run_started, http_request, http_response and run_finished, and a response carries the request_id of its request. A JSON body is embedded as a JSON object, so the file can be queried directly:

jq 'select(.event == "http_response" and .status_code >= 400)' datasphere/http.jsonl

Headers and bodies are written exactly as they were sent and received. Nothing is masked, because a masked value is usually the one that is needed to understand a rejected request. The file therefore contains the session tokens next to the tenant payloads. datasphere/*.jsonl is covered by .gitignore, but the file should not be shared.

Two limitations are worth knowing. A request that never receives an answer, for example after a connection error, is written without its http_response. And bodies are logged completely, so a repository search on a large tenant produces a correspondingly large line.

Notes

• Credentials: OAuth tokens are stored in the operating system credential store, separated by tenant and OAuth client ID. The client secret must be provided through settings.toml or the SECRET environment variable whenever the CLI runs.
• Session Duration: Stored refresh tokens are used to renew the session before an action starts. A browser opens only when no valid stored session is available.
• Threading: "Parallel" execution is implemented using asynchronous requests. Running tasks simultaneously can improve performance but should be used with caution to avoid triggering rate limits.
• Workspace files: Task templates are created when missing. Result files are retained at startup and replaced atomically when a command completes.
• Browser: Browser authentication uses a temporary Playwright context and a loopback-only OAuth callback.

Disclaimer

Important Note: This tool is designed for use with SAP Datasphere. Please ensure you have the necessary permissions before executing automation tasks.

Disclaimer: It is in no way affiliated with, authorized, maintained, or endorsed by SAP or any of its affiliates or subsidiaries. It is an independent and unofficial project. Use it at your own risk.