Getting started with the Yandex Cloud command line interface (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.

   This command runs the installation script using bash. The script detects the user's command shell via the SHELL variable and adds the configurations for zsh to ~/.zshrc.

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

For Windows, you can install the CLI using PowerShell or cmd.exe. In both cases, the installation script runs in PowerShell.

• Installation using PowerShell:

  1. Run this command:

     Invoke-Expression (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.

• Installation from cmd.exe:

  1. Run this command:

     @"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -Command "Invoke-Expression ((New-Object System.Net.WebClient).DownloadString('https://storage.yandexcloud.net/yandexcloud-yc/install.ps1'))" && SET "PATH=%PATH%;%USERPROFILE%\yandex-cloud\bin"
     

  2. When prompted by the installation script, confirm whether to add the yc path 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.

For more information, see Working with the Yandex Cloud CLI and API in Microsoft Windows.

To enable autocompletion:

1. Open ~/.zshrc and add the following lines to the beginning of the file:

   autoload -Uz compinit
   compinit
   

   The yc installation script adds CLI initialization and autocompletion lines to the end of ~/.zshrc. Place the autoload and compinit calls above these lines; otherwise, you will get the command not found: compdef error when you start the terminal.

   The final ~/.zshrc should look as follows:

   autoload -Uz compinit
   compinit
   
   # The lines below were added automatically by the yc installation script.
   if [ -f "$HOME/yandex-cloud/path.bash.inc" ]; then source "$HOME/yandex-cloud/path.bash.inc"; fi
   if [ -f "$HOME/yandex-cloud/completion.zsh.inc" ]; then source "$HOME/yandex-cloud/completion.zsh.inc"; fi
   
   Installing extended autocompletions

   The zsh-completions package extends the system's basic autocompletions. It is not required for the yc autocompletion.

   To install the package:

   1. Install Homebrew.

   2. Install the zsh-completions package:

      brew install zsh-completions
      

      Tip

      If using bash, install the bash-completion package instead of zsh-completions.

   3. Add a section with FPATH before the autoload and compinit lines. The final ~/.zshrc should look as follows:

      if type brew &>/dev/null; then
        FPATH=$(brew --prefix)/share/zsh-completions:$FPATH
      fi
      autoload -Uz compinit
      compinit
      
      # The lines below were added automatically by the yc installation script.
      if [ -f "$HOME/yandex-cloud/path.bash.inc" ]; then source "$HOME/yandex-cloud/path.bash.inc"; fi
      if [ -f "$HOME/yandex-cloud/completion.zsh.inc" ]; then source "$HOME/yandex-cloud/completion.zsh.inc"; fi
      

2. Restart the command shell or run the exec -l $SHELL command.

3. Check that autocompletion works: type yc and press Tab twice. A list of available commands should appear.

winget install Microsoft.PowerShell

To enable autocompletion in PowerShell:

1. If you do not have a PowerShell profile, create one and open it in a text editor:

   New-Item -Path $PROFILE -Type File -Force
   notepad $PROFILE
   

   Instead of notepad, you can use any editor you prefer. For example, for VS Code, use the code $PROFILE command.

2. Add the following code to the file and save it:

   Register-ArgumentCompleter -Native -CommandName yc -ScriptBlock {
       param($wordToComplete, $commandAst, $cursorPosition)
   
       $elements = $commandAst.CommandElements
       $allTokens = $elements | Select-Object -Skip 1 | ForEach-Object { $_.ToString() }
       $allTokens = $allTokens | Where-Object { $_ -match '^[\x20-\x7E]+$' }
   
       if ($wordToComplete -ne '') {
           $completedTokens = $allTokens | Select-Object -SkipLast 1
           $queryTokens = @($completedTokens) + @("")
       } else {
           $queryTokens = @($allTokens) + @("")
       }
   
       $result = yc __completeNoDesc @queryTokens 2>$null
   
       $completions = $result | Where-Object {
           $_ -notmatch '^\:' -and $_ -notmatch '^Completion'
       } | Where-Object {
           $_.StartsWith($wordToComplete)
       }
   
       if ($completions.Count -eq 0 -and $wordToComplete -ne '') {
           $queryTokensFallback = @($completedTokens) + @($wordToComplete)
           $resultFallback = yc __completeNoDesc @queryTokensFallback 2>$null
   
           $completions = $resultFallback | Where-Object {
               $_ -notmatch '^\:' -and $_ -notmatch '^Completion'
           } | Where-Object {
               $_.StartsWith($wordToComplete)
           }
       }
   
       $completions | ForEach-Object {
           $parts = $_ -split '\t'
           [System.Management.Automation.CompletionResult]::new(
               $parts[0], $parts[0], 'ParameterValue', $parts[0]
           )
       }
   }
   

   Note

   By default, pressing Tab in PowerShell suggests the options one by one. To open a menu with all options and tooltips instead, add the following lines to the top of the file:

   Set-PSReadLineOption -ShowToolTips
   Set-PSReadLineKeyHandler -Key Tab -Function MenuComplete
   

   These lines change the Tab behavior in all PowerShell commands, not just yc.

3. Restart PowerShell. Check that autocompletion works: type yc and press Tab. A list of available commands should appear.

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-id=<federation_ID>
   

   Note

   If the server has no GUI or browser, you will get the following error:

   ERROR: fill default credentials: federation id authentication is not supported on this system because the browser can not be opened
   

   Authenticate using a service account. Alternatively, you can use an SSH tunnel or X11 forwarding.

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, an IAM token will be saved in the profile. This IAM token will be used to authenticate each operation until the end of the token's lifetime (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, which allow you to reissue IAM tokens without entering the browser. Do it by enabling refresh tokens at the organization level and initializing DPoP protection in the CLI.

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********
   subject-id: ajea53egl28l********
   cloud-id: b1g159pa15cd********
   folder-id: b1g8o9jbt58********
   compute-default-zone: ru-central1-b
   

To authenticate using a local user account:

1. Launch the profile creation wizard:

   User pool

   Email

   1. Get your user pool ID from your administrator.

   2. Launch the profile creation wizard:

      yc init --userpool-id=<user_pool_ID>
      

   1. Get your email address:

      1. Go to the My account portal.
      2. In the left-hand panel, select  Profile.
      3. Copy the email address from the Contacts section.

   2. Launch the profile creation wizard:

      yc init --username=<email_address>
      

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

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

   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 will be saved in the profile. This IAM token will be used to authenticate each operation until the end of the token's lifetime (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, which allow you to reissue IAM tokens without entering the browser. Do it by enabling refresh tokens at the organization level and initializing DPoP protection in the CLI.

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

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

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

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

8. View your CLI profile settings:

   yc config list
   

   Result:

   User pool

   Email

   userpool-id: ek0auknfc0mh********
   subject-id: ek00cd1m8hdd8********
   cloud-id: b1g159pa15cd********
   folder-id: b1g8o9jbt58********
   compute-default-zone: ru-central1-b
   

   subject-id: b1g159pa15cd********
   username: <email_address>
   folder-id: b1g8o9jbt58********
   compute-default-zone: ru-central1-b