Getting started with the command-line interface

Written by

Improved by

Updated at October 1, 2024

Installation
Creating a profile
Examples of commands

The Yandex Cloud command-line interface (CLI) provides downloadable software for managing your cloud resources from the command line.

Installation

Linux

macOS

Windows

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.
After installation is complete, restart your terminal.

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

Install the Homebrew package manager.

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

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
```
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:

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"

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]
```
Enter Y.
Restart your terminal for the changes to take effect.

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

Creating a profile

Yandex account

Federated account

To get authenticated using a Yandex account:

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.
If authenticating for the first time, go to the cloud console. Accept the terms of the license agreement and privacy policy.
To initialize CLI profile setup, run this command:
```
yc init
```
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
```

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

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.

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

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-c
 [4] ru-central1-d
 [5] Do not set default zone
Please enter your numeric choice: 2

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:

Get your federation ID from your administrator.

Launch the profile creation wizard:

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

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

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.
Go back to the command line interface to finish creating the profile.

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.

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

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-c
 [4] ru-central1-d
 [5] Do not set default zone
Please enter your numeric choice: 2

View your CLI profile settings:

yc config list

Result:

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

Examples of commands

The following steps describe how to create a cloud network, subnet, and virtual machine that is connected to this subnet.

View the description of the CLI commands for working with cloud networks:
```
yc vpc network --help
```

Create a cloud network in the folder specified in your CLI profile:

yc vpc network create \
  --name my-yc-network \
  --labels my-label=my-value \
  --description "my first network via yc"

In the my-yc-network cloud network, create a subnet:

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"

Get a list of all cloud networks in the directory specified in your CLI profile:

yc vpc network list

Result:

+----------------------+------------------+-------------------------+
|          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:

yc vpc network list --format yaml

Result:

- 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

Create a VM and connect it to my-yc-subnet-a:
1. Prepare a key pair (public and private keys) for SSH access to the VM.
2. Create a Linux VM:
```
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.
Connect to the VM over SSH:
1. Find out the VM's public IP address. To do this, view detailed information about your VM:
```
yc compute instance get my-yc-instance
```
  In the command output, find the address of the VM in the one_to_one_nat section:
```
one_to_one_nat:
  address: 130.193.32.90
  ip_version: IPV4
```
2. Connect to the VM over SSH as yc-user, using the private key:
```
ssh yc-user@130.193.32.90
```

Delete the my-yc-instance VM, my-yc-subnet-a subnet, and my-yc-network network:

yc compute instance delete my-yc-instance
yc vpc subnet delete my-yc-subnet-a
yc vpc network delete my-yc-network

Getting started with the command-line interface

InstallationInstallation

Creating a profileCreating a profile

Examples of commandsExamples of commands

Was the article helpful?

Installation

Creating a profile

Examples of commands