---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://ydb.tech/docs/ru/contributor/documentation/cli-command-documentation.md?version=v25.4
  - href: ru/contributor/documentation/cli-command-documentation.md
    type: text/markdown
    title: Markdown version
  - href: ../../llms.txt
    type: text/markdown
    title: llms.txt
sourcePath: ru/core/contributor/documentation/cli-command-documentation.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt

# Документирование новых команд CLI

Эта статья описывает процесс создания документации для новых команд YDB CLI. Она содержит шаблон и рекомендации, основанные на существующих статьях о командах CLI.

## Общие принципы

Перед началом работы над документацией новой команды:

1. Ознакомьтесь с [Руководство по стилю документации YDB](https://ydb.tech/docs/ru/contributor/documentation/style-guide.md?version=v25.4) для понимания общих правил стиля документации.
2. Убедитесь, что команда реализована и доступна в CLI с опцией `--help`.

## Структура статьи

Каждая статья о команде CLI должна следовать следующей структуре:

### 1. Заголовок первого уровня

Заголовок должен кратко описывать действие команды. Используйте формулировку, которая начинается с существительного или отглагольного существительного.

**Примеры:**

- `# Создание топика`
- `# Удаление таблицы`
- `# Получение статуса фоновой операции`
- `# Чтение из топика`

### 2. Краткое описание

Первые 1–3 предложения описывают назначение команды. Если команда связана с другими командами, добавьте ссылки на них.

**Пример:**

```markdown
С помощью подкоманды `topic create` вы можете создать новый топик.
```

**Пример со ссылкой:**

```markdown
С помощью команды `topic consumer add` вы можете добавить читателя для [созданного ранее](topic-create.md) топика.
```

### 3. Примечания (опционально)

Если команда имеет важные особенности, ограничения или предупреждения, добавьте их сразу после описания с помощью блока `{% note %}`.

**Пример:**

```markdown
{% note info %}

При удалении топика также будут удалены все добавленные для него читатели.

{% endnote %}
```

### 4. Общий вид команды

Покажите синтаксис команды с использованием шаблона `ydb` и правильного форматирования.

**Базовый шаблон:**

```markdown
Общий вид команды:

ydb [global options...] <command> [options...] [arguments...]

* `global options` — [глобальные параметры](commands/global-options.md).
* `options` — [параметры подкоманды](#options).
* `arguments` — аргументы команды (опишите каждый).
```

**Примеры:**

Для команды без опций:

```markdown
ydb [global options...] topic drop <topic-path>
```

Для команды с опциями:

```markdown
ydb [global options...] topic create [options...] <topic-path>
```

Для сложной команды:

```markdown
ydb [connection options] topic read <topic-path> [--consumer STR] \
  [--format STR] [--wait] [--limit INT] \
  [--transform STR] [--file STR] [--commit BOOL] \
  [дополнительные параметры...]
```

### 5. Ссылка на справку

Всегда добавляйте команду для получения справки:

```markdown
Посмотрите описание команды:

ydb <command> --help
```

### 6. Параметры подкоманды

Если команда имеет параметры, создайте раздел `## Параметры подкоманды {#options}`.

Оформите параметры в виде таблицы:

```markdown
## Параметры подкоманды {#options}

Имя | Описание
|---|---
`--parameter-name VAL` | Описание параметра.
```

**Рекомендации по описанию параметров:**

- Укажите тип значения, если он важен (например, `VAL`, `STR`, `INT`, `BOOL`).
- Укажите значение по умолчанию, если оно есть.
- Перечислите возможные значения для перечислений.
- Добавьте ссылки на концепции, если параметр связан с ними.
- Используйте HTML-теги для форматирования внутри ячеек таблицы (например, `<br/>`, `<ul>`, `<li>`).

**Пример простого параметра:**

```markdown
`--consumer VAL` | Имя читателя, которого нужно добавить.
```

**Пример параметра с описанием:**

```markdown
`--retention-period` | Время хранения данных в топике. Положительное число с указанием единицы измерения.<br/>Поддерживаются следующие единицы:<ul><li>`s` – секунды;</li><li>`m` – минуты;</li><li>`h` – часы;</li><li>`d` – дни.</li></ul>Значение по умолчанию — `18h`.
```

**Пример параметра со ссылкой:**

```markdown
`--partitions-count`| Количество [партиций](../../concepts/datamodel/topic.md#partitioning) топика.<br/>Значение по умолчанию — `1`.
```

**Группировка параметров:**

Для команд с большим количеством параметров можно разделить их на группы:

```markdown
## Параметры {#options}

### Обязательные параметры

`<topic-path>`: Путь топика

### Основные опциональные параметры

`-c VAL`, `--consumer VAL`: Имя читателя топика.

### Другие опциональные параметры

| Имя | Описание |
|-----|----------|
| `--idle-timeout VAL` | Таймаут принятия решения о том что топик пуст. |
```

### 7. Примеры

Всегда добавляйте раздел с примерами использования команды.

**Шаблон раздела примеров:**

```markdown
## Примеры {#examples}

{% include [ydb-cli-profile](../../_includes/ydb-cli-profile.md) %}

[Описание примера]:
```

**Рекомендации по примерам:**

- Начинайте каждый пример с краткого описания того, что он демонстрирует.
- Используйте профиль `quickstart` для примеров: `ydb -p quickstart ...`
- Показывайте результаты выполнения команды, если они важны для понимания.
- Группируйте связанные примеры.
- Добавляйте ссылки на связанные команды или статьи в конце раздела, если это уместно.

**Пример простого использования:**

```markdown
Создайте читателя с именем `my-consumer` для [созданного ранее](topic-create.md) топика `my-topic`:

ydb -p quickstart topic consumer add \
  --consumer my-consumer \
  my-topic
```

**Пример с результатом:**

```markdown
Убедитесь, что читатель создан:

ydb -p quickstart scheme describe my-topic

Результат:

    RetentionPeriod: 2 hours
    PartitionsCount: 2
    SupportedCodecs: RAW, GZIP

    Consumers:
    ┌──────────────┬─────────────────┬───────────────────────────────┬───────────┐
    || ConsumerName | SupportedCodecs | ReadFrom                      | Important |
    ├──────────────┼─────────────────┼───────────────────────────────┼───────────┤
    || my-consumer  | RAW, GZIP       | Mon, 15 Aug 2022 16:00:00 MSK | 0         |
    └──────────────┴─────────────────┴───────────────────────────────┴───────────┘
```

**Пример с несколькими вариантами использования:**

```markdown
* Чтение одного сообщения с выводом в терминал:

ydb -p quickstart topic read topic1 -c c1

* Ожидание появления и чтение одного сообщения с записью его в файл:

ydb -p quickstart topic read topic1 -c c1 -w -f message.bin
```

## Полный шаблон статьи

Полный шаблон статьи доступен в отдельном файле: [шаблон](https://github.com/ydb-platform/ydb/tree/main/ydb/docs/ru/core/contributor/documentation/_templates/cli-command-template.md). Используйте его как основу при создании документации для новой команды CLI.

## Специальные случаи

### Команды без параметров

Если команда не имеет параметров (кроме глобальных), раздел "Параметры подкоманды" можно опустить.

**Пример:**

```markdown
# Удаление топика

С помощью подкоманды `topic drop` вы можете удалить [созданный ранее](topic-create.md) топик.

Общий вид команды:

ydb [global options...] topic drop <topic-path>

* `global options` — [глобальные параметры](commands/global-options.md).
* `topic-path` — путь топика.

Посмотрите описание команды удаления топика:

ydb topic drop --help

## Примеры {#examples}
...
```

### Команды с режимами работы

Если команда поддерживает несколько режимов работы, опишите их перед разделом параметров.

**Пример:**

```markdown
Поддерживается три режима работы команды:

1. **Одно сообщение**. Из топика считывается не более одного сообщения.
2. **Пакетный режим**. Сообщения из топика считываются до того момента, пока в топике не закончатся сообщения для обработки.
3. **Потоковый режим**. Сообщения из топика считываются по мере их появления.
```


### Предупреждения об устаревших командах

Если команда устарела, добавьте предупреждение в начале статьи:

```markdown
{% include notitle [warning](../../reference/ydb-cli/_includes/deprecated_command_warning.md) %}
```

## Именование файлов

- Используйте дефисы вместо подчёркиваний: `topic-create.md`, а не `topic_create.md`.
- Имя файла должно соответствовать структуре команды: `topic-consumer-add.md` для команды `topic consumer add`.
- Для простых команд используйте короткие имена: `version.md`, `table-drop.md`.

## Интеграция в документацию

После создания статьи:

1. **Добавьте ссылку в `_includes/commands.md`** — общий список всех команд CLI.
2. **Обновите оглавление** — добавьте статью в соответствующий `toc_i.yaml` или `toc_p.yaml`.
3. **Добавьте перекрёстные ссылки** — обновите связанные статьи, добавив ссылки на новую команду.
4. **Проверьте ссылки** — убедитесь, что все внутренние ссылки корректны и используют относительные пути с суффиксом `.md`.

## Проверка перед публикацией

Перед отправкой pull request убедитесь, что:

- [ ] Статья следует структуре, описанной выше.
- [ ] Все примеры протестированы и работают корректно.
- [ ] Используются правильные переменные: `ydb`, `YDB`.
- [ ] Все ссылки корректны и используют относительные пути с `.md`.
- [ ] Статья добавлена в оглавление и список команд.
- [ ] Текст соответствует [руководству по стилю](https://ydb.tech/docs/ru/contributor/documentation/style-guide.md?version=v25.4).
- [ ] Нет опечаток и грамматических ошибок.

## См. также

- [Руководство по стилю документации YDB](https://ydb.tech/docs/ru/contributor/documentation/style-guide.md?version=v25.4) — общее руководство по стилю документации
- [Структура документации YDB](https://ydb.tech/docs/ru/contributor/documentation/structure.md?version=v25.4) — структура документации
- [Процесс ревью документации YDB](https://ydb.tech/docs/ru/contributor/documentation/review.md?version=v25.4) — процесс ревью документации
- [Примеры существующих статей](https://ydb.tech/docs/ru/reference/ydb-cli/index.md?version=v25.4) — изучите похожие команды для вдохновения