cloudos-cli 2.76.4__tar.gz → 2.78.0__tar.gz

{cloudos_cli-2.76.4 → cloudos_cli-2.78.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudos_cli
-Version: 2.76.4
+Version: 2.78.0
 Summary: Python package for interacting with CloudOS
 Home-page: https://github.com/lifebit-ai/cloudos-cli
 Author: David Piñeyro
@@ -80,6 +80,8 @@ Python package for interacting with CloudOS
       - [Get Job Costs](#get-job-costs)
       - [Get Job Related Analyses](#get-job-related-analyses)
       - [Delete Job Results](#delete-job-results)
+      - [Archive Jobs](#archive-jobs)
+      - [Unarchive Jobs](#unarchive-jobs)
     - [Bash Jobs](#bash-jobs)
       - [Send Array Job](#send-array-job)
       - [Submit a Bash Array Job](#submit-a-bash-array-job)
@@ -967,7 +969,8 @@ cloudos job resume \
 
 Aborts jobs in the CloudOS workspace that are either running or initializing. It can be used with one or more job IDs provided as a comma-separated string using the `--job-ids` parameter.
 
-Example:
+##### Basic Usage
+
 ```bash
 cloudos job abort --profile my_profile --job-ids "680a3cf80e56949775c02f16"
 ```
@@ -977,6 +980,29 @@ Aborting jobs...
         Job 680a3cf80e56949775c02f16 aborted successfully.
 ```
 
+##### Force Abort
+
+The `--force` flag allows you to abort jobs faster as it removes the running infrastructure. When using this flag, be aware that some data might be lost (it could be results or logs, based on what the job is performing at the moment of the forced abort).
+
+```bash
+cloudos job abort --profile my_profile --job-ids "680a3cf80e56949775c02f16" --force
+```
+
+```console
+Aborting jobs...
+Warning: Using --force to abort job 680a3cf80e56949775c02f16. Some data might be lost.
+Job 680a3cf80e56949775c02f16 aborted successfully.
+```
+
+##### Additional Options
+
+- `--workspace-id`: The CloudOS workspace ID (can be set in profile)
+- `--apikey`: Your CloudOS API key (can be set in profile)
+- `--cloudos-url`: The CloudOS URL (default: https://cloudos.lifebit.ai)
+- `--verbose`: Print detailed information messages
+- `--disable-ssl-verification`: Disable SSL certificate verification (not recommended)
+- `--ssl-cert`: Path to your SSL certificate file
+
 #### Get Job Details
 
 Details of a job, including cost, status, and timestamps, can be retrieved with:
@@ -1469,6 +1495,198 @@ Selected job does not have 'Results' information.
 
 For bulk deletion of job results and working directories across multiple jobs in a project, see the [delete_project_jobs.sh utility script](docs/utils/delete_project_jobs.md) in the `utils` folder. This script allows you to efficiently delete results and/or working directories for all jobs in a project.
 
+#### Archive Jobs
+
+CloudOS allows you to archive completed jobs to organize and manage your analysis history.
+
+> [!NOTE]
+> Archiving jobs does not delete any data or results. It simply adds metadata to mark jobs as archived for organizational purposes.
+
+> [!IMPORTANT]
+> **Admin Permissions Required**: Only workspace administrators can archive jobs belonging to other users. Regular users can only archive their own jobs.
+
+**Archive a Single Job**
+
+To archive a single job, use the `job archive` command with the job ID:
+
+```bash
+cloudos job archive --profile my_profile --job-ids 69413101b07d5f5bb46891b4
+```
+
+The expected output will confirm successful archiving:
+
+```console
+Archiving jobs...
+Job '69413101b07d5f5bb46891b4' archived successfully.
+```
+
+**Archive Multiple Jobs**
+
+You can archive multiple jobs simultaneously by providing a comma-separated list of job IDs:
+
+```bash
+cloudos job archive --profile my_profile --job-ids "job1,job2,job3"
+```
+
+This will archive all valid job IDs in a single operation:
+
+```console
+Archiving jobs...
+3 jobs archived successfully: job1, job2, job3
+```
+
+**Verbose Output**
+
+For detailed information about the archiving process, use the `--verbose` flag:
+
+```bash
+cloudos job archive --profile my_profile --job-ids 69413101b07d5f5bb46891b4 --verbose
+```
+
+This provides additional details about the operation:
+
+```console
+Archiving jobs...
+	...Preparing objects
+	The following Cloudos object was created:
+	Cloudos(cloudos_url='https://cloudos.lifebit.ai', apikey='***', cromwell_token=None)
+
+	Archiving jobs in the following workspace: workspace_123
+	Job 69413101b07d5f5bb46891b4 found with status: completed
+Job '69413101b07d5f5bb46891b4' archived successfully.
+```
+
+**Error Handling**
+
+The archive command handles various scenarios gracefully:
+
+- **Invalid Job IDs**: Jobs that don't exist are skipped with a warning message
+- **Mixed Valid/Invalid**: Valid jobs are archived, invalid ones are reported
+- **Empty Job List**: Providing empty job IDs results in a clear error message
+
+Example with mixed valid and invalid job IDs:
+
+```bash
+cloudos job archive --profile my_profile --job-ids "valid_job,invalid_job"
+```
+
+```console
+Archiving jobs...
+Failed to get status for job invalid_job, please make sure it exists in the workspace: Job not found
+Job 'valid_job' archived successfully.
+```
+
+**Command Options**
+
+- `--job-ids`: One or more job IDs to archive (comma-separated for multiple)
+- `--verbose`: Display detailed information about the archiving process
+- `--profile`: Use a specific configuration profile
+- `--workspace-id`: Specify the workspace ID (if not using profiles)
+- `--apikey`: Your CloudOS API key (if not using profiles)
+
+> [!TIP]
+> Use the `cloudos job list` command to identify jobs you want to archive. You can filter by status, project, or other criteria to find specific jobs for archiving.
+
+#### Unarchive Jobs
+
+CloudOS allows you to restore archived jobs back to their active state. Unarchiving removes the archived status while preserving all job data, results, and history.
+
+> [!NOTE]
+> Unarchiving jobs does not modify any data or results. It simply removes the archived metadata flag, making jobs appear as regular (non-archived) jobs again.
+
+> [!IMPORTANT]
+> **Admin Permissions Required**: Only workspace administrators can unarchive jobs belonging to other users. Regular users can only unarchive their own jobs.
+
+**Unarchive a Single Job**
+
+To unarchive a single archived job, use the `job unarchive` command with the job ID:
+
+```bash
+cloudos job unarchive --profile my_profile --job-ids 6929d62fe63b3cba2b32261a
+```
+
+The expected output will confirm successful unarchiving:
+
+```console
+Unarchiving jobs...
+Job '6929d62fe63b3cba2b32261a' unarchived successfully.
+```
+
+**Unarchive Multiple Jobs**
+
+You can unarchive multiple jobs simultaneously by providing a comma-separated list of job IDs:
+
+```bash
+cloudos job unarchive --profile my_profile --job-ids "job1,job2,job3"
+```
+
+This will unarchive all valid job IDs in a single operation:
+
+```console
+Unarchiving jobs...
+3 jobs unarchived successfully: job1, job2, job3
+```
+
+**Verbose Output**
+
+For detailed information about the unarchiving process, use the `--verbose` flag:
+
+```bash
+cloudos job unarchive --profile my_profile --job-ids 6929d62fe63b3cba2b32261a --verbose
+```
+
+This provides additional details about the operation:
+
+```console
+Unarchiving jobs...
+	...Preparing objects
+	The following Cloudos object was created:
+	Cloudos(cloudos_url='https://cloudos.lifebit.ai', apikey='***', cromwell_token=None)
+
+	Unarchiving jobs in the following workspace: workspace_123
+	Job 6929d62fe63b3cba2b32261a found with status: completed
+Job '6929d62fe63b3cba2b32261a' unarchived successfully.
+```
+
+**Error Handling**
+
+The unarchive command handles various scenarios gracefully:
+
+- **Invalid Job IDs**: Jobs that don't exist are skipped with a warning message
+- **Mixed Valid/Invalid**: Valid jobs are unarchived, invalid ones are reported
+- **Empty Job List**: Providing empty job IDs results in a clear error message
+
+Example with mixed valid and invalid job IDs:
+
+```bash
+cloudos job unarchive --profile my_profile --job-ids "valid_job,invalid_job"
+```
+
+```console
+Unarchiving jobs...
+Failed to get status for job invalid_job, please make sure it exists in the workspace: Job not found
+Job 'valid_job' unarchived successfully.
+```
+
+**Command Options**
+
+- `--job-ids`: One or more job IDs to unarchive (comma-separated for multiple)
+- `--verbose`: Display detailed information about the unarchiving process
+- `--profile`: Use a specific configuration profile
+- `--workspace-id`: Specify the workspace ID (if not using profiles)
+- `--apikey`: Your CloudOS API key (if not using profiles)
+
+**Managing Job Lifecycle**
+
+Use the archive and unarchive commands together to manage your job organization:
+
+1. **Archive completed jobs** to keep your workspace organized
+2. **Unarchive when needed** to access or review historical analyses
+3. **Combine with filtering** using `cloudos job list` to manage jobs in bulk
+
+> [!TIP]
+> Archived jobs remain fully accessible - archiving is purely for organizational purposes. Use `cloudos job list` with appropriate filters to view and manage both archived and active jobs.
+
 ### Bash Jobs
 Execute bash scripts on CloudOS for custom processing workflows. Bash jobs allow you to run shell commands with custom parameters and are ideal for data preprocessing or simple computational tasks.
 

{cloudos_cli-2.76.4 → cloudos_cli-2.78.0}/README.md

@@ -45,6 +45,8 @@ Python package for interacting with CloudOS
       - [Get Job Costs](#get-job-costs)
       - [Get Job Related Analyses](#get-job-related-analyses)
       - [Delete Job Results](#delete-job-results)
+      - [Archive Jobs](#archive-jobs)
+      - [Unarchive Jobs](#unarchive-jobs)
     - [Bash Jobs](#bash-jobs)
       - [Send Array Job](#send-array-job)
       - [Submit a Bash Array Job](#submit-a-bash-array-job)
@@ -932,7 +934,8 @@ cloudos job resume \
 
 Aborts jobs in the CloudOS workspace that are either running or initializing. It can be used with one or more job IDs provided as a comma-separated string using the `--job-ids` parameter.
 
-Example:
+##### Basic Usage
+
 ```bash
 cloudos job abort --profile my_profile --job-ids "680a3cf80e56949775c02f16"
 ```
@@ -942,6 +945,29 @@ Aborting jobs...
         Job 680a3cf80e56949775c02f16 aborted successfully.
 ```
 
+##### Force Abort
+
+The `--force` flag allows you to abort jobs faster as it removes the running infrastructure. When using this flag, be aware that some data might be lost (it could be results or logs, based on what the job is performing at the moment of the forced abort).
+
+```bash
+cloudos job abort --profile my_profile --job-ids "680a3cf80e56949775c02f16" --force
+```
+
+```console
+Aborting jobs...
+Warning: Using --force to abort job 680a3cf80e56949775c02f16. Some data might be lost.
+Job 680a3cf80e56949775c02f16 aborted successfully.
+```
+
+##### Additional Options
+
+- `--workspace-id`: The CloudOS workspace ID (can be set in profile)
+- `--apikey`: Your CloudOS API key (can be set in profile)
+- `--cloudos-url`: The CloudOS URL (default: https://cloudos.lifebit.ai)
+- `--verbose`: Print detailed information messages
+- `--disable-ssl-verification`: Disable SSL certificate verification (not recommended)
+- `--ssl-cert`: Path to your SSL certificate file
+
 #### Get Job Details
 
 Details of a job, including cost, status, and timestamps, can be retrieved with:
@@ -1434,6 +1460,198 @@ Selected job does not have 'Results' information.
 
 For bulk deletion of job results and working directories across multiple jobs in a project, see the [delete_project_jobs.sh utility script](docs/utils/delete_project_jobs.md) in the `utils` folder. This script allows you to efficiently delete results and/or working directories for all jobs in a project.
 
+#### Archive Jobs
+
+CloudOS allows you to archive completed jobs to organize and manage your analysis history.
+
+> [!NOTE]
+> Archiving jobs does not delete any data or results. It simply adds metadata to mark jobs as archived for organizational purposes.
+
+> [!IMPORTANT]
+> **Admin Permissions Required**: Only workspace administrators can archive jobs belonging to other users. Regular users can only archive their own jobs.
+
+**Archive a Single Job**
+
+To archive a single job, use the `job archive` command with the job ID:
+
+```bash
+cloudos job archive --profile my_profile --job-ids 69413101b07d5f5bb46891b4
+```
+
+The expected output will confirm successful archiving:
+
+```console
+Archiving jobs...
+Job '69413101b07d5f5bb46891b4' archived successfully.
+```
+
+**Archive Multiple Jobs**
+
+You can archive multiple jobs simultaneously by providing a comma-separated list of job IDs:
+
+```bash
+cloudos job archive --profile my_profile --job-ids "job1,job2,job3"
+```
+
+This will archive all valid job IDs in a single operation:
+
+```console
+Archiving jobs...
+3 jobs archived successfully: job1, job2, job3
+```
+
+**Verbose Output**
+
+For detailed information about the archiving process, use the `--verbose` flag:
+
+```bash
+cloudos job archive --profile my_profile --job-ids 69413101b07d5f5bb46891b4 --verbose
+```
+
+This provides additional details about the operation:
+
+```console
+Archiving jobs...
+	...Preparing objects
+	The following Cloudos object was created:
+	Cloudos(cloudos_url='https://cloudos.lifebit.ai', apikey='***', cromwell_token=None)
+
+	Archiving jobs in the following workspace: workspace_123
+	Job 69413101b07d5f5bb46891b4 found with status: completed
+Job '69413101b07d5f5bb46891b4' archived successfully.
+```
+
+**Error Handling**
+
+The archive command handles various scenarios gracefully:
+
+- **Invalid Job IDs**: Jobs that don't exist are skipped with a warning message
+- **Mixed Valid/Invalid**: Valid jobs are archived, invalid ones are reported
+- **Empty Job List**: Providing empty job IDs results in a clear error message
+
+Example with mixed valid and invalid job IDs:
+
+```bash
+cloudos job archive --profile my_profile --job-ids "valid_job,invalid_job"
+```
+
+```console
+Archiving jobs...
+Failed to get status for job invalid_job, please make sure it exists in the workspace: Job not found
+Job 'valid_job' archived successfully.
+```
+
+**Command Options**
+
+- `--job-ids`: One or more job IDs to archive (comma-separated for multiple)
+- `--verbose`: Display detailed information about the archiving process
+- `--profile`: Use a specific configuration profile
+- `--workspace-id`: Specify the workspace ID (if not using profiles)
+- `--apikey`: Your CloudOS API key (if not using profiles)
+
+> [!TIP]
+> Use the `cloudos job list` command to identify jobs you want to archive. You can filter by status, project, or other criteria to find specific jobs for archiving.
+
+#### Unarchive Jobs
+
+CloudOS allows you to restore archived jobs back to their active state. Unarchiving removes the archived status while preserving all job data, results, and history.
+
+> [!NOTE]
+> Unarchiving jobs does not modify any data or results. It simply removes the archived metadata flag, making jobs appear as regular (non-archived) jobs again.
+
+> [!IMPORTANT]
+> **Admin Permissions Required**: Only workspace administrators can unarchive jobs belonging to other users. Regular users can only unarchive their own jobs.
+
+**Unarchive a Single Job**
+
+To unarchive a single archived job, use the `job unarchive` command with the job ID:
+
+```bash
+cloudos job unarchive --profile my_profile --job-ids 6929d62fe63b3cba2b32261a
+```
+
+The expected output will confirm successful unarchiving:
+
+```console
+Unarchiving jobs...
+Job '6929d62fe63b3cba2b32261a' unarchived successfully.
+```
+
+**Unarchive Multiple Jobs**
+
+You can unarchive multiple jobs simultaneously by providing a comma-separated list of job IDs:
+
+```bash
+cloudos job unarchive --profile my_profile --job-ids "job1,job2,job3"
+```
+
+This will unarchive all valid job IDs in a single operation:
+
+```console
+Unarchiving jobs...
+3 jobs unarchived successfully: job1, job2, job3
+```
+
+**Verbose Output**
+
+For detailed information about the unarchiving process, use the `--verbose` flag:
+
+```bash
+cloudos job unarchive --profile my_profile --job-ids 6929d62fe63b3cba2b32261a --verbose
+```
+
+This provides additional details about the operation:
+
+```console
+Unarchiving jobs...
+	...Preparing objects
+	The following Cloudos object was created:
+	Cloudos(cloudos_url='https://cloudos.lifebit.ai', apikey='***', cromwell_token=None)
+
+	Unarchiving jobs in the following workspace: workspace_123
+	Job 6929d62fe63b3cba2b32261a found with status: completed
+Job '6929d62fe63b3cba2b32261a' unarchived successfully.
+```
+
+**Error Handling**
+
+The unarchive command handles various scenarios gracefully:
+
+- **Invalid Job IDs**: Jobs that don't exist are skipped with a warning message
+- **Mixed Valid/Invalid**: Valid jobs are unarchived, invalid ones are reported
+- **Empty Job List**: Providing empty job IDs results in a clear error message
+
+Example with mixed valid and invalid job IDs:
+
+```bash
+cloudos job unarchive --profile my_profile --job-ids "valid_job,invalid_job"
+```
+
+```console
+Unarchiving jobs...
+Failed to get status for job invalid_job, please make sure it exists in the workspace: Job not found
+Job 'valid_job' unarchived successfully.
+```
+
+**Command Options**
+
+- `--job-ids`: One or more job IDs to unarchive (comma-separated for multiple)
+- `--verbose`: Display detailed information about the unarchiving process
+- `--profile`: Use a specific configuration profile
+- `--workspace-id`: Specify the workspace ID (if not using profiles)
+- `--apikey`: Your CloudOS API key (if not using profiles)
+
+**Managing Job Lifecycle**
+
+Use the archive and unarchive commands together to manage your job organization:
+
+1. **Archive completed jobs** to keep your workspace organized
+2. **Unarchive when needed** to access or review historical analyses
+3. **Combine with filtering** using `cloudos job list` to manage jobs in bulk
+
+> [!TIP]
+> Archived jobs remain fully accessible - archiving is purely for organizational purposes. Use `cloudos job list` with appropriate filters to view and manage both archived and active jobs.
+
 ### Bash Jobs
 Execute bash scripts on CloudOS for custom processing workflows. Bash jobs allow you to run shell commands with custom parameters and are ideal for data preprocessing or simple computational tasks.