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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudos_cli
-Version: 2.84.0
+Version: 2.86.0
 Summary: Python package for interacting with CloudOS
 Home-page: https://github.com/lifebit-ai/cloudos-cli
 Author: David Piñeyro
@@ -100,8 +100,10 @@ Python package for interacting with CloudOS
       - [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)
+      - [Get Interactive Session Status](#get-interactive-session-status)
+      - [Pause Interactive Session](#pause-interactive-session)
+      - [Resume Interactive Session](#resume-interactive-session)
     - [Datasets](#datasets)
       - [List Files](#list-files)
       - [Move Files](#move-files)
@@ -2004,13 +2006,13 @@ The table displays sessions with pagination controls (press `n` for next page, `
 
 ```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  │
-└─────────┴──────────────┴────────────────────┴───────────────┴────────┘
+┏━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━┓
+┃ Status  ┃ Name         ┃ Type           ┃ ID            ┃ Owner  ┃
+┡━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━┩
+│ paused  │ cloudosR     │ RStudio        │ 69aee0dba197… │ Leila  │
+│ running │ analysis-dev │ Jupyter        │ 69ae972a18f0… │ John   │
+│ paused  │ test_session │ VS Code        │ 69a996c098ab… │ James  │
+└─────────┴──────────────┴────────────────┴───────────────┴────────┘
 
 Total sessions: 15
 Page: 1 of 3
@@ -2047,7 +2049,7 @@ Interactive session list saved to interactive_sessions_list.json
 You can filter sessions by status and other criteria:
 
 ```bash
-# Filter by status (setup, initialising, running, scheduled, stopped)
+# Filter by status (setup, initialising, running, scheduled, paused)
 cloudos interactive-session list --profile my_profile --filter-status running
 
 # Show only your own sessions
@@ -2071,6 +2073,172 @@ cloudos interactive-session list --profile my_profile --table-columns "status,na
 
 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/"
+```
+
+Link multiple S3 buckets:
+
+```bash
+cloudos interactive-session create \
+  --profile my_profile \
+  --name "Multi-S3 Session" \
+  --session-type jupyter \
+  --link "s3://input-bucket/data/" \
+  --link "s3://output-bucket/results/"
+```
+
+
+
+This will show progress updates like:
+
+```console
+✓ Interactive Session Created Successfully
+
+┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
+┃ Property    ┃ Value               ┃
+┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
+│ Session ID  │ 69aee0dba197abc123  │
+│ Name        │ Ready Session       │
+│ Backend     │ awsJupyterNotebook  │
+│ Status      │ initialising        │
+└─────────────┴─────────────────────┘
+```
+```
+
+**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, paused)
+
+
+
 #### 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.
@@ -2092,7 +2260,7 @@ The command displays session information in a formatted table:
 ║ Session ID         ║ 69bc00cb1488084e5a6cae70                            ║
 ║ Name               ║ analysis-dev (linked)                               ║
 ║ Status             ║ running                                             ║
-║ Backend            ║ awsJupyterNotebook                                  ║
+║ Backend            ║ Jupyter                                             ║
 ║ Owner              ║ John Doe                                            ║
 ║ Project            ║ research                                            ║
 ║ Instance Type      ║ c5.xlarge                                           ║
@@ -2125,7 +2293,7 @@ Status changed: provisioning → running
 **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
+- **Running/paused sessions**: Watch mode will show a warning and display the current status instead
 
 Example with a running session:
 
@@ -2194,142 +2362,216 @@ cloudos interactive-session status --session-id <SESSION_ID> --profile my_profil
 # Creates: /tmp/session_status.csv
 ```
 
-#### Create Interactive Session
+#### Pause 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.
+You can pause and terminate a running interactive session using the `cloudos interactive-session pause` command. This command gracefully shuts down the session and optionally saves session data before termination.
 
 **Basic Usage**
 
-Create a simple Jupyter notebook session:
+Pause a session with confirmation:
 
 ```bash
-cloudos interactive-session create \
-  --profile my_profile \
-  --name "My Analysis" \
-  --session-type jupyter
+cloudos interactive-session pause --session-id <SESSION_ID> --profile my_profile
 ```
 
-Create an RStudio session with specific R version:
+The command displays a confirmation prompt:
+
+```console
+About to pause session: 69bd11ca02326c5b3649f5c1
+Upload data before pausing: True
+Force immediate termination: False
+Continue? [y/N]: y
+
+✓ Session pause request sent successfully.
+You can monitor the session status using: cloudos interactive-session status --session-id 69bd11ca02326c5b3649f5c1
+```
+
+**Skip Confirmation Prompt**
+
+Use the `-y` or `--yes` flag to skip the confirmation prompt:
 
 ```bash
-cloudos interactive-session create \
-  --profile my_profile \
-  --name "R Analysis" \
-  --session-type rstudio \
-  --r-version 4.4.2
+cloudos interactive-session pause --session-id <SESSION_ID> --profile my_profile -y
 ```
 
-Create a VS Code session (AWS only):
+**Data Management Options**
+
+By default, session data is saved to S3 before pausing. Use `--no-upload` to skip data saving (use with caution):
 
 ```bash
-cloudos interactive-session create \
-  --profile my_profile \
-  --name "Development" \
-  --session-type vscode
+# Save session data before pausing (default)
+cloudos interactive-session pause --session-id <SESSION_ID> --profile my_profile
+
+# Skip saving data (use with caution)
+cloudos interactive-session pause --session-id <SESSION_ID> --profile my_profile --no-upload
 ```
 
-Create a Spark cluster session with custom instance types (AWS only):
+**Termination Modes**
+
+**Graceful Shutdown (default)**
+
+Allows the session to clean up resources and save data before terminating:
 
 ```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
+cloudos interactive-session pause --session-id <SESSION_ID> --profile my_profile
 ```
 
-**Configuration Options**
+**Force Immediate Termination**
 
-You can customize your session with various options:
+Bypass graceful shutdown for immediate termination (useful for stuck sessions):
 
 ```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
+cloudos interactive-session pause --session-id <SESSION_ID> --profile my_profile --force
 ```
 
-**Required for Each Session:**
-- `--name`: Session name (1-100 characters)
-- `--session-type`: Type of backend - `jupyter`, `vscode`, `rstudio`, or `spark` (platform dependent)
+Use `--force` with caution as it may not save session data properly.
 
-**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`)
+**Wait for Termination**
 
-**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.
+Use the `--wait` flag to monitor the session until it reaches a terminal state:
 
-**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)
+```bash
+cloudos interactive-session pause --session-id <SESSION_ID> --profile my_profile --wait
+```
+
+Output with `--wait`:
+
+```console
+Pausing session...
+Status: shutting_down
+Status: uploading_data
+Status: cleaning_up
+Status: paused
+✓ Session paused successfully
+```
+
+**Error Handling**
+
+The command provides helpful error messages for common issues:
+
+```console
+# Trying to pause an already paused session
+Error: Cannot pause session - the session is already paused.
+Tip: Check the session status with: cloudos interactive-session status --session-id <SESSION_ID>
+
+# Trying to pause a session that is already being paused
+Error: Cannot pause session - the session is already being paused.
+Tip: Wait a moment and check status with: cloudos interactive-session status --session-id <SESSION_ID>
+```
+
+**Examples**
+
+Basic pause with confirmation:
+
+```bash
+cloudos interactive-session pause --session-id 688351ab6be610972db54a8e --workspace-id 687fb9905c45270e09db1e9a
+```
+
+Pause without saving data and skip confirmation:
+
+```bash
+cloudos interactive-session pause --session-id 688351ab6be610972db54a8e --workspace-id 687fb9905c45270e09db1e9a --no-upload -y
+```
+
+Force pause and wait for termination:
+
+```bash
+cloudos interactive-session pause --session-id 688351ab6be610972db54a8e --workspace-id 687fb9905c45270e09db1e9a --force -y --wait
+```
+
+Pause using profile configuration:
+
+```bash
+cloudos interactive-session pause --session-id 688351ab6be610972db54a8e --profile my_profile --wait
+```
+
+Pause with verbose output:
+
+```bash
+cloudos interactive-session pause --session-id 688351ab6be610972db54a8e --profile my_profile --verbose
+```
+
+**Options Reference**
+
+The command automatically loads from profile (via `@with_profile_config` decorator):
+- **From Profile**: apikey, cloudos-url, workspace-id
+- **Command Line**: Additional options and behaviors
+
+**Required:**
+- `--session-id`: The session ID to pause (24-character hex string)
+
+**Optional Overrides from Profile:**
+- `--apikey` (optional): Override API key from profile
+- `--cloudos-url` (optional): Override CloudOS URL from profile
+- `--workspace-id` (optional): Override workspace ID from profile
+
+**Optional Behavior Flags:**
+- `--no-upload`: Don't save session data before pausing (default: saves data)
+- `--force`: Force immediate termination, skip graceful shutdown (default: graceful). **Warning:** Shows a warning message that some data may not be saved.
+- `--wait`: Wait for session to fully pause (default: return immediately after sending pause command)
+- `-y, --yes`: Skip confirmation prompt (default: show confirmation)
 - `--verbose`: Show detailed progress messages
 
+**Optional Connection:**
+- `--disable-ssl-verification`: Disable SSL certificate verification (not recommended)
+- `--ssl-cert`: Path to SSL certificate file
+- `--profile`: Profile to use from config file (default: default profile)
 
-**Data Management**
+#### Resume Interactive Session
 
-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. 
+Resume a paused interactive session with optional configuration updates. You can change instance type, storage, cost limit, auto-shutdown time, and mount additional data files or folders when resuming.
 
 
-**Data Mounting Examples**
+**Basic Usage**
 
-Mount a file from File Explorer:
+Resume a paused session:
 
 ```bash
-cloudos interactive-session create \
-  --profile my_profile \
-  --name "Data Analysis" \
-  --session-type jupyter \
-  --mount "my_project/training_data.csv"
+cloudos interactive-session resume --session-id <SESSION_ID> --profile my_profile
 ```
 
-Link an S3 bucket:
+Resume with updated instance type:
 
 ```bash
-cloudos interactive-session create \
+cloudos interactive-session resume \
+  --session-id <SESSION_ID> \
   --profile my_profile \
-  --name "S3 Access" \
-  --session-type jupyter \
-  --link "s3://my-results-bucket/output/"
+  --instance c5.2xlarge
 ```
 
+Resume with multiple updates:
 
-**Output Display**
+```bash
+cloudos interactive-session resume \
+  --session-id <SESSION_ID> \
+  --profile my_profile \
+  --instance m5.xlarge \
+  --storage 1000 \
+  --cost-limit 50.0 \
+  --shutdown-in 12h
+```
 
-The session creation output displays a success message with session details:
+**Mount Additional Data**
+
+Resume and mount additional files:
 
 ```bash
-cloudos interactive-session create \
+cloudos interactive-session resume \
+  --session-id <SESSION_ID> \
   --profile my_profile \
-  --name "My Session" \
-  --session-type jupyter
+  --mount my-project/Data/new-dataset.csv \
+  --mount s3://my-bucket/data/file.txt
 ```
 
-The output shows the session details including:
-- Session ID
-- Session name
-- Backend type (jupyter, vscode, rstudio, spark)
-- Current status (scheduled, initialising, setup, running, stopped)
 
+**Configuration Updates**
+
+All configuration parameters are optional. If not specified, the session resumes with its previous configuration.
+
+- `--instance <TYPE>` - Change instance type (validated by platform)
+- `--storage <GB>` - Update storage size (100-5000 GB)
+- `--cost-limit <USD>` - Update compute cost limit (-1 for unlimited)
+- `--shutdown-in <DURATION>` - Update auto-shutdown time (e.g., 8h, 2d)
 
 ### Datasets