cloudos-cli 2.82.1__tar.gz → 2.83.0__tar.gz

{cloudos_cli-2.82.1 → cloudos_cli-2.83.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudos_cli
-Version: 2.82.1
+Version: 2.83.0
 Summary: Python package for interacting with CloudOS
 Home-page: https://github.com/lifebit-ai/cloudos-cli
 Author: David Piñeyro
@@ -98,6 +98,9 @@ Python package for interacting with CloudOS
           - [Custom Script Path](#custom-script-path)
           - [Custom Script Project](#custom-script-project)
       - [Use multiple projects for files in `--parameter` option](#use-multiple-projects-for-files-in---parameter-option)
+    - [Interactive Sessions](#interactive-sessions)
+      - [List Interactive Sessions](#list-interactive-sessions)
+      - [Create Interactive Session](#create-interactive-session)
     - [Datasets](#datasets)
       - [List Files](#list-files)
       - [Move Files](#move-files)
@@ -311,7 +314,14 @@ To generate a named profile, use the following command:
 cloudos configure --profile {profile-name}
 ```
 
-The same prompts will appear. If a profile with the same name already exists, the current parameters will appear in square brackets and can be overwritten or left unchanged by pressing Enter/Return.
+The same prompts will appear, including the execution platform (aws or azure). If a profile with the same name already exists, the current parameters will appear in square brackets and can be overwritten or left unchanged by pressing Enter/Return.
+
+When configuring a profile, you can specify:
+- **API Key**: Your CloudOS API credentials
+- **CloudOS URL**: The CloudOS instance URL  
+- **Project Name**: Default project for commands
+- **Execution Platform**: `aws` (default) or `azure` - determines default instance types and available features
+- **Repository Platform**: Version control system (github, gitlab, etc.)
 
 > [!NOTE]
 > When there is already at least 1 previous profile defined, a new question will appear asking to make the current profile as default
@@ -1967,6 +1977,237 @@ will take all `csv` file extensions in the specified folder.
 
 ---
 
+
+
+### Interactive Sessions
+
+Interactive sessions allow you to work within the platform using different virtual environments (Jupyter Notebooks, RStudio, VS Code, etc.). You can list, monitor, and manage your interactive sessions using the CLI.
+
+#### List Interactive Sessions
+
+You can get a list of all interactive sessions in your workspace by running `cloudos interactive-session list`. The command can produce three different output formats that can be selected using the `--output-format` option:
+
+- **stdout** (default): Displaysa  table directly in the terminal with interactive pagination 
+- **csv**: Saves session data to a CSV file with a minimum predefined set of columns by default, or all available columns using the `--all-fields` parameter
+- **json**: Saves complete session information to a JSON file with all available fields
+
+To display the list of interactive sessions as a formatted table in the terminal:
+
+```bash
+cloudos interactive-session list --profile my_profile
+# or explicitly:
+cloudos interactive-session list --profile my_profile --output-format stdout
+```
+
+The table displays sessions with pagination controls (press `n` for next page, `p` for previous page, or `q` to quit):
+
+```console
+                          Interactive Sessions                          
+┏━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━┓
+┃ Status  ┃ Name         ┃ Type               ┃ ID            ┃ Owner  ┃
+┡━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━┩
+│ stopped │ cloudosR     │ awsRstudio         │ 69aee0dba197… │ Leila  │
+│ running │ analysis-dev │ awsJupyterNotebook │ 69ae972a18f0… │ John   │
+│ stopped │ test_session │ awsVSCode          │ 69a996c098ab… │ James  │
+└─────────┴──────────────┴────────────────────┴───────────────┴────────┘
+
+Total sessions: 15
+Page: 1 of 3
+Sessions on this page: 5
+
+n = next, p = prev, q = quit
+```
+
+To save sessions to a CSV file with all available fields:
+
+```bash
+cloudos interactive-session list --profile my_profile --output-format csv --all-fields
+```
+
+The expected output is something similar to:
+
+```console
+Interactive session list saved to interactive_sessions_list.csv
+```
+
+To save the same information in JSON format:
+
+```bash
+cloudos interactive-session list --profile my_profile --output-format json
+```
+
+```console
+Interactive session list collected with a total of 15 sessions.
+Interactive session list saved to interactive_sessions_list.json
+```
+
+**Filtering Options**
+
+You can filter sessions by status and other criteria:
+
+```bash
+# Filter by status (setup, initialising, running, scheduled, stopped)
+cloudos interactive-session list --profile my_profile --filter-status running
+
+# Show only your own sessions
+cloudos interactive-session list --profile my_profile --filter-only-mine
+
+# Include archived sessions
+cloudos interactive-session list --profile my_profile --archived
+
+# Custom pagination
+cloudos interactive-session list --profile my_profile --limit 20 --page 2
+```
+
+**Table Columns**
+
+You can customize which columns to display:
+
+```bash
+# Display specific columns
+cloudos interactive-session list --profile my_profile --table-columns "status,name,owner,project,created_at,cost"
+```
+
+Available columns: `backend`, `cost`, `cost_limit`, `created_at`, `id`, `instance`, `name`, `owner`, `project`, `resources`, `runtime`, `saved_at`, `spot`, `status`, `time_left`, `type`, `version`
+
+
+#### Create Interactive Session
+
+You can create and start a new interactive session using the `cloudos interactive-session create` command. This command provisions a new virtual environment with your specified configuration.
+
+The command automatically loads API credentials and workspace information from your profile configuration, so you only need to specify the session-specific details.
+
+**Basic Usage**
+
+Create a simple Jupyter notebook session:
+
+```bash
+cloudos interactive-session create \
+  --profile my_profile \
+  --name "My Analysis" \
+  --session-type jupyter
+```
+
+Create an RStudio session with specific R version:
+
+```bash
+cloudos interactive-session create \
+  --profile my_profile \
+  --name "R Analysis" \
+  --session-type rstudio \
+  --r-version 4.4.2
+```
+
+Create a VS Code session (AWS only):
+
+```bash
+cloudos interactive-session create \
+  --profile my_profile \
+  --name "Development" \
+  --session-type vscode
+```
+
+Create a Spark cluster session with custom instance types (AWS only):
+
+```bash
+cloudos interactive-session create \
+  --profile my_profile \
+  --name "Spark Analysis" \
+  --session-type spark \
+  --spark-master c5.2xlarge \
+  --spark-core c5.xlarge \
+  --spark-workers 3
+```
+
+**Configuration Options**
+
+You can customize your session with various options:
+
+```bash
+cloudos interactive-session create \
+  --profile my_profile \
+  --name "Advanced Session" \
+  --session-type jupyter \
+  --instance c5.2xlarge \
+  --storage 1000 \
+  --spot \
+  --shared \
+  --cost-limit 50.0 \
+  --shutdown-in 8h
+```
+
+**Required for Each Session:**
+- `--name`: Session name (1-100 characters)
+- `--session-type`: Type of backend - `jupyter`, `vscode`, `rstudio`, or `spark` (platform dependent)
+
+**Optional Configuration:**
+- `--instance`: Instance type (default depends on execution platform: `c5.xlarge` for AWS, `Standard_F1s` for Azure)
+- `--storage`: Storage in GB (default: 500, range: 100-5000)
+- `--spot`: Use spot instances (AWS only, cost-saving)
+- `--shared`: Make session accessible to workspace members
+- `--cost-limit`: Compute cost limit in USD (default: -1 for unlimited)
+- `--shutdown-in`: Auto-shutdown duration (e.g., `8h`, `2d`, `30m`)
+
+**Data & Storage Management:**
+- `--mount`: Mount a data file into the session. Supports both CloudOS datasets and S3 files (AWS only). Format: `project_name/dataset_path` (e.g., `leila-test/Data/file.csv`) or `s3://bucket/path/to/file` (e.g., `s3://my-bucket/data/file.csv`). Can be used multiple times.
+- `--link`: Link a folder into the session for read/write access (AWS only). Supports S3 folders and CloudOS folders. Format: `s3://bucket/prefix` (e.g., `s3://my-bucket/data/`) or `project_name/folder_path` (e.g., `leila-test/AnalysesResults/analysis_id/results`). Can be used multiple times. **Note:** Linking is not supported on Azure. Use CloudOS file explorer for data access.
+
+**Backend-Specific:**
+- `--r-version`: R version for RStudio (options: `4.4.2`, `4.5.2`) - **optional for rstudio** (default: `4.4.2`)
+- `--spark-master`: Master instance type for Spark (default: `c5.2xlarge`)
+- `--spark-core`: Core instance type for Spark (default: `c5.xlarge`)
+- `--spark-workers`: Initial worker count for Spark (default: 1)
+- `--verbose`: Show detailed progress messages
+
+
+**Data Management**
+
+CloudOS CLI supports multiple ways to access data in interactive sessions, depending on your execution platform:
+- you can load data directly into the session (i.e. files are copied into the session's mounted-data volume)
+- you can link folders to your session  (i.e the folders are sym-linked to the session). This works only for folders (S3-based) and only in AWS enviornments. 
+
+
+**Data Mounting Examples**
+
+Mount a file from File Explorer:
+
+```bash
+cloudos interactive-session create \
+  --profile my_profile \
+  --name "Data Analysis" \
+  --session-type jupyter \
+  --mount "my_project/training_data.csv"
+```
+
+Link an S3 bucket:
+
+```bash
+cloudos interactive-session create \
+  --profile my_profile \
+  --name "S3 Access" \
+  --session-type jupyter \
+  --link "s3://my-results-bucket/output/"
+```
+
+
+**Output Display**
+
+The session creation output displays a success message with session details:
+
+```bash
+cloudos interactive-session create \
+  --profile my_profile \
+  --name "My Session" \
+  --session-type jupyter
+```
+
+The output shows the session details including:
+- Session ID
+- Session name
+- Backend type (jupyter, vscode, rstudio, spark)
+- Current status (scheduled, initialising, setup, running, stopped)
+
+
 ### Datasets
 
 Manage files and folders within your CloudOS File Explorer programmatically. These commands provide comprehensive file management capabilities for organizing research data and results.

{cloudos_cli-2.82.1 → cloudos_cli-2.83.0}/README.md

@@ -63,6 +63,9 @@ Python package for interacting with CloudOS
           - [Custom Script Path](#custom-script-path)
           - [Custom Script Project](#custom-script-project)
       - [Use multiple projects for files in `--parameter` option](#use-multiple-projects-for-files-in---parameter-option)
+    - [Interactive Sessions](#interactive-sessions)
+      - [List Interactive Sessions](#list-interactive-sessions)
+      - [Create Interactive Session](#create-interactive-session)
     - [Datasets](#datasets)
       - [List Files](#list-files)
       - [Move Files](#move-files)
@@ -276,7 +279,14 @@ To generate a named profile, use the following command:
 cloudos configure --profile {profile-name}
 ```
 
-The same prompts will appear. If a profile with the same name already exists, the current parameters will appear in square brackets and can be overwritten or left unchanged by pressing Enter/Return.
+The same prompts will appear, including the execution platform (aws or azure). If a profile with the same name already exists, the current parameters will appear in square brackets and can be overwritten or left unchanged by pressing Enter/Return.
+
+When configuring a profile, you can specify:
+- **API Key**: Your CloudOS API credentials
+- **CloudOS URL**: The CloudOS instance URL  
+- **Project Name**: Default project for commands
+- **Execution Platform**: `aws` (default) or `azure` - determines default instance types and available features
+- **Repository Platform**: Version control system (github, gitlab, etc.)
 
 > [!NOTE]
 > When there is already at least 1 previous profile defined, a new question will appear asking to make the current profile as default
@@ -1932,6 +1942,237 @@ will take all `csv` file extensions in the specified folder.
 
 ---
 
+
+
+### Interactive Sessions
+
+Interactive sessions allow you to work within the platform using different virtual environments (Jupyter Notebooks, RStudio, VS Code, etc.). You can list, monitor, and manage your interactive sessions using the CLI.
+
+#### List Interactive Sessions
+
+You can get a list of all interactive sessions in your workspace by running `cloudos interactive-session list`. The command can produce three different output formats that can be selected using the `--output-format` option:
+
+- **stdout** (default): Displaysa  table directly in the terminal with interactive pagination 
+- **csv**: Saves session data to a CSV file with a minimum predefined set of columns by default, or all available columns using the `--all-fields` parameter
+- **json**: Saves complete session information to a JSON file with all available fields
+
+To display the list of interactive sessions as a formatted table in the terminal:
+
+```bash
+cloudos interactive-session list --profile my_profile
+# or explicitly:
+cloudos interactive-session list --profile my_profile --output-format stdout
+```
+
+The table displays sessions with pagination controls (press `n` for next page, `p` for previous page, or `q` to quit):
+
+```console
+                          Interactive Sessions                          
+┏━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━┓
+┃ Status  ┃ Name         ┃ Type               ┃ ID            ┃ Owner  ┃
+┡━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━┩
+│ stopped │ cloudosR     │ awsRstudio         │ 69aee0dba197… │ Leila  │
+│ running │ analysis-dev │ awsJupyterNotebook │ 69ae972a18f0… │ John   │
+│ stopped │ test_session │ awsVSCode          │ 69a996c098ab… │ James  │
+└─────────┴──────────────┴────────────────────┴───────────────┴────────┘
+
+Total sessions: 15
+Page: 1 of 3
+Sessions on this page: 5
+
+n = next, p = prev, q = quit
+```
+
+To save sessions to a CSV file with all available fields:
+
+```bash
+cloudos interactive-session list --profile my_profile --output-format csv --all-fields
+```
+
+The expected output is something similar to:
+
+```console
+Interactive session list saved to interactive_sessions_list.csv
+```
+
+To save the same information in JSON format:
+
+```bash
+cloudos interactive-session list --profile my_profile --output-format json
+```
+
+```console
+Interactive session list collected with a total of 15 sessions.
+Interactive session list saved to interactive_sessions_list.json
+```
+
+**Filtering Options**
+
+You can filter sessions by status and other criteria:
+
+```bash
+# Filter by status (setup, initialising, running, scheduled, stopped)
+cloudos interactive-session list --profile my_profile --filter-status running
+
+# Show only your own sessions
+cloudos interactive-session list --profile my_profile --filter-only-mine
+
+# Include archived sessions
+cloudos interactive-session list --profile my_profile --archived
+
+# Custom pagination
+cloudos interactive-session list --profile my_profile --limit 20 --page 2
+```
+
+**Table Columns**
+
+You can customize which columns to display:
+
+```bash
+# Display specific columns
+cloudos interactive-session list --profile my_profile --table-columns "status,name,owner,project,created_at,cost"
+```
+
+Available columns: `backend`, `cost`, `cost_limit`, `created_at`, `id`, `instance`, `name`, `owner`, `project`, `resources`, `runtime`, `saved_at`, `spot`, `status`, `time_left`, `type`, `version`
+
+
+#### Create Interactive Session
+
+You can create and start a new interactive session using the `cloudos interactive-session create` command. This command provisions a new virtual environment with your specified configuration.
+
+The command automatically loads API credentials and workspace information from your profile configuration, so you only need to specify the session-specific details.
+
+**Basic Usage**
+
+Create a simple Jupyter notebook session:
+
+```bash
+cloudos interactive-session create \
+  --profile my_profile \
+  --name "My Analysis" \
+  --session-type jupyter
+```
+
+Create an RStudio session with specific R version:
+
+```bash
+cloudos interactive-session create \
+  --profile my_profile \
+  --name "R Analysis" \
+  --session-type rstudio \
+  --r-version 4.4.2
+```
+
+Create a VS Code session (AWS only):
+
+```bash
+cloudos interactive-session create \
+  --profile my_profile \
+  --name "Development" \
+  --session-type vscode
+```
+
+Create a Spark cluster session with custom instance types (AWS only):
+
+```bash
+cloudos interactive-session create \
+  --profile my_profile \
+  --name "Spark Analysis" \
+  --session-type spark \
+  --spark-master c5.2xlarge \
+  --spark-core c5.xlarge \
+  --spark-workers 3
+```
+
+**Configuration Options**
+
+You can customize your session with various options:
+
+```bash
+cloudos interactive-session create \
+  --profile my_profile \
+  --name "Advanced Session" \
+  --session-type jupyter \
+  --instance c5.2xlarge \
+  --storage 1000 \
+  --spot \
+  --shared \
+  --cost-limit 50.0 \
+  --shutdown-in 8h
+```
+
+**Required for Each Session:**
+- `--name`: Session name (1-100 characters)
+- `--session-type`: Type of backend - `jupyter`, `vscode`, `rstudio`, or `spark` (platform dependent)
+
+**Optional Configuration:**
+- `--instance`: Instance type (default depends on execution platform: `c5.xlarge` for AWS, `Standard_F1s` for Azure)
+- `--storage`: Storage in GB (default: 500, range: 100-5000)
+- `--spot`: Use spot instances (AWS only, cost-saving)
+- `--shared`: Make session accessible to workspace members
+- `--cost-limit`: Compute cost limit in USD (default: -1 for unlimited)
+- `--shutdown-in`: Auto-shutdown duration (e.g., `8h`, `2d`, `30m`)
+
+**Data & Storage Management:**
+- `--mount`: Mount a data file into the session. Supports both CloudOS datasets and S3 files (AWS only). Format: `project_name/dataset_path` (e.g., `leila-test/Data/file.csv`) or `s3://bucket/path/to/file` (e.g., `s3://my-bucket/data/file.csv`). Can be used multiple times.
+- `--link`: Link a folder into the session for read/write access (AWS only). Supports S3 folders and CloudOS folders. Format: `s3://bucket/prefix` (e.g., `s3://my-bucket/data/`) or `project_name/folder_path` (e.g., `leila-test/AnalysesResults/analysis_id/results`). Can be used multiple times. **Note:** Linking is not supported on Azure. Use CloudOS file explorer for data access.
+
+**Backend-Specific:**
+- `--r-version`: R version for RStudio (options: `4.4.2`, `4.5.2`) - **optional for rstudio** (default: `4.4.2`)
+- `--spark-master`: Master instance type for Spark (default: `c5.2xlarge`)
+- `--spark-core`: Core instance type for Spark (default: `c5.xlarge`)
+- `--spark-workers`: Initial worker count for Spark (default: 1)
+- `--verbose`: Show detailed progress messages
+
+
+**Data Management**
+
+CloudOS CLI supports multiple ways to access data in interactive sessions, depending on your execution platform:
+- you can load data directly into the session (i.e. files are copied into the session's mounted-data volume)
+- you can link folders to your session  (i.e the folders are sym-linked to the session). This works only for folders (S3-based) and only in AWS enviornments. 
+
+
+**Data Mounting Examples**
+
+Mount a file from File Explorer:
+
+```bash
+cloudos interactive-session create \
+  --profile my_profile \
+  --name "Data Analysis" \
+  --session-type jupyter \
+  --mount "my_project/training_data.csv"
+```
+
+Link an S3 bucket:
+
+```bash
+cloudos interactive-session create \
+  --profile my_profile \
+  --name "S3 Access" \
+  --session-type jupyter \
+  --link "s3://my-results-bucket/output/"
+```
+
+
+**Output Display**
+
+The session creation output displays a success message with session details:
+
+```bash
+cloudos interactive-session create \
+  --profile my_profile \
+  --name "My Session" \
+  --session-type jupyter
+```
+
+The output shows the session details including:
+- Session ID
+- Session name
+- Backend type (jupyter, vscode, rstudio, spark)
+- Current status (scheduled, initialising, setup, running, stopped)
+
+
 ### Datasets
 
 Manage files and folders within your CloudOS File Explorer programmatically. These commands provide comprehensive file management capabilities for organizing research data and results.

{cloudos_cli-2.82.1 → cloudos_cli-2.83.0}/cloudos_cli/__init__.py

@@ -8,4 +8,4 @@ Python package for interacting with Cloud OS (https://cloudos.lifebit.ai/)
 from .clos import Cloudos
 from ._version import __version__
 
-__all__ = ['jobs', 'utils', 'clos', 'queue', 'configure', 'datasets', 'import_wf']
+__all__ = ['jobs', 'utils', 'clos', 'queue', 'configure', 'datasets', 'import_wf', 'interactive_session']

{cloudos_cli-2.82.1 → cloudos_cli-2.83.0}/cloudos_cli/__main__.py

@@ -25,6 +25,7 @@ from cloudos_cli.procurement.cli import procurement
 from cloudos_cli.datasets.cli import datasets
 from cloudos_cli.configure.cli import configure
 from cloudos_cli.link.cli import link
+from cloudos_cli.interactive_session.cli import interactive_session
 
 
 # Install the custom exception handler
@@ -63,6 +64,7 @@ run_cloudos_cli.add_command(procurement)
 run_cloudos_cli.add_command(datasets)
 run_cloudos_cli.add_command(configure)
 run_cloudos_cli.add_command(link)
+run_cloudos_cli.add_command(interactive_session)
 
 if __name__ == '__main__':
     run_cloudos_cli()

cloudos_cli-2.83.0/cloudos_cli/_version.py

@@ -0,0 +1 @@
+__version__ = '2.83.0'