docs

docs/root/flags.rst

@@ -3,7 +3,45 @@
 Флаги вводимых команд
 =====================
 
-Флаги (или параметры) — это специальные аргументы, которые пользователь может добавлять к командам для управления их поведением. 
+Флаги — это специальные параметры, которые пользователь может добавлять к командам для управления их поведением. 
+
+Зачем нужны флаги в командах
+----------------------------
+
+Управление поведением команды
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Основная цель флагов — предоставить способ изменить логику работы команды без её переработки. Команда может работать в нескольких режимах: стандартном, подробном, отладочном или упрощённом. Флаги переключают эти режимы по требованию пользователя, оставляя основную функциональность неизменной.
+
+Опциональность и удобство
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Флаги решают проблему обязательности параметров. Если все параметры команды сделать обязательными, это затруднит использование команды. Флаги же позволяют задать значения только необходимые в конкретной ситуации, остальные используют значения по умолчанию.
+
+Когда могут понадобиться флаги
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Переключение режимов работы**
+  Команда выполняет развёртывание приложения обычно, но нужен режим без фактического развёртывания (dry-run) для проверки. Флаг ``--dry-run`` переключит режим работы.
+
+**Настройка уровня детальности**
+  При отладке или анализе требуется больше информации о процессе выполнения команды. Флаги ``--verbose`` или ``--debug`` предоставляют подробный вывод.
+
+**Управление поведением при ошибках**
+  По умолчанию команда может прерваться при первой ошибке. Флаг ``--force`` позволит продолжить работу, пропуская некритичные ошибки.
+
+**Форматирование вывода**
+  Команда выводит данные текстом, но в некоторых сценариях нужен JSON или CSV. Флаг ``--format=json`` переключит формат вывода.
+
+**Комбинирование опций**
+  Часто нужна комбинация нескольких изменений: подробный вывод, dry-run режим и JSON формат. Несколько флагов решают эту задачу одновременно.
+
+Практическое значение
+~~~~~~~~~~~~~~~~~~~~~
+
+Флаги делают команды более предсказуемыми и контролируемыми. Пользователь может начать с простого использования, а затем добавлять флаги по мере необходимости. Это особенно важно при автоматизации задач в скриптах, где гибкость интерфейса критична.
+
+Флаги также облегчают интеграцию команд в различные системы, так как дополнительное поведение достигается без изменения структуры команды, а только через передачу опциональных параметров.
 
 -----
 
@@ -32,38 +70,55 @@
 
 -----
 
-Ограничение по списку возможных значений
-----------------------------------------
+Флаги против аргументов
+-----------------------
 
-Вы можете заранее определить список допустимых значений для флага.
+В контексте Argenta флаги и аргументы относятся к разным уровням взаимодействия с приложением и имеют принципиально разные сферы действия.
 
-Предположим, у вас есть флаг ``--format``, который может принимать только значения ``json`` или ``xml``.
+Определение и назначение
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: bash
-   :linenos:
+**Аргументы** — это параметры, передаваемые при запуске приложения один раз при инициализации. Они определяют глобальное состояние и конфигурацию приложения на протяжении всей его работы, например адрес базы данных, уровень логирования или режим работы.
 
-   # Эта команда сработает
-   export --format json
+.. seealso:: API и более подробное описание в разделах :ref:`ArgParser <root_api_orchestrator_argparser>` и :ref:`Arguments <root_api_orchestrator_arguments>`.
+
+**Флаги** — это параметры командных операций, доступные в рамках интерактивной сессии при вводе каждой новой команды. Они позволяют модифицировать поведение конкретной команды без перезагрузки приложения.
+
+.. seealso:: API и более подробное описание в разделе :ref:`Flag <root_api_command_flag>`.
 
-   # А эта команда не пройдёт валидацию, так как значение "csv" не входит в список разрешённых
-   export --format csv
-   
 -----
 
-Проверка с помощью регулярных выражений
------------------------------------------
+Ключевые различия
+~~~~~~~~~~~~~~~~~
 
-Для более сложных проверок можно использовать регулярные выражения. Это полезно, когда значение должно соответствовать определённому формату (например, email-адрес, дата или номер телефона).
+**Время жизни и область действия**
+  Аргументы передаются один раз при запуске приложения и сохраняют действие на весь период работы(скоуп **APP**). Флаги наоборот локальны и живут в рамках скоупа **REQUEST**.
 
-Допустим, флаг ``--email`` должен принимать только корректные email-адреса.
+**Частота изменения**
+  Для изменения аргументов необходимо перезапустить приложение. Флаги можно менять между каждым вводом команды без остановки приложения.
 
-.. code-block:: bash
-   :linenos:
+**Уровень конфигурации**
+  Аргументы управляют глобальной конфигурацией приложения и его окружением. Флаги управляют поведением отдельных команд и операций пользователя.
 
-   # Эта команда выполнится, так как значение соответствует формату email
-   send --email "user@example.com"
+**Использование**
+  Аргументы задают начальное состояние системы: что подключить, как работать. Флаги управляют тактикой выполнения команд: как её выполнить, с какими изменениями.
 
-   # Эта команда не пройдёт валидацию, так как "user_example.com" — некорректный email
-   send --email "user_example.com"
+-----
+  
+Практические примеры в Argenta
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Встроенная валидация избавляет от необходимости писать проверки вручную и делает код более декларативным.
+При запуске приложения Argenta передаются аргументы:
+
+- Адрес подключения к базе данных
+- Режим работы (production, development, testing)
+- Уровень логирования
+- Путь к конфигурационным файлам
+
+В интерактивной сессии для каждой команды указываются флаги:
+
+- ``deploy --verbose --dry-run`` — для текущей команды развёртывания
+- ``backup --compress --encrypted`` — для команды резервного копирования
+- ``test --parallel --coverage`` — для команды тестирования
+
+Один пользователь может выполнить разные команды с разными флагами в одной сессии приложения, без необходимости перезапуска с новыми аргументами.