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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudos_cli
-Version: 2.82.1
+Version: 2.84.0
 Summary: Python package for interacting with CloudOS
 Home-page: https://github.com/lifebit-ai/cloudos-cli
 Author: David Piñeyro
@@ -98,6 +98,10 @@ 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)
+      - [Get Interactive Session Status](#get-interactive-session-status)
+      - [Create Interactive Session](#create-interactive-session)
     - [Datasets](#datasets)
       - [List Files](#list-files)
       - [Move Files](#move-files)
@@ -311,7 +315,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 +1978,359 @@ 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): Displays a 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`
+
+#### Get Interactive Session Status
+
+You can retrieve detailed status information for a specific interactive session using the `cloudos interactive-session status` command. This command provides comprehensive information about the session including its current state, resource allocation, costs, and more.
+
+**Basic Usage**
+
+Get the status of a session:
+
+```bash
+cloudos interactive-session status --session-id <SESSION_ID> --profile my_profile
+```
+
+The command displays session information in a formatted table:
+
+```console
+╔════════════════════╦═════════════════════════════════════════════════════╗
+║ Property           ║ Value                                               ║
+╠════════════════════╬═════════════════════════════════════════════════════╣
+║ Session ID         ║ 69bc00cb1488084e5a6cae70                            ║
+║ Name               ║ analysis-dev (linked)                               ║
+║ Status             ║ running                                             ║
+║ Backend            ║ awsJupyterNotebook                                  ║
+║ Owner              ║ John Doe                                            ║
+║ Project            ║ research                                            ║
+║ Instance Type      ║ c5.xlarge                                           ║
+║ Storage            ║ 50 GB                                               ║
+║ Cost               ║ $2.45/hour                                          ║
+║ Runtime            ║ 2h 15m 30s                                          ║
+║ Created At         ║ 2024-03-19 10:30:00 UTC                             ║
+║ Last Saved         ║ 2024-03-19 12:30:00 UTC                             ║
+║ Auto-Shutdown At   ║ 2024-03-19 18:30:00 UTC                             ║
+╚════════════════════╩═════════════════════════════════════════════════════╝
+```
+
+**Watch Mode for Provisioning Sessions**
+
+Use the `--watch` flag to continuously monitor a session's status as it provisions, with real-time status change notifications:
+
+```bash
+cloudos interactive-session status --session-id <SESSION_ID> --profile my_profile --watch
+```
+
+Watch mode automatically tracks status changes and polls until the session reaches a terminal state:
+
+```console
+Session 69bc00cb1488084e5a6cae70 currently is in initialising...
+Status changed: initialising → provisioning
+Status changed: provisioning → running
+✓ Session is now running and ready to use!
+```
+
+**Watch Mode Behavior**
+
+- **Pre-running sessions** (setup, initialising, scheduled): Watch mode will continuously poll and display status changes every 30 seconds (default)
+- **Running/stopped sessions**: Watch mode will show a warning and display the current status instead
+
+Example with a running session:
+
+```bash
+cloudos interactive-session status --session-id <SESSION_ID> --profile my_profile --watch
+```
+
+```console
+⚠ Warning: Watch mode only works for pre-running statuses (setup, initialising, scheduled). Current status: running. Showing session status instead.
+[session status table displayed]
+```
+
+**Polling Interval**
+
+Customize the polling interval for watch mode:
+
+```bash
+# Poll every 15 seconds instead of default 30
+cloudos interactive-session status --session-id <SESSION_ID> --profile my_profile --watch --watch-interval 15
+```
+
+**Watch Mode Timeout**
+
+Set a maximum time to wait for the session to reach running state. The `--max-wait-time` option accepts human-friendly duration formats:
+
+```bash
+# 30 minutes (default)
+cloudos interactive-session status --session-id <SESSION_ID> --profile my_profile --watch
+
+# 5 minutes
+cloudos interactive-session status --session-id <SESSION_ID> --profile my_profile --watch --max-wait-time 5m
+
+# 2 hours
+cloudos interactive-session status --session-id <SESSION_ID> --profile my_profile --watch --max-wait-time 2h
+
+# 1 day
+cloudos interactive-session status --session-id <SESSION_ID> --profile my_profile --watch --max-wait-time 1d
+
+# 60 seconds
+cloudos interactive-session status --session-id <SESSION_ID> --profile my_profile --watch --max-wait-time 60s
+```
+
+**Supported timeout formats:**
+- `30s` - seconds
+- `5m` - minutes
+- `2h` - hours
+- `1d` - days
+
+If the session does not reach running state within the specified timeout, the watch mode exits with a clear message:
+
+```console
+Timeout: Session did not reach running state within 30m. Current status: provisioning. Exiting watch mode.
+```
+
+**Output Formats**
+
+Save session status to a file:
+
+```bash
+# Save as JSON
+cloudos interactive-session status --session-id <SESSION_ID> --profile my_profile --output-format json --output-basename /tmp/session_status
+# Creates: /tmp/session_status.json
+
+# Save as CSV
+cloudos interactive-session status --session-id <SESSION_ID> --profile my_profile --output-format csv --output-basename /tmp/session_status
+# Creates: /tmp/session_status.csv
+```
+
+#### 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.