ydb docs cli commands list, scheme-ls

ref:f0a1bd2979b0778ee3df177c73fb871329ae3768

12 files changed, 152 insertions, 180 deletions

diff --git a/ydb/docs/ru/core/getting_started/_includes/cli/ls_example_generic.md b/ydb/docs/ru/core/getting_started/_includes/cli/ls_example_generic.md
index 2b071300db..14cb78cf81 100644
--- a/ydb/docs/ru/core/getting_started/_includes/cli/ls_example_generic.md
+++ b/ydb/docs/ru/core/getting_started/_includes/cli/ls_example_generic.md
@@ -1,11 +1,11 @@
 Например, если: 
-* Эндпоинт: grpc://ydb.aerosmith.com:2136
+* Эндпоинт: grpc://ydb.example.com:2136
 * Имя базы данных: /john/db1
 * База данных не требует аутентификации, или задана нужная переменная окружения, как описано [здесь](../../auth.md).
 * База данных только что создана и не содержит объектов
 
 То команда и результат выполнения будут выглядеть следующим образом:
 ``` bash
-$ {{ ydb-cli }} -e grpc://ydb.aerosmith.com:2136 -d /john/db1 scheme ls
+$ {{ ydb-cli }} -e grpc://ydb.example.com:2136 -d /john/db1 scheme ls
 .sys
 ```
diff --git a/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md b/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md
new file mode 100644
index 0000000000..83685314c8
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-cli/_includes/commands.md
@@ -0,0 +1,75 @@
+# Команды YDB CLI
+
+Общий синтаксис вызова команд YDB CLI:
+
+``` bash
+{{ ydb-cli }} [global options] <command> [<subcommand> ...] [command options]
+```
+
+, где:
+
+- `{{ ydb-cli}}` - команда запуска YDB CLI из командной строки операционной системы
+- `[global options]` - [глобальные опции](../commands/global-options.md), одинаковые для всех команд YDB CLI
+- `<command>` - команда
+- `[<subcomand>  ...]` - подкоманды, указываемые в случае если выбранная команда содержит подкоманды
+- `[command options]` - опции команды, специфичные для каждой команды и подкоманд
+
+## Команды {#list}
+
+Вы можете ознакомиться с нужными командами выбрав тематический раздел в меню слева, или воспользовавшись алфавитным перечнем ниже.
+
+Любая команда может быть вызвана в командной строке с опцией `--help` для получения справки по ней. Перечень всех поддерживаемых YDB CLI команд может быть получен запуском YDB CLI с опцией `--help` [без указания команды](../commands/service.md).
+
+Команда / подкоманда | Краткое описание
+--- | ---
+[config profile activate](../profile/activate.md) | Активация [профиля](../profile/index.md)
+[config profile create](../profile/create.md) | Создание [профиля](../profile/index.md)
+[config profile delete](../profile/create.md) | Удаление [профиля](../profile/index.md)
+[config profile get](../profile/list-and-get.md) | Получение параметров [профиля](../profile/index.md)
+[config profile list](../profile/list-and-get.md) | Список [профилей](../profile/index.md)
+[config profile set](../profile/activate.md) | Активация [профиля](../profile/index.md)
+[discovery list](../commands/discovery-list.md) | Список эндпоинтов
+[discovery whoami](../commands/discovery-whoami.md) | Проверка аутентификации
+export s3 | Экспорт данных в хранилище S3
+import file csv | Импорт данных из CSV-файла
+import file tsv | Импорт данных из TSV-файла
+import s3 | Импорт данных из хранилища S3
+[init](../profile/create.md) | Инициализация CLI, создание [профиля](../profile/index.md)
+operation cancel | Прерывание исполнения долгой операции
+operation forget | Удалить долгую операцию из истории
+operation get | Статус долгой операции
+operation list | Список долгих операций
+[scheme describe](../commands/scheme-describe.md) | Описание объекта схемы данных
+[scheme ls](../commands/scheme-ls.md) | Список объектов схемы данных
+[scheme mkdir](../commands/dir.md#mkdir) | Создание директории
+scheme permissions add | Предоставление разрешения
+scheme permissions chown | Изменение владельца объекта
+scheme permissions clear | Очистка разрешений
+scheme permissions grant | Предоставление разрешения
+scheme permissions remove | Удаление разрешения
+scheme permissions revoke | Удаление разрешения
+scheme permissions set | Установка разрешений
+[scheme rmdir](../commands/dir.md#rmdir) | Удаление директории
+scripting yql | Выполнение YQL-скрипта
+table attribute add | Добавление атрибута таблицы
+table attribute drop | Удаление атрибута таблицы
+table drop | Удаление таблицы
+[table index add global](../commands/operations-index.md) | Добавление синхронного индекса 
+[table index add global-async](../commands/operations-index.md) | Добавление асинхронного индекса 
+[table index add global-sync](../commands/operations-index.md) | Добавление синхронного индекса 
+[table index drop](../commands/operations-index.md) | Удаление индекса
+[table query execute](../commands/query.md) | Исполнение YQL-запроса
+[table query explain](../commands/explain-plan.md) | План исполнения YQL-запроса
+[table readtable](../commands/readtable.md) | Потоковое чтение таблицы
+table ttl drop  | Удаление параметров TTL
+table ttl set  | Установка параметров TTL
+tools copy | Копирование таблиц
+tools dump | Выгрузка директории или таблицы в файловую систему
+[tools rename](../commands/tools/rename.md) | Переменование таблиц
+tools restore | Восстановление из файловой системы
+{% if ydb-cli == "ydb" %}
+[update](../commands/service.md) | Обновление YDB CLI
+[version](../commands/service.md) | Вывод информации о версии YDB CLI
+{% endif %}
+yql | Выполнение YQL-скрипта (с поддержкой стриминга)
+
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands.md b/ydb/docs/ru/core/reference/ydb-cli/commands.md
new file mode 100644
index 0000000000..67f9942c09
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-cli/commands.md
@@ -0,0 +1,2 @@
+{% include [commands.md](_includes/commands.md) %}
+
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/commands/all-output.md b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/commands/all-output.md
deleted file mode 100644
index 46cb9435e4..0000000000
--- a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/commands/all-output.md
+++ /dev/null
@@ -1,123 +0,0 @@
-```text
-YDB client
-
-Usage: ydb [options...] <subcommand>
-
-Subcommands:
-ydb
-├─ config                   Manage YDB CLI configuration
-│  └─ profile               Manage configuration profiles
-│     ├─ activate           Activate specified configuration profile (aliases: set)
-│     ├─ create             Create new configuration profile or re-configure existing one
-│     ├─ delete             Delete specified configuration profile (aliases: remove)
-│     ├─ get                List values for specified configuration profile
-│     └─ list               List configuration profiles
-├─ discovery                Discovery service operations
-│  ├─ list                  List endpoints
-│  └─ whoami                Who am I?
-├─ export                   Export service operations
-│  └─ s3                    Create export to S3
-├─ import                   Import service operations
-│  ├─ file                  Import data from file
-│  │  ├─ csv                Import data from CSV file
-│  │  └─ tsv                Import data from TSV file
-│  └─ s3                    Create import from S3
-├─ init                     YDB CLI initialization
-├─ operation                Operation service operations
-│  ├─ cancel                Start cancellation of a long-running operation
-│  ├─ forget                Forget long-running operation
-│  ├─ get                   Check status for a given operation
-│  └─ list                  List operations of specified kind
-├─ scheme                   Scheme service operations
-│  ├─ describe              Show information about object at given object
-│  ├─ ls                    Show information about objects inside given directory
-│  ├─ mkdir                 Make directory
-│  ├─ permissions           Modify permissions
-│  │  ├─ chown              Change owner
-│  │  ├─ clear              Clear permissions
-│  │  ├─ grant              Grant permission (aliases: add)
-│  │  ├─ revoke             Revoke permission (aliases: remove)
-│  │  └─ set                Set permissions
-│  └─ rmdir                 Remove directory
-├─ scripting                Scripting service operations
-│  └─ yql                   Execute YQL script
-├─ table                    Table service operations
-│  ├─ attribute             Attribute operations (aliases: attr)
-│  │  ├─ add                Add attributes to the specified table
-│  │  └─ drop               Drop attributes from the specified table
-│  ├─ drop                  Drop a table
-│  ├─ index                 Index operations
-│  │  ├─ add                Add index in to the specified table
-│  │  │  ├─ global-async    Add global async index. The command returns operation
-│  │  │  └─ global-sync     Add global sync index. The command returns operation (aliases: global)
-│  │  └─ drop               Drop index from the specified table
-│  ├─ query                 Query operations
-│  │  ├─ execute            Execute query (aliases: exec)
-│  │  └─ explain            Explain query
-│  ├─ readtable             Stream read table
-│  └─ ttl                   Ttl operations
-│     ├─ drop               Drop ttl settings from the specified table
-│     └─ set                Set ttl settings for the specified table
-├─ tools                    YDB tools service
-│  ├─ copy                  Copy table(s)
-│  ├─ dump                  Dump specified database directory or table into local directory
-│  ├─ rename                Rename or repalce table(s)
-│  └─ restore               Restore database from local dump into specified directory
-├─ update                   Update current YDB CLI binary if there is a newer version available
-├─ version                  Print Yandex.Cloud YDB CLI version
-└─ yql                      Execute YQL script (streaming)
-
-
-Options:
-  {-?|-h|--help}        Print usage
-  {-e|--endpoint} [PROTOCOL://]HOST[:PORT]
-                        [Required] Endpoint to connect. Protocols: grpc, grpcs (Default: grpcs).
-                          Endpoint search order:
-                            1. This option
-                            2. Profile specified with --profile option
-                            3. Active configuration profile
-  {-d|--database} PATH  [Required] Database to work with.
-                          Database search order:
-                            1. This option
-                            2. Profile specified with --profile option
-                            3. Active configuration profile
-  {-v|--verbose}        Increase verbosity of operations (default: 0)
-  --ca-file PATH        Path to a file containing the PEM encoding of the server root certificates for tls connections.
-                        If this parameter is empty, the default roots will be used.
-  --iam-token-file PATH IAM token file. Note: IAM tokens expire in 12 hours.
-                          For more info go to: cloud.yandex.ru/docs/iam/concepts/authorization/iam-token
-                          Token search order:
-                            1. This option
-                            2. Profile specified with --profile option
-                            3. "IAM_TOKEN" environment variable
-                            4. Active configuration profile
-  --yc-token-file PATH  YC token file. It should contain OAuth token of a Yandex Passport user to get IAM token with.
-                          For more info go to: cloud.yandex.ru/docs/iam/concepts/authorization/oauth-token
-                          Token search order:
-                            1. This option
-                            2. Profile specified with --profile option
-                            3. "YC_TOKEN" environment variable
-                            4. Active configuration profile
-  --use-metadata-credentials
-                        Use metadata service on a virtual machine to get credentials
-                          For more info go to: cloud.yandex.ru/docs/compute/operations/vm-connect/auth-inside-vm
-                          Definition priority:
-                            1. This option
-                            2. Profile specified with --profile option
-                            3. "USE_METADATA_CREDENTIALS" environment variable
-                            4. Active configuration profile (default: 0)
-  --sa-key-file PATH    Service account key file
-                          For more info go to: cloud.yandex.ru/docs/iam/operations/iam-token/create-for-sa
-                          Definition priority:
-                            1. This option
-                            2. Profile specified with --profile option
-                            3. "SA_KEY_FILE" environment variable
-                            4. Active configuration profile
-  --iam-endpoint STR    Endpoint of IAM service (default: "iam.api.cloud.yandex.net")
-  --profile NAME        Profile name to use configuration parameters from.
-  --license             Print license
-  --credits             Print third-party licenses
-
-Free args: min: 1, max: unlimited
-  <subcommand>  config,discovery,export,import,init,operation,scheme,scripting,table,tools,update,version,yql
-```
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/commands/all.md b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/commands/all.md
deleted file mode 100644
index 2a4edcb4be..0000000000
--- a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/commands/all.md
+++ /dev/null
@@ -1,7 +0,0 @@
-## Получение общей информации обо всех подкомандах {{ ydb-short-name }} CLI {#all}
-
-Получите список всех доступных подкоманд {{ ydb-short-name }} CLI с кратким описанием:
-
-```bash
-{{ ydb-cli }} --help
-```
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/commands/intro.md b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/commands/intro.md
deleted file mode 100644
index 3df624a91b..0000000000
--- a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/commands/intro.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Структура и описание команд {{ ydb-short-name }} CLI
-
-Получите информацию обо всех доступных командах {{ ydb-short-name }} CLI или узнайте подробное описание конкретной команды.
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/commands/one.md b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/commands/one.md
deleted file mode 100644
index 7ef6de07c1..0000000000
--- a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/commands/one.md
+++ /dev/null
@@ -1,29 +0,0 @@
-## Получение детальной информации о подкомандах {{ ydb-short-name }} CLI {#one}
-
-Для любой подкоманды также можно получить более подробное описание со списком доступных параметров:
-
-```bash
-{{ ydb-cli }} discovery whoami --help
-```
-
-Результат:
-
-```text
-Usage: ydb [global options...] discovery whoami [options...]
-
-Description: Who am I?
-
-Global options:
-  {-e|--endpoint}, {-d|--database}, {-v|--verbose}, --ca-file, --iam-token-file, --yc-token-file, --use-metadata-credentials, --sa-key-file, --iam-endpoint, --profile, --license, --credits
-  To get full description of these options run 'ydb --help'.
-
-Options:
-  {-?|-h|--help}      print usage
-  --client-timeout ms Operation client timeout
-  {-g|--groups}       With groups (default: 0)
-```
-
-Передаваемые параметры делятся на два типа:
-
-* `Global options` — глобальные, указываются после `ydb`.
-* `Options` — опции подкоманды, указываются после подкоманды.
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/dir.md b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/dir.md
index e9c185a650..fba0d59e49 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/dir.md
+++ b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/dir.md
@@ -16,6 +16,15 @@ YDB CLI поддерживает операции изменения струк�
 
 В параметре `path` указывается относительный путь создаваемой директории от корня директорий базы данных. Будут созданы все директории на этом пути, которые не существовали до момента вызова команды.
 
+Если конечная директория на пути уже существовала, то выполнение команды завершится успешно (код результата 0) с выдачей предупреждения о том, что никаких изменений не было произведено:
+
+``` text
+Status: SUCCESS
+Issues: 
+<main>: Error: dst path fail checks, path: /<database>/<path>: path exist, request accepts it, 
+pathId: [OwnerId: <some>, LocalPathId: <some>], path type: EPathTypeDir, path state: EPathStateNoChanges
+```
+
 Также поддерживается синтаксис указания полного пути, начинающегося с символа `/`, который должен в этом случае содержать в начале [размещение базы данных](../../../../concepts/connect.md#database), указанной в параметрах соединения, или с которой разрешаются операции через установленное соединение с кластером.
 
 Примеры:
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/scheme-ls.md b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/scheme-ls.md
index 332e7df0c8..6f3d4ca1fa 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/scheme-ls.md
+++ b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/scheme-ls.md
@@ -1,19 +1,72 @@
 # Список объектов
 
-Чтобы получить список объектов, используйте подкоманду `scheme ls <Путь>`. Если путь не указан, то будет выведен листинг корня базы данных:
+Команда `scheme ls` позволяет получить список объектов в базе данных:
 
 ```bash
-{{ ydb-cli }} scheme ls
+{{ ydb-cli }} [connection options] scheme ls [path] [-lR]
 ```
 
-Результат:
+{% include [conn_options_ref.md](conn_options_ref.md) %}
 
-```text
-episodes seasons  series .sys
+При запуске без параметров выводится перечень имен объектов в корневой директории базы данных в сжатом формате.
+
+Параметром `path` можно задать [директорию](../dir.md), для которой нужно вывести перечень объектов.
+
+Для команды доступны следующие опции:
+- `-l` : Полная информация об атрибутах каждого объекта
+- `-R` : Рекурсивный обход всех поддиректорий
+
+**Примеры**
+
+- Получение объектов в корневой директории базы данных в сжатом формате
+
+```bash
+{{ ydb-cli }} --profile db1 scheme ls
+```
+
+- Получение объектов во всех директориях базы данных в сжатом формате
+
+```bash
+{{ ydb-cli }} --profile db1 scheme ls -R
+```
+
+- Получение объектов в заданной директории базы данных в сжатом формате
+
+```bash
+{{ ydb-cli }} --profile db1 scheme ls dir1
+{{ ydb-cli }} --profile db1 scheme ls dir1/dir2
 ```
 
-Чтобы посмотреть подробную информацию об объектах, добавьте флаг `-l`:
+- Получение объектов во всех поддиректориях заданной директории базы данных в сжатом формате
 
 ```bash
-{{ ydb-cli }} scheme ls -l
+{{ ydb-cli }} --profile db1 scheme ls dir1 -R
+{{ ydb-cli }} --profile db1 scheme ls dir1/dir2 -R
 ```
+
+- Получение полной информации по объектам в корневой директории базы данных
+
+```bash
+{{ ydb-cli }} --profile db1 scheme ls -l
+```
+
+- Получение полной информации по объектам в заданной директории базы данных
+
+```bash
+{{ ydb-cli }} --profile db1 scheme ls dir1 -l
+{{ ydb-cli }} --profile db1 scheme ls dir2/dir3 -l
+```
+
+- Получение полной информации по объектам во всех директория базы данных
+
+```bash
+{{ ydb-cli }} --profile db1 scheme ls -lR
+```
+
+- Получение полной информации по объектам во всех поддиректориях заданной директории базы данных
+
+```bash
+{{ ydb-cli }} --profile db1 scheme ls dir1 -lR
+{{ ydb-cli }} --profile db1 scheme ls dir2/dir3 -lR
+```
+
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/tools/rename.md b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/tools/rename.md
index a0d9ec547d..415d4dd0ab 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/tools/rename.md
+++ b/ydb/docs/ru/core/reference/ydb-cli/commands/_includes/tools/rename.md
@@ -1,6 +1,6 @@
 # Переименование таблицы
 
-С помощью подкоманды `tools rename` вы можете переименовать одну или несколько таблиц одновременно, перенести таблицу в другую директорию в пределах той же БД, заменить одну таблицу другой в рамках одной транзакции.
+С помощью подкоманды `tools rename` вы можете [переименовать](../../../../../concepts/datamodel.md#rename) одну или несколько таблиц одновременно, перенести таблицу в другую директорию в пределах той же БД, заменить одну таблицу другой в рамках одной транзакции.
 
 Общий вид команды:
 
diff --git a/ydb/docs/ru/core/reference/ydb-cli/commands/commands.md b/ydb/docs/ru/core/reference/ydb-cli/commands/commands.md
deleted file mode 100644
index e7541c4794..0000000000
--- a/ydb/docs/ru/core/reference/ydb-cli/commands/commands.md
+++ /dev/null
@@ -1,7 +0,0 @@
-{% include [intro.md](_includes/commands/intro.md) %}
-
-{% include [all.md](_includes/commands/all.md) %}
-
-{% include [all-output.md](_includes/commands/all-output.md) %}
-
-{% include [one.md](_includes/commands/one.md) %}
diff --git a/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml b/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml
index 98d3bda3ac..12383f1df5 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml
+++ b/ydb/docs/ru/core/reference/ydb-cli/toc_i.yaml
@@ -2,7 +2,7 @@ items:
   - name: Установка
     href: install.md
   - name: Структура команд YDB CLI
-    href: commands/commands.md
+    href: commands.md
   - name: Сервисные команды
     href: commands/service.md
   - name: Соединение с БД и аутентификация
@@ -23,6 +23,8 @@ items:
     items:
     - name: Выполнение запроса к данным
       href: commands/query.md
+    - name: План исполнения запроса
+      href: commands/explain-plan.md
     - name: Потоковое чтение таблицы
       href: commands/readtable.md
     - name: Работа со вторичными индексами