.TH "GCLOUD_ALPHA_STORAGE_OBJECTS_UPDATE" 1



.SH "NAME"
.HP
gcloud alpha storage objects update \- update Cloud Storage objects



.SH "SYNOPSIS"
.HP
\f5gcloud alpha storage objects update\fR [\fIURL\fR\ ...] [\fB\-\-additional\-headers\fR=\fIHEADER\fR=\fIVALUE\fR] [\fB\-\-all\-versions\fR] [\fB\-\-continue\-on\-error\fR,\ \fB\-c\fR] [\fB\-\-[no\-]event\-based\-hold\fR] [\fB\-\-read\-paths\-from\-stdin\fR,\ \fB\-I\fR] [\fB\-\-recursive\fR,\ \fB\-R\fR,\ \fB\-r\fR] [\fB\-\-storage\-class\fR=\fISTORAGE_CLASS\fR,\ \fB\-s\fR\ \fISTORAGE_CLASS\fR] [\fB\-\-[no\-]temporary\-hold\fR] [\fB\-\-acl\-file\fR=\fIACL_FILE\fR\ \fB\-\-add\-acl\-grant\fR=[\fIACL_GRANT\fR,...]\ \fB\-\-canned\-acl\fR=\fIPREDEFINED_ACL\fR,\ \fB\-\-predefined\-acl\fR=\fIPREDEFINED_ACL\fR,\ \fB\-a\fR\ \fIPREDEFINED_ACL\fR\ \fB\-\-[no\-]preserve\-acl\fR,\ \fB\-p\fR\ \fB\-\-remove\-acl\-grant\fR=\fIREMOVE_ACL_GRANT\fR] [\fB\-\-clear\-encryption\-key\fR\ \fB\-\-decryption\-keys\fR=[\fIDECRYPTION_KEY\fR,...]\ \fB\-\-encryption\-key\fR=\fIENCRYPTION_KEY\fR] [\fB\-\-cache\-control\fR=\fICACHE_CONTROL\fR\ \fB\-\-clear\-cache\-control\fR\ \fB\-\-clear\-content\-disposition\fR\ \fB\-\-clear\-content\-encoding\fR\ \fB\-\-clear\-content\-language\fR\ \fB\-\-clear\-content\-type\fR\ \fB\-\-clear\-custom\-time\fR\ \fB\-\-content\-disposition\fR=\fICONTENT_DISPOSITION\fR\ \fB\-\-content\-encoding\fR=\fICONTENT_ENCODING\fR\ \fB\-\-content\-language\fR=\fICONTENT_LANGUAGE\fR\ \fB\-\-content\-type\fR=\fICONTENT_TYPE\fR\ \fB\-\-custom\-time\fR=\fICUSTOM_TIME\fR\ \fB\-\-clear\-custom\-contexts\fR\ |\ \fB\-\-custom\-contexts\fR=[\fICUSTOM_CONTEXTS_KEYS_AND_VALUES\fR,...]\ |\ \fB\-\-custom\-contexts\-file\fR=\fICUSTOM_CONTEXTS_FILE\fR\ |\ \fB\-\-remove\-custom\-contexts\fR=[\fICUSTOM_CONTEXTS_KEYS\fR,...]\ \fB\-\-update\-custom\-contexts\fR=[\fICUSTOM_CONTEXTS_KEYS_AND_VALUES\fR,...]\ \fB\-\-clear\-custom\-metadata\fR\ |\ \fB\-\-custom\-metadata\fR=[\fICUSTOM_METADATA_KEYS_AND_VALUES\fR,...]\ |\ \fB\-\-remove\-custom\-metadata\fR=[\fIMETADATA_KEYS\fR,...]\ \fB\-\-update\-custom\-metadata\fR=[\fICUSTOM_METADATA_KEYS_AND_VALUES\fR,...]] [\fB\-\-if\-generation\-match\fR=\fIGENERATION\fR\ \fB\-\-if\-metageneration\-match\fR=\fIMETAGENERATION\fR] [\fB\-\-clear\-retention\fR\ \fB\-\-override\-unlocked\-retention\fR\ \fB\-\-retain\-until\fR=\fIDATETIME\fR\ \fB\-\-retention\-mode\fR=\fIRETENTION_MODE\fR] [\fIGCLOUD_WIDE_FLAG\ ...\fR]



.SH "DESCRIPTION"

\fB(ALPHA)\fR Update Cloud Storage objects.



.SH "EXAMPLES"

Update a Google Cloud Storage object's custom\-metadata:

.RS 2m
$ gcloud alpha storage objects update gs://bucket/my\-object \e
    \-\-custom\-metadata=key1=value1,key2=value2
.RE

One can use wildcards (https://cloud.google.com/storage/docs/wildcards) to
update multiple objects in a single command. for instance to update all objects
to have a custom\-metadata key:

.RS 2m
$ gcloud alpha storage objects update gs://bucket/** \e
    \-\-custom\-metadata=key1=value1,key2=value2
.RE

Rewrite all JPEG images to the NEARLINE storage class:

.RS 2m
$ gcloud alpha storage objects update gs://bucket/*.jpg \e
    \-\-storage\-class=NEARLINE
.RE

You can also provide a precondition on an object's metageneration in order to
avoid potential race conditions:

.RS 2m
$ gcloud alpha storage objects update gs://bucket/*.jpg \e
    \-\-storage\-class=NEARLINE \-\-if\-metageneration\-match=123456789
.RE

The following command overwrites the custom contexts of an object:

.RS 2m
$ gcloud alpha storage objects update gs://bucket/my\-object \e
    \-\-custom\-contexts=key1=value1,key2=value2
.RE

The following example simultaneously updates and removes custom contexts, with
remove being applied first:

.RS 2m
$ gcloud alpha storage objects update gs://bucket/my\-object \e
    \-\-update\-custom\-contexts=key2=value3 \e
    \-\-remove\-custom\-contexts=key2,key3
.RE



.SH "POSITIONAL ARGUMENTS"

.RS 2m
.TP 2m
[\fIURL\fR ...]

Specifies URLs of objects to update.


.RE
.sp

.SH "FLAGS"

.RS 2m
.TP 2m
\fB\-\-additional\-headers\fR=\fIHEADER\fR=\fIVALUE\fR

Includes arbitrary headers in storage API calls. Accepts a comma separated list
of key=value pairs, e.g. \f5header1=value1,header2=value2\fR. Overrides the
default \fBstorage/additional_headers\fR property value for this command
invocation.

.TP 2m
\fB\-\-all\-versions\fR

Perform the operation on all object versions.

.TP 2m
\fB\-\-continue\-on\-error\fR, \fB\-c\fR

If any operations are unsuccessful, the command will exit with a non\-zero exit
status after completing the remaining operations. This flag takes effect only in
sequential execution mode (i.e. processor and thread count are set to 1).
Parallelism is default.

.TP 2m
\fB\-\-[no\-]event\-based\-hold\fR

Enables or disables an event\-based hold on objects. Use
\fB\-\-event\-based\-hold\fR to enable and \fB\-\-no\-event\-based\-hold\fR to
disable.

.TP 2m
\fB\-\-read\-paths\-from\-stdin\fR, \fB\-I\fR

Read the list of objects to update from stdin. No need to enter a source
argument if this flag is present. Example: "storage objects update \-I
\-\-content\-type=new\-type"

.TP 2m
\fB\-\-recursive\fR, \fB\-R\fR, \fB\-r\fR

Recursively update objects under any buckets or directories that match the URL
expression.

.TP 2m
\fB\-\-storage\-class\fR=\fISTORAGE_CLASS\fR, \fB\-s\fR \fISTORAGE_CLASS\fR

Specify the storage class of the object. Using this flag triggers a rewrite of
underlying object data.

.TP 2m
\fB\-\-[no\-]temporary\-hold\fR

Enables or disables a temporary hold on objects. Use \fB\-\-temporary\-hold\fR
to enable and \fB\-\-no\-temporary\-hold\fR to disable.

.TP 2m
\fB\-\-acl\-file\fR=\fIACL_FILE\fR

Path to a local JSON or YAML formatted file containing a valid policy. See the
ObjectAccessControls resource
(https://cloud.google.com/storage/docs/json_api/v1/objectAccessControls) for a
representation of JSON formatted files. The output of \f5gcloud storage
[buckets|objects] describe\fR \f5\-\-format="multi(acl:format=json)"\fR is a
valid file and can be edited for more fine\-grained control.

.TP 2m
\fB\-\-add\-acl\-grant\fR=[\fIACL_GRANT\fR,...]

Key\-value pairs mirroring the JSON accepted by your cloud provider. For
example, for Cloud
Storage,\f5\-\-add\-acl\-grant=entity=user\-tim@gmail.com,role=OWNER\fR

.TP 2m
\fB\-\-canned\-acl\fR=\fIPREDEFINED_ACL\fR, \fB\-\-predefined\-acl\fR=\fIPREDEFINED_ACL\fR, \fB\-a\fR \fIPREDEFINED_ACL\fR

Applies predefined, or "canned," ACLs to a resource. See docs for a list of
predefined ACL constants:
https://cloud.google.com/storage/docs/access\-control/lists#predefined\-acl

.TP 2m
\fB\-\-[no\-]preserve\-acl\fR, \fB\-p\fR

Preserves ACLs when copying in the cloud. This option is Cloud Storage\-only,
and you need OWNER access to all copied objects. If all objects in the
destination bucket should have the same ACL, you can also set a default object
ACL on that bucket instead of using this flag. Preserving ACLs is the default
behavior for updating existing objects. Use \fB\-\-preserve\-acl\fR to enable
and \fB\-\-no\-preserve\-acl\fR to disable.

.TP 2m
\fB\-\-remove\-acl\-grant\fR=\fIREMOVE_ACL_GRANT\fR

Key\-value pairs mirroring the JSON accepted by your cloud provider. For
example, for Cloud Storage, \f5\-\-remove\-acl\-grant=ENTITY\fR, where
\f5ENTITY\fR has a valid ACL entity format, such as \f5user\-tim@gmail.com\fR,
\f5group\-admins\fR, \f5allUsers\fR, etc.


.RE
.sp

.SH "ENCRYPTION FLAGS"

.RS 2m
.TP 2m
\fB\-\-clear\-encryption\-key\fR

Clears the encryption key associated with an object. Using this flag triggers a
rewrite of affected objects, which are then encrypted using the default
encryption key set on the bucket, if one exists, or else with a Google\-managed
encryption key.

.TP 2m
\fB\-\-decryption\-keys\fR=[\fIDECRYPTION_KEY\fR,...]

A comma\-separated list of customer\-supplied encryption keys (RFC 4648 section
4 base64\-encoded AES256 strings) that will be used to decrypt Cloud Storage
objects. Data encrypted with a customer\-managed encryption key (CMEK) is
decrypted automatically, so CMEKs do not need to be listed here.

.TP 2m
\fB\-\-encryption\-key\fR=\fIENCRYPTION_KEY\fR

The encryption key to use for encrypting target objects. The specified
encryption key can be a customer\-supplied encryption key (An RFC 4648 section 4
base64\-encoded AES256 string), or a customer\-managed encryption key of the
form
\f5projects/{project}/locations/{location}/keyRings/{key\-ring}/cryptoKeys/{crypto\-key}\fR.
The specified key also acts as a decryption key, which is useful when copying or
moving encrypted data to a new location. Using this flag in an \f5objects
update\fR command triggers a rewrite of target objects.


.RE
.sp

.SH "OBJECT METADATA FLAGS"

.RS 2m
.TP 2m
\fB\-\-cache\-control\fR=\fICACHE_CONTROL\fR

How caches should handle requests and responses.

.TP 2m
\fB\-\-clear\-cache\-control\fR

Clears object cache control.

.TP 2m
\fB\-\-clear\-content\-disposition\fR

Clears object content disposition.

.TP 2m
\fB\-\-clear\-content\-encoding\fR

Clears content encoding.

.TP 2m
\fB\-\-clear\-content\-language\fR

Clears object content language.

.TP 2m
\fB\-\-clear\-content\-type\fR

Clears object content type.

.TP 2m
\fB\-\-clear\-custom\-time\fR

Clears object custom time.

.TP 2m
\fB\-\-content\-disposition\fR=\fICONTENT_DISPOSITION\fR

How content should be displayed.

.TP 2m
\fB\-\-content\-encoding\fR=\fICONTENT_ENCODING\fR

How content is encoded (e.g. \f5\fIgzip\fR\fR).

.TP 2m
\fB\-\-content\-language\fR=\fICONTENT_LANGUAGE\fR

Content's language (e.g. \f5\fIen\fR\fR signifies "English").

.TP 2m
\fB\-\-content\-type\fR=\fICONTENT_TYPE\fR

Type of data contained in the object (e.g. \f5\fItext/html\fR\fR).

.TP 2m
\fB\-\-custom\-time\fR=\fICUSTOM_TIME\fR

Custom time for Cloud Storage objects in RFC 3339 format.

.TP 2m

Group that allow users to handle object contexts.

At most one of these can be specified:


.RS 2m
.TP 2m
\fB\-\-clear\-custom\-contexts\fR

Clears all custom contexts on objects.

.TP 2m
\fB\-\-custom\-contexts\fR=[\fICUSTOM_CONTEXTS_KEYS_AND_VALUES\fR,...]

Sets custom contexts on objects. The existing custom contexts (if any) would be
overwritten.

.TP 2m
\fB\-\-custom\-contexts\-file\fR=\fICUSTOM_CONTEXTS_FILE\fR

Path to a local JSON or YAML file containing custom contexts one wants to set on
an object. For example:

1. The following JSON document shows two key value pairs, i.e. (key1, value1)
and (key2, value2):

.RS 2m
  {
    "key1": {"value": "value1"},
    "key2": {"value": "value2"}
  }
.RE

2. The following YAML document shows two key value pairs, i.e. (key1, value1)
and (key2, value2):

.RS 2m
  key1:
    value: value1
  key2:
    value: value2
.RE

Note: Currently object contexts only supports string format for values.

.TP 2m

Flags that preserve the existing contexts on the object, and can be specified
together. However they cannot be specified with
\f5\-\-clear\-custom\-contexts\fR, \f5\-\-custom\-contexts\fR or
\f5\-\-custom\-contexts\-file\fR. If \f5\-\-update\-custom\-contexts\fR and
\f5\-\-remove\-custom\-contexts\fR are specified together, the
\f5\-\-remove\-custom\-contexts\fR would be applied first on object.


.RS 2m
.TP 2m
\fB\-\-remove\-custom\-contexts\fR=[\fICUSTOM_CONTEXTS_KEYS\fR,...]

Removes the custom contexts on the object, if an entry is not found, it would be
ignored.

.TP 2m
\fB\-\-update\-custom\-contexts\fR=[\fICUSTOM_CONTEXTS_KEYS_AND_VALUES\fR,...]

Updates the custom contexts on the object, if an entry is found, it would be
overwritten, otherwise the entry would be added.

.RE
.RE
.sp
.TP 2m

At most one of these can be specified:


.RS 2m
.TP 2m
\fB\-\-clear\-custom\-metadata\fR

Clears all custom metadata on objects. When used with \f5\-\-preserve\-posix\fR,
POSIX attributes will still be stored in custom metadata.

.TP 2m
\fB\-\-custom\-metadata\fR=[\fICUSTOM_METADATA_KEYS_AND_VALUES\fR,...]

Sets custom metadata on objects. When used with \f5\-\-preserve\-posix\fR, POSIX
attributes are also stored in custom metadata.

.TP 2m

Flags that preserve unspecified existing metadata cannot be used with
\f5\-\-custom\-metadata\fR or \f5\-\-clear\-custom\-metadata\fR, but can be
specified together:


.RS 2m
.TP 2m
\fB\-\-remove\-custom\-metadata\fR=[\fIMETADATA_KEYS\fR,...]

Removes individual custom metadata keys from objects. This flag can be used with
\f5\-\-update\-custom\-metadata\fR. When used with \f5\-\-preserve\-posix\fR,
POSIX attributes specified by this flag are not preserved.

.TP 2m
\fB\-\-update\-custom\-metadata\fR=[\fICUSTOM_METADATA_KEYS_AND_VALUES\fR,...]

Adds or sets individual custom metadata key value pairs on objects. Existing
custom metadata not specified with this flag is not changed. This flag can be
used with \f5\-\-remove\-custom\-metadata\fR. When keys overlap with those
provided by \f5\-\-preserve\-posix\fR, values specified by this flag are used.


.RE
.RE
.RE
.sp

.SH "PRECONDITION FLAGS"

.RS 2m
.TP 2m
\fB\-\-if\-generation\-match\fR=\fIGENERATION\fR

Execute only if the generation matches the generation of the requested object.

.TP 2m
\fB\-\-if\-metageneration\-match\fR=\fIMETAGENERATION\fR

Execute only if the metageneration matches the metageneration of the requested
object.


.RE
.sp

.SH "RETENTION FLAGS"

.RS 2m
.TP 2m
\fB\-\-clear\-retention\fR

Clears object retention settings and unlocks the configuration. Requires
\-\-override\-unlocked\-retention flag as confirmation.

.TP 2m
\fB\-\-override\-unlocked\-retention\fR

Needed for certain retention configuration modifications, such as clearing
retention settings and reducing retention time. Note that locked configurations
cannot be edited even with this flag.

.TP 2m
\fB\-\-retain\-until\fR=\fIDATETIME\fR

Ensures the object is retained until the specified time in RFC 3339 format.
Requires \-\-override\-unlocked\-retention flag to shorten the retain\-until
time in unlocked configurations.

.TP 2m
\fB\-\-retention\-mode\fR=\fIRETENTION_MODE\fR

Sets the object retention mode to either "Locked" or "Unlocked". When retention
mode is "Locked", the retain until time can only be increased.
\fIRETENTION_MODE\fR must be one of: \fBLocked\fR, \fBUnlocked\fR.


.RE
.sp

.SH "GCLOUD WIDE FLAGS"

These flags are available to all commands: \-\-access\-token\-file, \-\-account,
\-\-billing\-project, \-\-configuration, \-\-flags\-file, \-\-flatten,
\-\-format, \-\-help, \-\-impersonate\-service\-account, \-\-log\-http,
\-\-project, \-\-quiet, \-\-trace\-token, \-\-user\-output\-enabled,
\-\-verbosity.

Run \fB$ gcloud help\fR for details.



.SH "NOTES"

This command is currently in alpha and might change without notice. If this
command fails with API permission errors despite specifying the correct project,
you might be trying to access an API with an invitation\-only early access
allowlist. This variant is also available:

.RS 2m
$ gcloud storage objects update
.RE