Discover object storage with the Google Cloud CLI

Create a bucket

Buckets are the basic containers that hold your data in Cloud Storage.

To create a bucket:

1. Open a terminal window.

2. Use the gcloud storage buckets create command and a globally unique name to create a bucket:

   gcloud storage buckets create gs://BUCKET_NAME/ --uniform-bucket-level-access

   Replace BUCKET_NAME with a name for your bucket.

   See bucket naming requirements.

   • Bucket names can only contain lowercase letters, numeric characters, dashes (-), underscores (_), and dots (.). Spaces are not allowed. Names containing dots require verification.
   • Bucket names must start and end with a number or letter.
   • Bucket names must contain 3-63 characters. Names containing dots can contain up to 222 characters, but each dot-separated component can be no longer than 63 characters.
   • Bucket names cannot be represented as an IP address in dotted-decimal notation (for example, 192.168.5.4).
   • Bucket names cannot begin with the "goog" prefix.
   • Bucket names cannot contain "google" or close misspellings, such as "g00gle".

   If successful, the command returns a response like the following:

   Creating gs://my-awesome-bucket/...

   If the bucket name that you chose is already in use, either by you or someone else, the command returns a response like ServiceException: 409 Bucket my-awesome-bucket already exists. Try again with a different bucket name.

You've just created a bucket where you can store your data!

Upload an object into your bucket

1. Save the following image to your computer, such as on the desktop.

   

2. Use the gcloud storage cp command to copy the image from the location where you saved it to the bucket that you created:

   gcloud storage cp Desktop/kitten.png gs://BUCKET_NAME

   If successful, the command returns a response like the following:

   Copying file://Desktop/kitten.png to gs://my-awesome-bucket/kitten.png
     Completed files 1/1 | 8.6kiB/8.6kiB

   You've just stored an object in your bucket.

Download the object from your bucket

1. Use the gcloud storage cp command to download the image that you stored in your bucket to somewhere on your computer, such as the desktop:

   gcloud storage cp gs://BUCKET_NAME/kitten.png Desktop/kitten2.png

   If successful, the command returns a response like the following:

   Copying gs://my-awesome-bucket/kitten.png to file://Desktop/kitten2.png
     Completed files 1/1 | 8.6kiB/8.6kiB 

   You've just downloaded something from your bucket.

Copy the object to a simulated folder in the bucket

1. Use the gcloud storage cp command to create a simulated folder and copy the image into it:

   gcloud storage cp gs://BUCKET_NAME/kitten.png gs://BUCKET_NAME/quickstart-folder/kitten3.png

   If successful, the command returns a response like the following:

   Copying gs://my-awesome-bucket/kitten.png to gs://my-awesome-bucket/quickstart-folder/kitten3.png
     Completed files 1/1 | 8.6kiB/8.6kiB 

   You've just copied your image into a new simulated folder in your bucket.

List contents of a bucket

1. Use the gcloud storage ls command to list the contents at the top level of your bucket:

   gcloud storage ls gs://BUCKET_NAME

   If successful, the command returns a response like the following:

   gs://my-awesome-bucket/kitten.png
   gs://my-awesome-bucket/quickstart-folder/

   You've just seen the contents at the top level of your bucket.

List details for an object

1. Use the gcloud storage ls command with the --long flag to get some details about one of your images:

   gcloud storage ls gs://BUCKET_NAME/kitten.png --long

   If successful, the command returns a response like the following:

   8775  2026-01-21T01:22:17Z  gs://srs-bucketcli/kitten.png
   TOTAL: 1 objects, 8775 bytes (8.57kiB)

   You've just obtained information about the image's size and date of creation.

Make the objects publicly accessible

1. Use the gcloud storage buckets add-iam-policy-binding command to grant all users permission to read the images stored in your bucket:

   gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME --member=allUsers --role=roles/storage.objectViewer

   The command is successful if your response contains the following:

   bindings:
     - members:
       - allUsers
       role: roles/storage.objectViewer
   

   Now anyone can get your images.

2. To remove this access, use the following command:

   gcloud storage buckets remove-iam-policy-binding gs://BUCKET_NAME --member=allUsers --role=roles/storage.objectViewer

   The command is successful if no error is returned.

   You have removed public access to the images in your bucket.

Give someone access to your bucket

1. Use the gcloud storage buckets add-iam-policy-binding command to give a specific email address permission to add objects to your bucket:

   gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME --member=user:jeffersonloveshiking@gmail.com --role=roles/storage.objectCreator

   The command is successful if your response contains the following:

   bindings:
     - members:
       - user:jeffersonloveshiking@gmail.com
       role: roles/storage.objectCreator
   

   Now this user can add items to your bucket.

2. To remove this permission, use the following command:

   gcloud storage buckets remove-iam-policy-binding gs://BUCKET_NAME --member=user:jeffersonloveshiking@gmail.com --role=roles/storage.objectCreator

   The command is successful if no error is returned.

   You have removed the user's access to this bucket.

Delete an object

1. Use the gcloud storage rm command to delete one of your images:

   gcloud storage rm gs://BUCKET_NAME/kitten.png

   If successful, the command returns a response like the following:

   Removing gs://my-awesome-bucket/kitten.png...

   This copy of the image is no longer stored on Cloud Storage (though the copy you made in the simulated folder quickstart-folder/ still exists).