[Yandex Cloud documentation](../index.md) > [Command line interface](index.md) > Getting started with the CLI # Getting started with the command line interface The _Yandex Cloud command line interface (CLI)_ is downloadable software you can use to manage your cloud resources via the command line. ## Installation {#install} This section provides a guide for interactive CLI installation using a script that: 1. Identifies your OS and architecture. 1. Downloads the executable with the latest stable CLI version for your environment. 1. Performs a health check. 1. Adds the CLI to the `PATH` environment variable. 1. Generates autocompletion settings. {% note tip %} To manually set up the CLI installation directory, autocompletion, and shell startup script, and add the CLI to the `PATH` environment variable, use the [non-interactive CLI installation script](operations/install-cli.md#non-interactive). You can also manually download and install the executable with the latest stable CLI version. For more information, see [Installation without using a script](operations/install-cli.md#bin). {% endnote %} {% 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](error.md#failure-writing-output-to-destination). ## Creating a profile {#initialize} {% 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 ``` - 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 %} ## Examples of commands {#example} See below for how to create a [cloud network](../vpc/concepts/network.md#network), a [subnet](../vpc/concepts/network.md#subnet), and a [VM](../compute/concepts/vm.md) connected to that subnet. 1. View the description of the CLI commands for working with cloud networks: ```bash yc vpc network --help ``` 1. Create a cloud network in the [folder](../resource-manager/concepts/resources-hierarchy.md#folder) specified in your CLI profile: ```bash yc vpc network create \ --name my-yc-network \ --labels my-label=my-value \ --description "my first network via yc" ``` 1. In the `my-yc-network` cloud network, create a subnet: ```bash yc vpc subnet create \ --name my-yc-subnet-a \ --zone ru-central1-a \ --range 10.1.2.0/24 \ --network-name my-yc-network \ --description "my first subnet via yc" ``` 1. Get a list of all cloud networks in the directory specified in your CLI profile: ```bash yc vpc network list ``` Result: ```text +----------------------+------------------+-------------------------+ | ID | NAME | DESCRIPTION | +----------------------+------------------+-------------------------+ | skesdqhkc644******** | my-ui-network | my first network via ui | | c6449hbqqar1******** | my-yc-network | my first network via yc | +----------------------+------------------+-------------------------+ ``` Get the same list with more details in YAML format: ```bash yc vpc network list --format yaml ``` Result: ```text - id: skesdqhkc644******** folder_id: ijkl9012 created_at: "2018-09-05T09:51:16Z" name: my-ui-network description: "my first network via ui" labels: {} - id: c6449hbqqar1******** folder_id: ijkl9012 created_at: "2018-09-05T09:55:36Z" name: my-yc-network description: "my first network via yc" labels: my-label: my-value ``` 1. Create a VM and connect it to `my-yc-subnet-a`: 1. [Create](../compute/operations/vm-connect/ssh.md#creating-ssh-keys) a key pair (public and private keys) for SSH access to the VM. 1. Create a Linux VM: ```bash yc compute instance create \ --name my-yc-instance \ --network-interface subnet-name=my-yc-subnet-a,nat-ip-version=ipv4 \ --zone ru-central1-a \ --ssh-key ~/.ssh/id_ed25519.pub ``` Where `ssh-key` is the path to a public key for SSH access. The VM will automatically create the `yc-user` user with the specified public key. 1. Connect to the VM over SSH: 1. Learn the [public IP address](../vpc/concepts/address.md#public-addresses) of the VM. To do this, view detailed information about your VM: ```bash yc compute instance get my-yc-instance ``` In the command output, find the address of the VM in the `one_to_one_nat` section: ```yaml one_to_one_nat: address: 130.193.32.90 ip_version: IPV4 ``` 1. Connect to the VM over SSH as `yc-user`, using the private key: ```bash ssh yc-user@130.193.32.90 ``` 1. Delete the `my-yc-instance` VM, `my-yc-subnet-a` subnet, and `my-yc-network` network: ```bash yc compute instance delete my-yc-instance yc vpc subnet delete my-yc-subnet-a yc vpc network delete my-yc-network ``` #### Useful links {#see-also} * [CLI update](operations/update-cli.md)