cloudos_cli.interactive_session.interactive_session

Interactive session helper functions for CloudOS.

Functions

build_app_filtered_page_fetcher(cl, ...)	Return a page-fetch callback that strips app-type sessions from each page.
build_resume_payload([instance_type, ...])	Build the resume session payload for the API.
build_session_payload(name, backend, project_id)	Build the complex session creation payload for the API.
confirm_session_stop(session_data[, ...])	Display session termination confirmation details.
create_interactive_session_list_table(sessions)	Create a rich table displaying interactive sessions with interactive pagination.
export_session_status_csv(session_data[, ...])	Export session status as CSV.
export_session_status_json(session_data[, ...])	Export session status as JSON.
fetch_interactive_session_page(cl, ...)	Helper function to fetch a specific page of interactive sessions.
format_cost([cost_value])	Format cost as currency.
format_duration(seconds)	Convert seconds to human-readable format.
format_instance_type(instance_type[, ...])	Format instance type with spot indicator.
format_session_creation_table(session_data)	Display session creation result in table format.
format_session_status_table(session_data[, ...])	Wrapper function to display session status as a rich table.
format_stop_success_output(session_data[, wait])	Display successful session stop output.
format_timestamp([iso_timestamp])	Convert ISO8601 timestamp to readable format.
format_volume_sizes(volume_sizes)	Format a volume split for display, e.g. 'Libraries: 50 GB, Session results: 225 GB, ...'.
get_interactive_session_status(cloudos_url, ...)	Wrapper function to fetch session status from API.
get_response_volume_sizes(session_data)	Return the volumeSizes dict from a session API response, or None if absent.
map_status(api_status)	Map API status value to user-friendly display status.
parse_data_file(data_file_str)	Parse data file format: either S3 or Lifebit Platform dataset path.
parse_link_path(link_path_str)	Parse link path format: supports S3, Lifebit Platform, or legacy colon format.
parse_shutdown_duration(duration_str)	Parse shutdown duration string to ISO8601 datetime string.
parse_watch_timeout_duration(duration_str)	Parse watch timeout duration string to seconds.
poll_session_termination(cloudos_url, ...[, ...])	Poll session status until it reaches a terminal state.
process_interactive_session_list(sessions[, ...])	Process interactive sessions data into a pandas DataFrame.
resolve_volume_sizes([storage_size, ...])	Work out the storage size and its split into the three session volumes.
save_interactive_session_list_to_csv(df, outfile)	Save interactive session list to CSV file.
transform_session_response(api_response)	Transform raw API response to user-friendly display format.
validate_instance_type(instance_type[, ...])	Validate instance type format for the given execution platform.
validate_session_id(session_id)	Validate session ID format (24-character hex string).
validate_volume_sizes(storage_size, volume_sizes)	Check that a volume split is valid for the given storage size.
volume_size_rows(volume_sizes)	Return (label, value) table rows for each volume, drawn as a tree under Storage.

Classes

InteractiveSessionAPI(cloudos_url, apikey[, ...])	API client for interactive session operations.
OutputFormatter()	Handles formatting output in different formats.
WatchModeManager(api_client, session_id, team_id)	Manages watch mode polling and display.

class cloudos_cli.interactive_session.interactive_session.InteractiveSessionAPI(cloudos_url, apikey, verify_ssl=True)

Bases: object

API client for interactive session operations.

Parameters:

• cloudos_url (str)

• apikey (str)

• verify_ssl (bool)

REQUEST_TIMEOUT = 30

get_session_status(session_id, team_id)

Retrieve session status from API endpoint.

GET /api/v2/interactive-sessions/{sessionId}?teamId={teamId}

Parameters:

• session_id (str) – Session ID (24-character hex)

• team_id (str) – Team/workspace ID

Returns:

Session status response

Return type:

dict

Raises:

• PermissionError – If authentication fails (401, 403)

• ValueError – If session not found (404)

• RuntimeError – For other API errors

class cloudos_cli.interactive_session.interactive_session.OutputFormatter

Bases: object

Handles formatting output in different formats.

static format_csv(session_data)

Export as CSV with key fields.

Parameters:

session_data (dict)

Return type:

str

static format_json(raw_response)

Return raw API response as formatted JSON.

Parameters:

raw_response (dict)

Return type:

str

static format_stdout(session_data, cloudos_url)

Display session status as a rich table with color coding.

Parameters:

• session_data (dict)

• cloudos_url (str)

Return type:

None

class cloudos_cli.interactive_session.interactive_session.WatchModeManager(api_client, session_id, team_id, interval=10)

Bases: object

Manages watch mode polling and display.

Parameters:

• api_client (InteractiveSessionAPI)

• session_id (str)

• team_id (str)

• interval (int)

get_elapsed_time()

Get formatted elapsed time.

Return type:

str

watch(verbose=False)

Continuously poll session status until reaching terminal state.

Terminal states: running, paused, terminated

Handles Ctrl+C gracefully.

Parameters:

verbose (bool)

Return type:

dict

cloudos_cli.interactive_session.interactive_session.build_app_filtered_page_fetcher(cl, workspace_id, limit, filter_status, filter_only_mine, archived, verify_ssl)

Return a page-fetch callback that strips app-type sessions from each page.

The returned callable is intended for use as the fetch_page_callback argument of create_interactive_session_list_table(). It fetches a page via fetch_interactive_session_page() and removes any session whose interactiveSessionType belongs to APP_SESSION_TYPES before returning, ensuring app sessions never appear in the interactive table even when the user navigates to subsequent pages.

Parameters:

• cl (Cloudos) – API client instance.

• workspace_id (str) – Team/workspace identifier.

• limit (int) – Page size.

• filter_status (tuple or None) – Status values to pass to the API filter.

• filter_only_mine (bool) – Restrict results to the authenticated user’s sessions.

• archived (bool) – Include archived sessions.

• verify_ssl (bool or str) – SSL verification setting.

Returns:

A function fetch_page(page_num: int) -> dict that returns the API response dict with app sessions already removed from "sessions".

Return type:

callable

cloudos_cli.interactive_session.interactive_session.build_resume_payload(instance_type=None, storage_size=None, cost_limit=None, shutdown_at=None, volume_sizes=None)

Build the resume session payload for the API.

Only includes fields that have been specified (all are optional).

Parameters:

• instance_type (str, optional) – New instance type (if changing)

• storage_size (int, optional) – New storage size in GB (if changing)

• volume_sizes (dict, optional) – New split of the storage into ‘libraries’, ‘sessionResults’ and ‘mountedData’ (GB). Must add up to storage_size.

• cost_limit (float, optional) – New compute cost limit (if changing)

• shutdown_at (str, optional) – New auto-shutdown datetime in ISO8601 format (if changing)

Returns:

Resume payload for API request

Return type:

dict

cloudos_cli.interactive_session.interactive_session.build_session_payload(name, backend, project_id, execution_platform='aws', instance_type='c5.xlarge', storage_size=500, volume_sizes=None, is_spot=False, is_shared=False, cost_limit=-1, shutdown_at=None, data_files=None, s3_mounts=None, r_version=None, spark_master_type=None, spark_core_type=None, spark_workers=1)

Build the complex session creation payload for the API.

Parameters:

• name (str) – Session name (1-100 characters)

• backend (str) – Backend type: regular, vscode, spark, rstudio, windows, linux

• project_id (str) – Project MongoDB ObjectId

• execution_platform (str, optional) – Execution platform: ‘aws’ (default) or ‘azure’

• instance_type (str) – Instance type (EC2 for AWS, e.g., c5.xlarge; Azure VM size, e.g., Standard_D4s_v3)

• storage_size (int) – Storage in GB (default: 500, range: 500-64050)

• volume_sizes (dict, optional) – Split of the storage into ‘libraries’, ‘sessionResults’ and ‘mountedData’ (GB). Must add up to storage_size. If not given, the default split is used (see resolve_volume_sizes).

• is_spot (bool) – Use spot instances (AWS only, default: False)

• is_shared (bool) – Make session shared (default: False)

• cost_limit (float) – Compute cost limit in USD (default: -1 for unlimited)

• shutdown_at (str) – ISO8601 datetime for auto-shutdown (optional)

• data_files (list) – List of data file dicts. For AWS: Lifebit Platform or S3. For Azure: Lifebit Platform only.

• s3_mounts (list) – List of S3 mount dicts (AWS only, ignored for Azure)

• r_version (str) – R version for RStudio (required for rstudio backend)

• spark_master_type (str) – Spark master instance type (required for spark backend, AWS only)

• spark_core_type (str) – Spark core instance type (required for spark backend, AWS only)

• spark_workers (int) – Initial number of Spark workers (default: 1, AWS only)

Returns:

Complete payload for API request

Return type:

dict

cloudos_cli.interactive_session.interactive_session.confirm_session_stop(session_data, no_upload=False, force=False)

Display session termination confirmation details.

Parameters:

• session_data (dict) – Session data from API response

• no_upload (bool) – Whether data upload on close is disabled

• force (bool) – Whether force abort is enabled

Return type:

None

cloudos_cli.interactive_session.interactive_session.create_interactive_session_list_table(sessions, pagination_metadata=None, selected_columns=None, page_size=10, fetch_page_callback=None)

Create a rich table displaying interactive sessions with interactive pagination.

Parameters:

• sessions (list) – List of session objects from the API

• pagination_metadata (dict, optional) – Pagination information from the API response

• selected_columns (str or list, optional) – Comma-separated string or list of column names to display. If None, uses responsive column selection based on terminal width. Available columns: id, name, status, type, instance, cost, owner

• page_size (int, optional) – Number of sessions per page for interactive pagination. Default=10.

• fetch_page_callback (callable, optional) – Callback function to fetch a specific page of results. Should accept page number (1-indexed) and return dict with ‘sessions’ and ‘pagination_metadata’ keys.

cloudos_cli.interactive_session.interactive_session.export_session_status_csv(session_data, output_file=None)

Export session status as CSV.

Parameters:

• session_data (dict) – Transformed session data (from transform_session_response)

• output_file (str, optional) – Path to save CSV file. If None, returns CSV string.

Returns:

CSV formatted string

Return type:

str

cloudos_cli.interactive_session.interactive_session.export_session_status_json(session_data, output_file=None)

Export session status as JSON.

Parameters:

• session_data (dict) – Raw API response

• output_file (str, optional) – Path to save JSON file. If None, returns JSON string.

Returns:

JSON formatted string

Return type:

str

cloudos_cli.interactive_session.interactive_session.fetch_interactive_session_page(cl, workspace_id, page_num, limit, filter_status, filter_only_mine, archived, verify_ssl)

Helper function to fetch a specific page of interactive sessions.

Parameters:

• cl (Cloudos) – Lifebit Platform API client instance

• workspace_id (str) – Workspace ID

• page_num (int) – Page number to fetch

• limit (int) – Number of results per page

• filter_status (tuple or None) – Status filters

• filter_only_mine (bool) – Whether to filter only user’s sessions

• archived (bool) – Whether to include archived sessions

• verify_ssl (bool or str) – SSL verification setting

Returns:

API response with sessions and pagination metadata

Return type:

dict

cloudos_cli.interactive_session.interactive_session.format_cost(cost_value=None)

Format cost as currency.

Examples: “$12.50”, “$0.00”

Parameters:

cost_value (float)

Return type:

str

cloudos_cli.interactive_session.interactive_session.format_duration(seconds)

Convert seconds to human-readable format.

Examples: “2h 15m”, “45m 30s”, “30s”

Parameters:

seconds (int)

Return type:

str

cloudos_cli.interactive_session.interactive_session.format_instance_type(instance_type, is_cost_saving=False)

Format instance type with spot indicator.

Examples: “c5.xlarge”, “c5.xlarge (spot)”

Parameters:

• instance_type (str)

• is_cost_saving (bool)

Return type:

str

cloudos_cli.interactive_session.interactive_session.format_session_creation_table(session_data, instance_type=None, storage_size=None, backend_type=None, r_version=None, spark_master=None, spark_core=None, spark_workers=None, data_files=None, s3_mounts=None, shutdown_in=None, volume_sizes=None)

Display session creation result in table format.

Parameters:

• session_data (dict) – Session data from API response

• instance_type (str, optional) – Instance type that was requested (for display if not in response)

• storage_size (int, optional) – Storage size that was requested (for display if not in response)

• backend_type (str, optional) – Backend type (regular, vscode, spark, rstudio, windows, linux) for backend-specific display

• r_version (str, optional) – R version for RStudio backend

• spark_master (str, optional) – Spark master instance type

• spark_core (str, optional) – Spark core instance type

• spark_workers (int, optional) – Number of Spark workers

• data_files (list, optional) – List of parsed data file objects to display

• s3_mounts (list, optional) – List of parsed S3 mount objects to display

• shutdown_in (str, optional) – Shutdown duration value (e.g., ‘12h’, ‘2d’) that was requested

• volume_sizes (dict, optional) – Volume split that was requested (for display if not in response)

Returns:

Formatted table output

Return type:

str

cloudos_cli.interactive_session.interactive_session.format_session_status_table(session_data, cloudos_url=None)

Wrapper function to display session status as a rich table.

Parameters:

• session_data (dict) – Transformed session data (from transform_session_response)

• cloudos_url (str, optional) – Lifebit Platform URL for creating links

Return type:

None

cloudos_cli.interactive_session.interactive_session.format_stop_success_output(session_data, wait=False)

Display successful session stop output.

Parameters:

• session_data (dict) – Final session data from API response

• wait (bool) – Whether the command waited for full termination

Return type:

None

cloudos_cli.interactive_session.interactive_session.format_timestamp(iso_timestamp=None)

Convert ISO8601 timestamp to readable format.

Example: “2026-03-13 10:30:00”

Parameters:

iso_timestamp (str)

Return type:

str

cloudos_cli.interactive_session.interactive_session.format_volume_sizes(volume_sizes)

Format a volume split for display, e.g. ‘Libraries: 50 GB, Session results: 225 GB, …’.

cloudos_cli.interactive_session.interactive_session.get_interactive_session_status(cloudos_url, apikey, session_id, team_id, verify_ssl=True, verbose=False)

Wrapper function to fetch session status from API.

Parameters:

• cloudos_url (str) – Lifebit Platform URL

• apikey (str) – API key for authentication

• session_id (str) – Session ID (24-char hex)

• team_id (str) – Team/workspace ID

• verify_ssl (bool) – Whether to verify SSL certificates

• verbose (bool) – Whether to print verbose output

Returns:

Raw API response

Return type:

dict

Raises:

• ValueError – If session not found

• PermissionError – If authentication fails

• RuntimeError – For other API errors

cloudos_cli.interactive_session.interactive_session.get_response_volume_sizes(session_data)

Return the volumeSizes dict from a session API response, or None if absent.

The session endpoints return it at the top level; resources and interactiveSessionConfiguration are checked as fallbacks.

cloudos_cli.interactive_session.interactive_session.map_status(api_status)

Map API status value to user-friendly display status.

Converts API status values (like ‘ready’, ‘aborted’) to display values (like ‘running’, ‘paused’) matching the list command.

Parameters:

api_status (str)

Return type:

str

cloudos_cli.interactive_session.interactive_session.parse_data_file(data_file_str)

Parse data file format: either S3 or Lifebit Platform dataset path.

Supports mounting both S3 files and Lifebit Platform dataset files into the session.

Parameters:

data_file_str (str) –

Format: - S3 file: s3://bucket_name/path/to/file.txt - Lifebit Platform dataset: project_name/dataset_path or project_name > dataset_path

Examples: - s3://lifebit-featured-datasets/pipelines/phewas/data.csv - leila-test/Data/3_vcf_list.txt

Returns:

Parsed data item. For S3: {“type”: “s3”, “s3_bucket”: “…”, “s3_prefix”: “…”}

For Lifebit Platform dataset: {“type”: “cloudos”, “project_name”: “…”, “dataset_path”: “…”}

Return type:

dict

Raises:

ValueError – If format is invalid

cloudos_cli.interactive_session.interactive_session.parse_link_path(link_path_str)

Parse link path format: supports S3, Lifebit Platform, or legacy colon format.

Links an S3 folder or Lifebit Platform folder to the session for read/write access.

Parameters:

link_path_str (str) – Format (one of): - S3 path: s3://bucketName/s3Prefix (e.g., s3://my-bucket/data/) - Lifebit Platform folder: project/folder_path (e.g., leila-test/Data) - Legacy format (deprecated): mountName:bucketName:s3Prefix

Returns:

Tuple of (type, data) where type is ‘s3’ or ‘cloudos’ and data contains: For S3: {“s3_bucket”: “…”, “s3_prefix”: “…”} For Lifebit Platform: {“project_name”: “…”, “folder_path”: “…”}

Return type:

dict

cloudos_cli.interactive_session.interactive_session.parse_shutdown_duration(duration_str)

Parse shutdown duration string to ISO8601 datetime string.

Accepts formats: 30m, 2h, 8h, 1d, 2d

Parameters:

duration_str (str) – Duration string (e.g., “2h”, “30m”, “1d”)

Returns:

ISO8601 formatted datetime string (future time)

Return type:

str

cloudos_cli.interactive_session.interactive_session.parse_watch_timeout_duration(duration_str)

Parse watch timeout duration string to seconds.

Accepts formats: 30m, 2h, 1d, 30s

Parameters:

duration_str (str) – Duration string (e.g., “30m”, “2h”, “1d”, “30s”)

Returns:

Duration in seconds

Return type:

int

cloudos_cli.interactive_session.interactive_session.poll_session_termination(cloudos_url, apikey, session_id, team_id, max_wait=300, poll_interval=5, verify_ssl=True)

Poll session status until it reaches a terminal state.

Parameters:

• cloudos_url (str) – Lifebit Platform API URL

• apikey (str) – API key for authentication

• session_id (str) – Session ID to monitor

• team_id (str) – Team/workspace ID

• max_wait (int) – Maximum time to wait in seconds (default: 300 = 5 minutes)

• poll_interval (int) – Polling interval in seconds (default: 5)

• verify_ssl (bool) – Whether to verify SSL certificates

Returns:

Final session status response

Return type:

dict

Raises:

TimeoutError – If session doesn’t reach terminal state within max_wait

cloudos_cli.interactive_session.interactive_session.process_interactive_session_list(sessions, all_fields=False)

Process interactive sessions data into a pandas DataFrame.

Parameters:

• sessions (list) – List of session objects from the API

• all_fields (bool, default=False) – If True, include all fields from the API response. If False, include only the most relevant fields.

Returns:

df – DataFrame with session data

Return type:

pandas.DataFrame

cloudos_cli.interactive_session.interactive_session.resolve_volume_sizes(storage_size=None, libraries=None, session_results=None, mounted_data=None)

Work out the storage size and its split into the three session volumes.

Rules: - No volume given: libraries gets 50 GB and the rest is split evenly between

sessionResults and mountedData.

• One volume given: the other two split the remaining storage evenly.

• Two volumes given: the third one gets the remaining storage.

• All three given: the storage size is their sum. If storage_size is also given, it must match the sum.

When the remaining storage can’t be split evenly, the extra GB goes to sessionResults (or to mountedData if sessionResults was given).

Parameters:

• storage_size (int, optional) – Total storage in GB. Defaults to 500 unless all three volumes are given.

• libraries (int, optional) – Libraries volume in GB.

• session_results (int, optional) – Session results volume in GB.

• mounted_data (int, optional) – Mounted data volume in GB.

Returns:

(storage_size, volume_sizes) where volume_sizes is a dict keyed by ‘libraries’, ‘sessionResults’ and ‘mountedData’.

Return type:

tuple

Raises:

ValueError – If the storage size is out of range or the split is not valid.

cloudos_cli.interactive_session.interactive_session.save_interactive_session_list_to_csv(df, outfile, count=None)

Save interactive session list to CSV file.

Parameters:

• df (pandas.DataFrame) – The session data to save

• outfile (str) – Path to the output CSV file

• count (int, optional) – Total number of sessions on this page for display message

cloudos_cli.interactive_session.interactive_session.transform_session_response(api_response)

Transform raw API response to user-friendly display format.

Parameters:

api_response (dict)

Return type:

dict

cloudos_cli.interactive_session.interactive_session.validate_instance_type(instance_type, execution_platform='aws')

Validate instance type format for the given execution platform.

Parameters:

• instance_type (str) – Instance type to validate

• execution_platform (str) – ‘aws’ or ‘azure’

Returns:

(is_valid: bool, error_message: str or None)

Return type:

tuple

cloudos_cli.interactive_session.interactive_session.validate_session_id(session_id)

Validate session ID format (24-character hex string).

Parameters:

session_id (str)

Return type:

bool

cloudos_cli.interactive_session.interactive_session.validate_volume_sizes(storage_size, volume_sizes)

Check that a volume split is valid for the given storage size.

Parameters:

• storage_size (int) – Total storage in GB.

• volume_sizes (dict) – Sizes in GB keyed by ‘libraries’, ‘sessionResults’ and ‘mountedData’.

Raises:

ValueError – If a volume is missing, below its minimum, or the volumes do not add up to the storage size.

cloudos_cli.interactive_session.interactive_session.volume_size_rows(volume_sizes)

Return (label, value) table rows for each volume, drawn as a tree under Storage.