Getting started with the command-line interface

Written by

Yandex.Cloud

improved by

Pushkin

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 the command:
```
$ curl https://storage.yandexcloud.net/yandexcloud-yc/install.sh | bash
```
The script will install the CLI and add the executable file path to the environment variable PATH.

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 path to the CLI to the variable PATH yourself.
After installation is complete, restart your terminal.

Run the command:
```
$ curl https://storage.yandexcloud.net/yandexcloud-yc/install.sh | bash
```
The script will install the CLI and add the executable file path to the environment variable PATH.
Restart your terminal for the changes to take effect.

The CLI supports command completion for the bash shell. For command completion to work:

Install the Homebrew package manager.

Install the bash-completion package:

$ brew install bash-completion

The installation script will update the ~/.bash_profile 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.bash.inc' ]; then source '/Users/<username>/yandex-cloud/completion.bash.inc'; fi

After the installation is complete, add the following lines to the ~/.bash_profile file. Insert them above the lines automatically added by the installation script.
```
if [ -f $(brew --prefix)/etc/bash_completion ]; then
. $(brew --prefix)/etc/bash_completion
fi
```
Restart your terminal.

For Windows, the CLI can be installed using PowerShell and cmd:

To install using PowerShell:
1. Run the 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 cmd:

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

Creating a profile

If you aren't connected to the management console yet, log in to the management console and accept the user agreement by clicking Log in.

As a user

As a service account

As a federated user

To authenticate as a user:

Get an OAuth token from Yandex.OAuth. To do this, go to the link and click Allow.
To configure your CLI profile, run the command yc init.

Enter your 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: AaAaBbBbCcCcDdDdEeEeFfFfGgGg

At the command prompt, select one of the clouds from the list of those you have access to:
```
Please select cloud to use:
 [1] cloud1 (id = aoe2bmdcvatao4frg22b)
 [2] cloud2 (id = dcvatao4faoe2bmrg22b)
Please enter your numeric choice: 2
```
If only one cloud is available, it's selected automatically.

Select the default folder:

Please choose a folder to use:
 [1] folder1 (id = cvatao4faoe2bmdrg22b)
 [2] folder2 (id = tao4faoe2cvabmdrg22b)
 [3] Create a new folder
Please enter your numeric choice: 1

Select the default availability zone for Yandex Compute Cloud:

Do you want to configure a default Yandex Compute Cloud availability zone? [Y/n] Y
Which zone do you want to use as a profile default?
 [1] ru-central1-a
 [2] ru-central1-b
 [3] ru-central1-c
 [4] Don't set default zone
Please enter your numeric choice: 2

View your CLI profile settings:
```
$ yc config list
```

Before you start, get your service account ready:

Authenticate in the CLI as a user.
If you don't have a service account yet, create one and configure access.

To authenticate as a service account:

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

$ yc iam service-account --folder-id <folder ID> list
+----------------------+------------+
|          ID          |    NAME    |
+----------------------+------------+
| aje3932acd0c5ur7dagp | default-sa |
+----------------------+------------+

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
id: aje83v701b1un777sh40
service_account_id: aje3932acd0c5ur7dagp
created_at: "2019-08-26T12:31:25Z"
key_algorithm: RSA_2048

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

Make sure that the service account parameters are added correctly:

$ yc config list
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-----

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>
```
  Or run commands with the --cloud-id parameter.
2. Specify a folder in the profile:
```
$ yc config set folder-id <folder ID>
```
  Or use the --folder-id parameter in your 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.

To authenticate using an SAML-compatible identity federation:

Get your federation ID from your administrator.

Launch the profile creation wizard:

yc init --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 'aje1f0hsgds3aas2f6ai2'.
Your federation authentication web site will be opened.
After your successful authentication, you will be redirected to 'https://console.cloud.yandex.com'.

Press 'enter' to continue...
```
On successful authentication on the federation server, 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 the default folder:

Please choose a folder to use:
 [1] folder1 (id = cvatao4faoe2bmdrg22b)
 [2] folder2 (id = tao4faoe2cvabmdrg22b)
 [3] Create a new folder
Please enter your numeric choice: 1

Select the default availability zone for Yandex Compute Cloud:

Do you want to configure a default Yandex Compute Cloud availability zone? [Y/n] Y
Which zone do you want to use as a profile default?
 [1] ru-central1-a
 [2] ru-central1-b
 [3] ru-central1-c
 [4] Don't set default zone
Please enter your numeric choice: 2

View your CLI profile settings:

$ yc config list
federation-id: aje1f0hs6ojais2f6ai2
...

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"

Create a subnet in the cloud network my-yc-network:

$ yc vpc subnet create \
    --name my-yc-subnet-b \
    --zone ru-central1-b \
    --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

+----------------------+------------------+-------------------------+
|          ID          |       NAME       |       DESCRIPTION       |
+----------------------+------------------+-------------------------+
| skesdqhkc6449hbqqar1 | my-ui-network    | my first network via ui |
| c6449hbqqar1skesdqhk | my-yc-network    | my first network via yc |
+----------------------+------------------+-------------------------+

Get the same list with more details in YAML format:

$ yc vpc network list --format yaml

- id: skesdqhkc6449hbqqar1
  folder_id: ijkl9012
  created_at: "2018-09-05T09:51:16Z"
  name: my-ui-network
  description: "my first network via ui"
  labels: {}
- id: c6449hbqqar1skesdqhk
  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 virtual machine and connect it to the subnet my-yc-subnet-b:
1. Prepare the key pair (public and private keys) for SSH access to the VM.
2. Create a virtual machine:
```
$ yc compute instance create \
    --name my-yc-instance \
    --network-interface subnet-name=my-yc-subnet-b,nat-ip-version=ipv4 \
    --zone ru-central1-b \
	  --ssh-key ~/.ssh/id_rsa.pub
```
  Pass the path to the public key for SSH access in the ssh-key parameter. The yc-user user will be automatically created in the virtual machine OS with the specified public key.
Connect to the virtual machine over SSH:
1. Find out the public IP address of the virtual machine. To do this, view detailed information about your virtual machine:
```
$ 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 virtual machine over SSH on behalf of the yc-user user, using the private key:
```
$ ssh yc-user@130.193.32.90
```

Delete the my-yc-instance virtual machine, the my-yc-subnet-b subnet and the my-yc-network network:

$ yc compute instance delete my-yc-instance
$ yc vpc subnet delete my-yc-subnet-b
$ yc vpc network delete my-yc-network

Getting started with the command-line interface

Installation

Creating a profile

Examples of commands

Was the article helpful?