Need more information on usage of ibmcloud cos object-retention-put and documentation correction.

[SanMasood]

Hello.

1. Could you please provide more detail in the documentation regarding the usage of ibmcloud cos object-retention-put command. The documentation does not make it clear what exactly The KEY of the object is and where to obtain it from.

Also, could you please elaborate more on what the expectation for the STRUCTURE is? What are the possible values for Mode? (https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-getting-started-cloud-object-storage).

2. The example usage of object-retention-get over here: https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-ic-cos-cli#object-retention is incorrect. It says object-retention-put instead.

[IBM-diksha]

Hi @SanMasood
The Key of the object is the object name in the COS bucket. And for the STRUCTURE for retention is the object retention configuration that ibcludes the retention mode and retain until date.
Here is an example.
{"Mode": "COMPLIANCE", "RetainUntilDate": "2024-12-12T00:00:00Z"}
Other possible value for Mode is GOVERNANCE , but as of now we do not support that in IBM COS.
For the example usage , we will have an internal ticket for that and rectify it.
Thank you.

[SanMasood]

Thank you for your response. This is the command I've used:

ibmcloud cos object-retention-put --bucket bucket-sm-1 --key 'test_report.pdf'  --retention '{ "Mode": "COMPLIANCE", "RetainUntilDate": "2025-12-12T00:00:00"}'

However, this gives me the error The value in flag '--retention' is invalid .

Is there a command to apply retention to a bucket please? An CLI alternative to this:

[IBM-diksha]

Hi @SanMasood can you please try the following -
ibmcloud cos object-retention-put --bucket bucket-sm-1 --key 'test_report.pdf' --retention '{ "Mode": "COMPLIANCE", "RetainUntilDate": "2025-12-12T00:00:00Z"}'

In the command the time stamp should be 2025-12-12T00:00:00Z instead of 2025-12-12T00:00:00 the Z represents the timezone and to keep it consistent it takes UTC timezone , hence it says the value in --retention is invalid due to the timestamp , please try this and let us know if it works.

And as of now we only support putting retention at object level using cli for cos.