[Yandex Cloud documentation](../../index.md) > [Yandex Object Storage](../index.md) > [Tools](index.md) > Console clients > Yandex Cloud CLI # Command line interface (Yandex Cloud CLI) The [Yandex Cloud CLI](../../cli/index.md) is downloadable software you can use to manage your cloud resources via the command line. ## Install the Yandex Cloud CLI {#install} {% list tabs group=operating_system %} - Linux {#linux} 1. Run this command: ```bash curl -sSL https://storage.yandexcloud.net/yandexcloud-yc/install.sh | bash ``` The script will install the CLI and add the executable file path to the `PATH` environment variable. {% note info %} The script will update `PATH` only if you run it in the `bash` or `zsh` command shell. If you run the script in a different shell, add the CLI path to the `PATH` variable yourself. {% endnote %} {% note warning %} For autocompletion to work correctly when using `zsh`, you need the shell version 5.1 or higher. If using `bash` on CentOS and derivative distributions, install the `bash-completion` package. {% endnote %} 1. After installation is complete, restart your terminal. - macOS {#macos} 1. Run this command: ```bash curl -sSL https://storage.yandexcloud.net/yandexcloud-yc/install.sh | bash ``` The script will install the CLI and add the executable file path to the `PATH` environment variable. 1. Restart your terminal for the changes to take effect. The CLI supports command autocompletion for the `bash` and `zsh` command shells. To enable autocompletion: 1. Install the [Homebrew](https://brew.sh) package manager. 1. Install the `zsh-completion` package: {% note warning %} If you installed bash instead of zsh or have macOS Mojave 10.14 or earlier with bash as the default shell, use the `bash-completion` package instead of `zsh-completion` and the `~/.bash_profile` configuration file instead of `~/.zshrc` at the current and next step. {% endnote %} ``` brew install zsh-completion ``` The installation script will update the `~/.zshrc` configuration file: ``` # The next line updates PATH for Yandex Cloud CLI. if [ -f '/Users//yandex-cloud/path.bash.inc' ]; then source '/Users//yandex-cloud/path.bash.inc'; fi # The next line enables shell command completion for yc. if [ -f '/Users//yandex-cloud/completion.zsh.inc' ]; then source '/Users//yandex-cloud/completion.zsh.inc'; fi ``` 1. After the installation is complete, add the following lines to the `~/.zshrc` configuration file. Insert them above the lines automatically added by the installation script. ``` if [ -f $(brew --prefix)/etc/zsh_completion ]; then . $(brew --prefix)/etc/zsh_completion fi ``` 1. Restart your terminal. - Windows {#windows} For Windows, you can install the CLI using PowerShell or command line: - To install using PowerShell: 1. Run this command: ```bash iex (New-Object System.Net.WebClient).DownloadString('https://storage.yandexcloud.net/yandexcloud-yc/install.ps1') ``` 1. The installation script will ask whether to add the path to `yc` to the PATH variable: ``` Add yc installation dir to your PATH? [Y/n] ``` 1. Enter `Y`. After this, you can use the Yandex Cloud CLI without restarting the command shell. - To install using the command line: 1. Run this command: ```bash @"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://storage.yandexcloud.net/yandexcloud-yc/install.ps1'))" && SET "PATH=%PATH%;%USERPROFILE%\yandex-cloud\bin" ``` 1. The installation script will ask whether to add the path to `yc` to the PATH variable: ``` Add yc installation dir to your PATH? [Y/n] ``` 1. Enter `Y`. 1. Restart your terminal for the changes to take effect. {% endlist %} If you get an error during CLI installation, see [CLI troubleshooting](../../cli/error.md#failure-writing-output-to-destination). ## Get authenticated in the Yandex Cloud CLI {#cli-auth} To access the Yandex Cloud CLI, get authenticated using one of the following methods: {% list tabs group=authentication %} - Yandex account {#yandex-account} To get authenticated using a [Yandex account](../../iam/concepts/users/accounts.md#passport): 1. Get your email address: 1. Navigate to your [Yandex](https://id.yandex.ru/personal) account. 1. Copy your email address from the **Contacts** section. 1. Launch the profile creation wizard: ```bash yc init --username= ``` 1. Select the profile you want to set up authentication for or create a new one. ```text Welcome! This command will take you through the configuration process. Pick desired action: [1] Re-initialize this profile 'default' with new settings [2] Create a new profile ``` 1. The CLI prompts you to continue authentication in the browser. Press **Enter** to continue. ```text You are going to be authenticated via username ''. Authentication web site will be opened. After your successful authentication, you will be redirected to 'https://console.yandex.cloud'. Press 'enter' to continue... ``` On successful authentication, an [IAM token](../../iam/concepts/authorization/iam-token.md) will be saved in the profile. This IAM token will be used to authenticate each operation until the end of the token's [lifetime](../../iam/concepts/authorization/iam-token.md) (not more than 12 hours). After that, the CLI will once again prompt you to authenticate in the browser. To extend the period during which you do not have to authenticate in the browser, use [refresh tokens](../../iam/concepts/authorization/refresh-token.md), which allow you to reissue IAM tokens without entering the browser. Do it by enabling refresh tokens [at the organization level](../../iam/concepts/authorization/refresh-token.md#token-enabling) and [initializing DPoP protection](../../iam/concepts/authorization/refresh-token.md#enabling-dpop) in the CLI. 1. Go back to the command line interface to finish creating the profile. 1. Select one of the [clouds](../../resource-manager/concepts/resources-hierarchy.md#cloud) from the list of those you have access to: ```text Please select cloud to use: [1] cloud1 (id = aoe2bmdcvata********) [2] cloud2 (id = dcvatao4faoe********) Please enter your numeric choice: 2 ``` If there is only one cloud available, it will be selected automatically. 1. Select the default [folder](../../resource-manager/concepts/resources-hierarchy.md#folder): ```text Please choose a folder to use: [1] folder1 (id = cvatao4faoe2********) [2] folder2 (id = tao4faoe2cva********) [3] Create a new folder Please enter your numeric choice: 1 ``` 1. To select the default [availability zone](../../overview/concepts/geo-scope.md) for [Compute Cloud](../../compute/index.md), type `Y`. To skip the setup, type `n`. ```bash Do you want to configure a default Yandex Compute Cloud availability zone? [Y/n] Y ``` If you typed `Y`, select the availability zone: ```text Which zone do you want to use as a profile default? [1] ru-central1-a [2] ru-central1-b [3] ru-central1-d [4] Do not set default zone Please enter your numeric choice: 2 ``` 1. View your CLI profile settings: ```bash yc config list ``` Result: ```bash subject-id: b1g159pa15cd******** username: folder-id: b1g8o9jbt58******** compute-default-zone: ru-central1-b ``` - Federated account {#federated-account} To authenticate using a [SAML-compatible identity federation](../../organization/concepts/add-federation.md): 1. Get your federation ID from your administrator. 1. Launch the profile creation wizard: ```bash yc init --federation-id= ``` 1. Select the profile you want to set up authentication for or create a new one. ```text Welcome! This command will take you through the configuration process. Pick desired action: [1] Re-initialize this profile 'default' with new settings [2] Create a new profile ``` 1. The CLI prompts you to continue authentication in the browser. Press **Enter** to continue. ```text You are going to be authenticated via federation-id 'aje1f0hsgds3a********'. Your federation authentication web site will be opened. After your successful authentication, you will be redirected to 'https://console.yandex.cloud'. Press 'enter' to continue... ``` On successful authentication, an [IAM token](../../iam/concepts/authorization/iam-token.md) will be saved in the profile. This IAM token will be used to authenticate each operation until the end of the token's [lifetime](../../iam/concepts/authorization/iam-token.md) (not more than 12 hours). After that, the CLI will once again prompt you to authenticate in the browser. To extend the period during which you do not have to authenticate in the browser, use [refresh tokens](../../iam/concepts/authorization/refresh-token.md), which allow you to reissue IAM tokens without entering the browser. Do it by enabling refresh tokens [at the organization level](../../iam/concepts/authorization/refresh-token.md#token-enabling) and [initializing DPoP protection](../../iam/concepts/authorization/refresh-token.md#enabling-dpop) in the CLI. 1. Go back to the command line interface to finish creating the profile. 1. Select one of the [clouds](../../resource-manager/concepts/resources-hierarchy.md#cloud) from the list of those you have access to: ```text Please select cloud to use: [1] cloud1 (id = aoe2bmdcvata********) [2] cloud2 (id = dcvatao4faoe********) Please enter your numeric choice: 2 ``` If there is only one cloud available, it will be selected automatically. 1. Select the default [folder](../../resource-manager/concepts/resources-hierarchy.md#folder): ```text Please choose a folder to use: [1] folder1 (id = cvatao4faoe2********) [2] folder2 (id = tao4faoe2cva********) [3] Create a new folder Please enter your numeric choice: 1 ``` 1. To select the default [availability zone](../../overview/concepts/geo-scope.md) for [Compute Cloud](../../compute/index.md), type `Y`. To skip the setup, type `n`. ```bash Do you want to configure a default Yandex Compute Cloud availability zone? [Y/n] Y ``` If you typed `Y`, select the availability zone: ```text Which zone do you want to use as a profile default? [1] ru-central1-a [2] ru-central1-b [3] ru-central1-d [4] Do not set default zone Please enter your numeric choice: 2 ``` 1. View your CLI profile settings: ```bash yc config list ``` Result: ```bash federation-id: aje1f0hs6oja******** subject-id: ajea53egl28l******** cloud-id: b1g159pa15cd******** folder-id: b1g8o9jbt58******** compute-default-zone: ru-central1-b ``` - Service account {#service-account} To authenticate as a service account: 1. Get a list of service accounts that exist in your cloud: ```bash yc iam service-account --folder-id list ``` Result: ```text +----------------------+------------+--------+---------------------+-----------------------+ | ID | NAME | LABELS | CREATED AT | LAST AUTHENTICATED AT | +----------------------+------------+--------+---------------------+-----------------------+ | ajeg2b2et02f******** | my-robot | | 2024-09-08 18:59:45 | 2025-08-21 06:40:00 | | ajegtlf2q28a******** | default-sa | | 2023-06-27 16:18:18 | 2025-08-21 06:30:00 | +----------------------+------------+--------+---------------------+-----------------------+ ``` 1. Create an authorized key for the service account and save it to a file named `key.json`: ```bash yc iam key create \ --service-account-name default-sa \ --output key.json \ --folder-id ``` Result: ```text id: aje83v701b1u******** service_account_id: aje3932acd0c******** created_at: "2019-08-26T12:31:25Z" key_algorithm: RSA_2048 ``` 1. Add the service account authorized key to the CLI profile. 1. Create a new CLI profile: ```bash yc config profile create sa-profile ``` 1. Add an authorized key: ```bash yc config set service-account-key key.json ``` 1. Make sure the parameters for the service account are added correctly: ```bash yc config list ``` Result: ```text service-account-key: id: aje83v701b1u******** service_account_id: aje3932acd0c******** created_at: "2019-08-26T12:31:25Z" key_algorithm: RSA_2048 public_key: | -----BEGIN PUBLIC KEY----- MIIBIjANBg... -----END PUBLIC KEY----- private_key: | -----BEGIN PRIVATE KEY----- MIIEvwIBAD... -----END PRIVATE KEY----- ``` 1. Configure your profile to run commands. Some commands require that you specify unique IDs for your cloud and folder. You can specify their details in the profile or use a specific flag for these commands. 1. Specify the cloud in your profile: ```bash yc config set cloud-id ``` You can also use the `--cloud-id` parameter to [run commands](../../cli/concepts/index.md#manage-properties). 1. Specify a folder in the profile: ```bash yc config set folder-id ``` You can also use the `--folder-id` parameter to [run commands](../../cli/concepts/index.md#manage-properties). All operations in this profile will be performed on behalf of the linked service account. You can [change the profile parameters](../../cli/operations/profile/manage-properties.md) or [switch to another profile](../../cli/operations/profile/profile-activate.md). - Local user account {#local-account} To authenticate using a [local user account](../../iam/concepts/users/accounts.md#local): 1. Launch the profile creation wizard: {% list tabs %} - User pool 1. Get your user pool ID from your administrator. 1. Launch the profile creation wizard: ```bash yc init --userpool-id= ``` - Email 1. Get your email address: 1. Go to the [My account](https://myaccount.yandex.cloud/) portal. 1. In the left-hand panel, select ![alt](../../_assets/console-icons/passport.svg) **Profile**. 1. Copy the email address from the **Contacts** section. 1. Launch the profile creation wizard: ```bash yc init --username= ``` {% endlist %} 1. Select the profile you want to set up authentication for or create a new one. ```text Welcome! This command will take you through the configuration process. Pick desired action: [1] Re-initialize this profile 'default' with new settings [2] Create a new profile ``` 1. The CLI prompts you to continue authentication in the browser. Press **Enter** to continue. ```text You are going to be authenticated via userpool-id 'ek0auknfc0mh********'. Your userpool authentication web site will be opened. After your successful authentication, you will be redirected to cloud console. Press 'enter' to continue... ``` On successful authentication, an [IAM token](../../iam/concepts/authorization/iam-token.md) will be saved in the profile. This IAM token will be used to authenticate each operation until the end of the token's [lifetime](../../iam/concepts/authorization/iam-token.md) (not more than 12 hours). After that, the CLI will once again prompt you to authenticate in the browser. To extend the period during which you do not have to authenticate in the browser, use [refresh tokens](../../iam/concepts/authorization/refresh-token.md), which allow you to reissue IAM tokens without entering the browser. Do it by enabling refresh tokens [at the organization level](../../iam/concepts/authorization/refresh-token.md#token-enabling) and [initializing DPoP protection](../../iam/concepts/authorization/refresh-token.md#enabling-dpop) in the CLI. 1. Go back to the command line interface to finish creating the profile. 1. Select one of the [clouds](../../resource-manager/concepts/resources-hierarchy.md#cloud) from the list of those you have access to: ```text Please select cloud to use: [1] cloud1 (id = aoe2bmdcvata********) [2] cloud2 (id = dcvatao4faoe********) Please enter your numeric choice: 2 ``` If there is only one cloud available, it will be selected automatically. 1. Select the default [folder](../../resource-manager/concepts/resources-hierarchy.md#folder): ```text Please choose a folder to use: [1] folder1 (id = cvatao4faoe2********) [2] folder2 (id = tao4faoe2cva********) [3] Create a new folder Please enter your numeric choice: 1 ``` 1. To select the default [availability zone](../../overview/concepts/geo-scope.md) for [Compute Cloud](../../compute/index.md), type `Y`. To skip the setup, type `n`. ```bash Do you want to configure a default Yandex Compute Cloud availability zone? [Y/n] Y ``` If you typed `Y`, select the availability zone: ```text Which zone do you want to use as a profile default? [1] ru-central1-a [2] ru-central1-b [3] ru-central1-d [4] Do not set default zone Please enter your numeric choice: 2 ``` 1. View your CLI profile settings: ```bash yc config list ``` Result: {% list tabs %} - User pool ```bash userpool-id: ek0auknfc0mh******** subject-id: ek00cd1m8hdd8******** cloud-id: b1g159pa15cd******** folder-id: b1g8o9jbt58******** compute-default-zone: ru-central1-b ``` - Email ```bash subject-id: b1g159pa15cd******** username: folder-id: b1g8o9jbt58******** compute-default-zone: ru-central1-b ``` {% endlist %} {% endlist %} ## Test the Yandex Cloud CLI operation with Object Storage {% note info %} To enable debug output in the console, use the `--debug` flag. {% endnote %} ### Create a bucket {#create-bucket} The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id ` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions. 1. View the description of the CLI command to create a bucket: ```bash yc storage bucket create --help ``` 1. Create a bucket in the default folder: ```bash yc storage bucket create --name ``` Where `--name` is the name of the bucket. This is a required parameter. For more information, see [Bucket naming rules](../concepts/bucket.md#naming). By default, a bucket with a dot in the name is only available over HTTP. To provide HTTPS support for your bucket, [upload](../operations/hosting/certificate.md) your own security certificate to Object Storage. Result: ```text name: example folder_id: b1gmit33ngp6******** anonymous_access_flags: read: false list: false default_storage_class: STANDARD versioning: VERSIONING_DISABLED max_size: "53687091200" acl: {} created_at: "2022-12-16T14:05:12.196007Z" ``` {% cut "Optional parameters" %} * `--default-storage-class`: [Storage class](../concepts/storage-class.md). The possible values are: * `standard`: Standard storage. It is installed by default. * `cold`: Cold storage. * `ice`: Ice storage. Cold classes are designed to store [objects](../concepts/object.md) that you plan to use less frequently for longer periods of time. The colder the storage, the cheaper it is to store data in, but the more expensive it is to read from and write to it. * `--max-size`: Maximum bucket size, in bytes. The default value is `0` (unlimited). * Parameters for enabling [public access](../security/public-access.md) to a bucket: * `--public-read`: Enables public read access to bucket objects. * `--public-list`: Enables public view access to the list of bucket objects. * `--public-config-read`: Enables public read access to bucket settings. By default, public access to the bucket is disabled. {% note warning %} Public access is granted to an unlimited number of anonymous users. Use it only when other access grant mechanisms are not available. {% endnote %} * Parameters to configure the bucket [ACL](../concepts/acl.md): * `--acl`: Predefined ACL. For a list of possible values, see [Predefined ACLs](../concepts/acl.md#predefined-acls). You cannot use this parameter together with `--grants`. * `--grants`: This parameter configures permissions for individual users, [service accounts](../../iam/concepts/users/service-accounts.md), [user groups](../../organization/concepts/groups.md), and [public groups](../concepts/acl.md#public-groups) (a group of all internet users or a group of all authenticated Yandex Cloud users). You cannot use this parameter together with `--acl`. The parameter value is specified in the following format: `grant-type=,grantee-id=,permission=`, where: * `grant-type`: Permission grantee type. The possible values are: * `grant-type-account`: User, [service account](../../iam/concepts/users/service-accounts.md), or [user group](../../organization/concepts/groups.md). * `grant-type-all-authenticated-users`: [Public group](../concepts/acl.md#public-groups) that includes all authenticated Yandex Cloud users. * `grant-type-all-users`: Public group that includes all internet users. * `grantee-id`: ID of the user, service account, or user group you need to grant a permission to. It is specified only if `grant-type=grant-type-account`. * `permission`: ACL permission type. The possible values are `permission-full-control`, `permission-write`, and `permission-read`. Learn more about permissions in [Permission types](../concepts/acl.md#permissions-types). To configure multiple permissions, specify the `--grants` parameter multiple times. By default, an empty ACL is created for each new bucket. {% endcut %} Learn more about the `yc storage bucket create` command in the [YC CLI reference](../../cli/cli-ref/storage/cli-ref/bucket/create.md). ### Upload an object to the bucket {#upload-object} 1. See the description of the CLI command for uploading a file to a bucket: ```bash yc storage s3api put-object --help ``` 1. Get a list of buckets in the default folder: ```bash yc storage bucket list ``` Result: ```text +------------------+----------------------+-------------+-----------------------+---------------------+ | NAME | FOLDER ID | MAX SIZE | DEFAULT STORAGE CLASS | CREATED AT | +------------------+----------------------+-------------+-----------------------+---------------------+ | first-bucket | b1gmit33ngp6******** | 53687091200 | STANDARD | 2022-12-16 13:58:18 | +------------------+----------------------+-------------+-----------------------+---------------------+ ``` 1. Run this command: ```bash yc storage s3api put-object \ --body \ --bucket \ --key ``` Where: * `--body`: Path to the file you need to upload to the bucket. * `--bucket`: Name of your bucket. * `--key`: [Key](../concepts/object.md#key) by which to store the object in the bucket. Result: ```text etag: '"d41d8cd98f00b204e980099********"' request_id: 3f2705f******** ``` Alternative command: ```bash yc storage s3 cp \ \ s3:/// ``` Result: ```text upload: object.txt to s3://my-bucket/object.txt ``` {% cut "Configuring parameters for the `yc storage s3 cp` command" %} You can set the following parameters for the `yc storage s3 cp` command: * `s3.max-queue-size`: Maximum number of issues per queue. The default value is `1,000`. * `s3.max-concurrent-requests`: Maximum number of simultaneous requests. The default value is `10`. * `s3.multipart-threshold`: Object threshold size to trigger a multipart upload if exceeded. The default value is `8MB`. * `s3.multipart-chunksize`: Size of parts the object will be split into in a multipart upload. The default value is `8MB`. To set these parameters, use the `yc config set ` command. {% endcut %} ### Download an object from the bucket {#download-object} 1. See the description of the CLI command for downloading an object from a bucket: ```bash yc storage s3api get-object --help ``` 1. Get a list of buckets in the default folder: ```bash yc storage bucket list ``` Result: ```text +------------------+----------------------+-------------+-----------------------+---------------------+ | NAME | FOLDER ID | MAX SIZE | DEFAULT STORAGE CLASS | CREATED AT | +------------------+----------------------+-------------+-----------------------+---------------------+ | first-bucket | b1gmit33ngp6******** | 53687091200 | STANDARD | 2022-12-16 13:58:18 | +------------------+----------------------+-------------+-----------------------+---------------------+ ``` 1. Run this command: ```bash yc storage s3api get-object \ --bucket \ --key \ ``` Where: * `--bucket`: Name of your bucket. * `--key`: Object [key](../concepts/object.md#key). * ``: Local download path. Result: ```bash etag: '"d41d8cd98f00b204e9800998********"' request_id: af194b83******** accept_ranges: bytes content_type: application/octet-stream last_modified_at: "2024-10-08T12:36:36Z" server_side_encryption: aws:kms sse_kms_key_id: abj497vtg3h0******** ``` Alternative command: ```bash yc storage s3 cp \ s3:/// \ ``` Result: ```text download: s3://my-bucket/object.txt to object.txt ``` {% cut "Configuring parameters for the `yc storage s3 cp` command" %} You can set the following parameters for the `yc storage s3 cp` command: * `s3.max-queue-size`: Maximum number of issues per queue. The default value is `1,000`. * `s3.max-concurrent-requests`: Maximum number of simultaneous requests. The default value is `10`. * `s3.multipart-threshold`: Object threshold size to trigger a multipart upload if exceeded. The default value is `8MB`. * `s3.multipart-chunksize`: Size of parts the object will be split into in a multipart upload. The default value is `8MB`. To set these parameters, use the `yc config set ` command. {% endcut %}