Contact UsGet started

Command line interface (Yandex Cloud CLI)

Written by
Improved by
Updated at March 7, 2025

The Yandex Cloud CLI is downloadable software you can use to manage your cloud resources via the command line.

Install the Yandex Cloud CLI

  1. Run this command:

    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

    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.

    Warning

    For correct operation of the autocompletion feature 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.

  2. After installation is complete, restart your terminal.

  1. Run this command:

    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.

  2. Restart your terminal for the changes to take effect.

The CLI supports command autocompletion for the bash and zsh command shells. To enable command autocompletion:

  1. Install the Homebrew package manager.

  2. Install the zsh-completion package:

    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.

    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/<username>/yandex-cloud/path.bash.inc' ]; then source '/Users/<username>/yandex-cloud/path.bash.inc'; fi
# The next line enables shell command completion for yc.
if [ -f '/Users/<username>/yandex-cloud/completion.zsh.inc' ]; then source '/Users/<username>/yandex-cloud/completion.zsh.inc'; fi

  3. 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

  4. Restart your terminal.

For Windows, you can install the CLI using PowerShell or command line:

  • To install using PowerShell:

    1. Run this command:

      iex (New-Object System.Net.WebClient).DownloadString('https://storage.yandexcloud.net/yandexcloud-yc/install.ps1')

    2. 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]

    3. 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:

      @"%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"

    2. 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]

    3. Enter Y.

    4. Restart your terminal for the changes to take effect.

If you get an error during CLI installation, see CLI troubleshooting.

Get authenticated in the Yandex Cloud CLI

To access the Yandex Cloud CLI, get authenticated using one of the following methods:

To get authenticated using a Yandex account:

  1. Get an OAuth token in Yandex ID:

    1. Click the link. If the application requests access to data, permit it. You need to do this to get a token.

    2. Copy the token to the clipboard or save it.

  2. If authenticating for the first time, go to the cloud console. Accept the terms of the license agreement and privacy policy.

  3. To initialize CLI profile setup, run this command:

    yc init

  4. Select the profile you want to set up authentication for or create a new one. If it is your first time running the yc init command, this step will be skipped.

    Pick desired action:
[1] Re-initialize this profile 'default' with new settings
[2] Create a new profile
Please enter your numeric choice: 1

  5. Enter the previously obtained OAuth token when prompted by the command:

    Please go to https://oauth.yandex.com/authorize?response_type=token&client_id=1a6990aa636648e9b2ef855fa7bec2fb
in order to obtain OAuth token.

Please enter OAuth token: y0_AgA ... wvs7N4

  6. Select one of the clouds from the list of those you have access to:

    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.

  7. Select the default folder:

    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

  8. To select the default availability zone for Compute Cloud, type Y. To skip the setup, type n.

    Do you want to configure a default Yandex Compute Cloud availability zone? [Y/n] Y

    If you chose Y, select the availability zone:

    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

  9. View your CLI profile settings:

    yc config list

    Result:

    token: y0_AgA...wvs7N4
cloud-id: b1g159pa15cd********
folder-id: b1g8o9jbt58********
compute-default-zone: ru-central1-b

To authenticate using a SAML-compatible identity federation:

  1. Get your federation ID from your administrator.

  2. Launch the profile creation wizard:

    yc init \
   --federation-endpoint auth.cloud.yandex.com \
   --federation-id <federation_ID>

  3. Select the profile you want to set up authentication for or create a new one.

    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

  4. The CLI prompts you to continue authentication in the browser. Press Enter to continue.

    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, the IAM token is saved in the profile. This token is used to authenticate each operation until the token expires. After that, the CLI again displays a prompt to authenticate in the browser.

  5. Go back to the command line interface to finish creating the profile.

  6. Select one of the clouds from the list of those you have access to:

    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.

  7. Select the default folder:

    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

  8. To select the default availability zone for Compute Cloud, type Y. To skip the setup, type n.

    Do you want to configure a default Yandex Compute Cloud availability zone? [Y/n] Y

    If you typed Y, select the availability zone:

    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

  9. View your CLI profile settings:

    yc config list

    Result:

    federation-id: aje1f0hs6oja********
cloud-id: b1g159pa15cd********
folder-id: b1g8o9jbt58********
compute-default-zone: ru-central1-b

To authenticate as a service account:

  1. Get a list of service accounts that exist in your cloud:

    yc iam service-account --folder-id <folder_ID> list

    Result:

    +----------------------+------------+
|          ID          |    NAME    |
+----------------------+------------+
| aje3932acd0c5ur7dagp | default-sa |
+----------------------+------------+

  2. Create an authorized key for the service account and save it to the key.json file:

    yc iam key create --service-account-name default-sa --output key.json --folder-id <folder_ID>

    Result:

    id: aje83v701b1un777sh40
service_account_id: aje3932acd0c5ur7dagp
created_at: "2019-08-26T12:31:25Z"
key_algorithm: RSA_2048

  3. Add the service account authorized key to the CLI profile.

    1. Create a new CLI profile:

      yc config profile create sa-profile

    2. Add an authorized key:

      yc config set service-account-key key.json

  4. Make sure that the service account parameters are added correctly:

    yc config list

    Result:

    service-account-key:
  id: aje83v701b1un777sh40
  service_account_id: aje3932acd0c5ur7dagp
  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-----

  5. 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:

      yc config set cloud-id <cloud_ID>

      You can also use the --cloud-id parameter to run commands.

    2. Specify a folder in the profile:

      yc config set folder-id <folder_ID>

      You can also use the --folder-id parameter to run commands.

    All operations in this profile will be performed on behalf of the linked service account. You can change the profile parameters or switch to another profile.

Test the Yandex Cloud CLI operation with Object Storage

Note

To enable debug output in the console, use the --debug key.

Create a bucket

The folder specified in the CLI profile is used by default. You can specify a different folder through the --folder-name or --folder-id parameter.

  1. View the description of the CLI command to create a bucket:

    yc storage bucket create --help

  2. Create a bucket in the default folder:

    yc storage bucket create --name <bucket_name>

    Where --name is the name of the bucket. This is a required parameter. For more information, see Bucket naming rules.

    By default, a bucket with a dot in the name is only available over HTTP. To provide HTTPS support for your bucket, upload your own security certificate to Object Storage.

    Result:

    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"
    Optional parameters
    • --default-storage-class: Storage class. 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 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 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.

    Warning

    Public access is granted to an unlimited number of anonymous users. Use it only when other access grant mechanisms are not available.

    • Parameters to configure the bucket ACL:

    • --acl: Predefined ACL. For a list of possible values, see Predefined ACLs. You cannot use this parameter together with --grants.

    • --grants: This parameter configures permissions for individual users, service accounts, user groups, and 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=<permission_grantee_type>,grantee-id=<grantee_ID>,permission=<permission_type>, where:

      • grant-type: Permission grantee type. The possible values are:
      • grant-type-account: User, service account, or user group.
      • grant-type-all-authenticated-users: Public group 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.

      To configure multiple permissions, specify the --grants parameter multiple times.

    By default, an empty ACL is created for each new bucket.

    Learn more about the yc storage bucket create command in the YC CLI reference.

Upload an object to the bucket

  1. See the description of the CLI command for uploading a file to a bucket:

    yc storage s3api put-object --help

  2. Get a list of buckets in the default folder:

    yc storage bucket list

    Result:

    +------------------+----------------------+-------------+-----------------------+---------------------+
|       NAME       |      FOLDER ID       |  MAX SIZE   | DEFAULT STORAGE CLASS |     CREATED AT      |
+------------------+----------------------+-------------+-----------------------+---------------------+
| first-bucket     | b1gmit33ngp6******** | 53687091200 | STANDARD              | 2022-12-16 13:58:18 |
+------------------+----------------------+-------------+-----------------------+---------------------+

  3. Run this command:

    yc storage s3api put-object \
  --body <local_file_path> \
  --bucket <bucket_name> \
  --key <object_path>

    Where:

    • --body: Path to the file you need to upload to the bucket.
    • --bucket: Name of your bucket.
    • --key: Key to use for storing the object in the bucket.

    Result:

    etag: '"d41d8cd98f00b204e980099********"'
request_id: 3f2705f********

Download an object from the bucket

  1. See the description of the CLI command for downloading an object from a bucket:

    yc storage s3api get-object --help

  2. Get a list of buckets in the default folder:

    yc storage bucket list

    Result:

    +------------------+----------------------+-------------+-----------------------+---------------------+
|       NAME       |      FOLDER ID       |  MAX SIZE   | DEFAULT STORAGE CLASS |     CREATED AT      |
+------------------+----------------------+-------------+-----------------------+---------------------+
| first-bucket     | b1gmit33ngp6******** | 53687091200 | STANDARD              | 2022-12-16 13:58:18 |
+------------------+----------------------+-------------+-----------------------+---------------------+

  3. Run this command:

    yc storage s3api get-object \
  --bucket <bucket_name> \
  --key <object_key> \
  <download_path>

    Where:

    • --bucket: Name of your bucket.
    • --key: Object key.
    • <download_path>: Local download path.

    Result:

    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********
Previous
All tools
Next
AWS CLI