Справочник CLI

Интерфейс командной строки среды выполнения Wippy.

Глобальные флаги

Доступны для всех команд:

Приоритет лимита памяти: флаг --memory-limit > переменная окружения GOMEMLIMIT > 1GB по умолчанию.

--config можно передавать несколько раз для композиции файлов конфигурации. Файлы объединяются слева направо: более поздние файлы переопределяют совпадающие значения и сохраняют всё остальное. Каждый явно указанный файл должен существовать; без --config стандартный .wippy.yaml необязателен. Первый файл задаёт директорию, относительно которой разрешаются относительные пути. Конфигурация применяется по порядку: композиция файлов, затем выбор --profile, затем переопределения --set. См. Конфигурация.

wippy init

Создать новый lock-файл.

wippy init
wippy init --src-dir ./src --modules-dir .wippy

wippy run

Запустить среду выполнения или выполнить команду.

wippy run                                   # Запустить среду выполнения
wippy run list                              # Список доступных команд
wippy run migrate                           # Запустить именованную пользовательскую команду
wippy run snapshot.wapp                     # Запустить из pack-файла
wippy run acme/http                         # Запустить модуль из хаба
wippy run acme/http@1.2.3                   # Запустить конкретную версию
wippy run --exec app:worker                 # Запустить среду и выполнить один процесс

Запуск модуля из хаба (wippy run org/module) разрешает его один раз, записывает в wippy.lock и складывает проверенные пакеты локально. Последующие запуски той же ссылки стартуют из lock-файла — сеть не нужна. Селектор версии, который больше не совпадает с lock-файлом, отклоняется с подсказкой выполнить wippy update.

Для локального приложения wippy run чинит устаревший lock-файл до старта любого сервиса среды выполнения. Он загружает объявления зависимостей из исходников, и если lock-файл уже им удовлетворяет — пересобирает граф только по локальным и уже установленным данным (проверенный офлайн-доступ, без сети). Если результат офлайн-разрешения совпадает с lock-файлом, загрузка продолжается без изменений. Если он успешен, но отличается, он становится кандидатным графом; к хабу за разрешением обращаются только тогда, когда офлайн-проход не удался или lock-файл больше не удовлетворяет объявлениям из исходников. Пакеты, которых кандидатному графу не хватает, скачиваются и проверяются, и только после этого wippy.lock перезаписывается. Lock-файл, выбирающий корень развёртывания, авторитетен и никогда не разрешается заново.

--exec блокируется до тех пор, пока запущенный процесс не выдаст результат, после чего код завершения процесса становится кодом завершения CLI. Ctrl-C во время --exec отменяет выполняемый процесс, и среда выполнения всё равно завершается штатно; второй сигнал вызывает принудительный выход.

--set записывает любое значение конфигурации среды выполнения из командной строки, объединяя с .wippy.yaml по каждому листу:

wippy run --set cluster.enabled=true \
          --set cluster.membership.join_addrs=node-2:7946,node-3:7946 \
          --set cluster.raft.bootstrap_expect=3

Значения преобразуются по форме: true/false в bool, целые и дробные числа в числа, остальное остаётся строкой (длительности вроде 5s разбираются там, где опция этого ожидает).

wippy test

Запустить точку входа тестов: запись процесса, объявляющую вариант использования test. Среда выполнения загружается, выполняет эту запись и завершается. wippy run не запускает тестовые точки входа автоматически; тестирование всегда идёт через wippy test.

wippy test                     # Запустить тесты из локального проекта
wippy test snapshot.wapp       # Запустить тесты из pack-файла
wippy test acme/module@1.2.3   # Запустить тесты из модуля хаба

wippy lint

Проверить Lua-код на ошибки типов и предупреждения.

wippy lint
wippy lint --level warning
wippy lint --json
wippy lint --rules

Проверяет все Lua-записи: function.lua, library.lua, process.lua, workflow.lua (включая их .bc-варианты).

wippy add

Добавить зависимость модуля.

wippy add acme/http
wippy add acme/http@1.2.3
wippy add acme/http@latest

wippy install

Установить зависимости из lock-файла.

wippy install                            # Установить все
wippy install acme/http                  # Установить конкретный модуль
wippy install --refresh acme/http        # Перекачать конкретный модуль

wippy update

Обновить зависимости и пересоздать lock-файл.

wippy update                      # Обновить все
wippy update acme/http            # Обновить конкретный модуль
wippy update acme/http demo/sql   # Обновить несколько

wippy artifacts

Работа с артефактами файловой системы на этапе сборки.

wippy artifacts materialize

Проверить и материализовать одну файловую систему-артефакт из существующего пакета.

wippy artifacts materialize snapshot.wapp app:package_fs
wippy artifacts materialize snapshot.wapp app:package_fs --root build

Ресурс адресуется полным namespace:name, должен объявлять meta.artifact.format, и этот формат должен быть зарегистрирован в CLI. Команда не разрешает зависимости модулей, не изменяет wippy.lock, не вызывает менеджеры пакетов и не участвует в композиции среды выполнения. См. Артефакты сборки.

wippy pack

Создать snapshot-пакет (файл .wapp).

wippy pack snapshot.wapp
wippy pack release.wapp --description "Release 1.0"
wippy pack app.wapp --embed app:assets --bytecode **

Без --embed и --embed-all паттерны встраивания берутся из секции embed: манифеста модуля wippy.yaml. Упаковка приложения также переносит встроенные ресурсы из пакетов его зависимостей, а итоговый пакет предоставляет команды только основного модуля.

Выходной файл записывается атомарно: пакет собирается во временный файл в целевой директории, синхронизируется, проверяется и только затем переименовывается поверх целевого, наследуя права существующего файла, если он есть. Неудачная упаковка оставляет прежний файл нетронутым. Указание выходного файла, который одновременно является одним из входов пакета — тот же путь либо жёсткая или символическая ссылка, ведущая на тот же файл, — отклоняется, а не приводит к усечению входа посреди чтения.

--meta не может записывать зарезервированные метаданные. Ключ registry, а также всё под префиксами wippy. и system., принадлежит формату пакета и отклоняется.

Ресурсы, объявляющие meta.artifact.format, проверяются во время упаковки, поэтому некорректный артефакт падает здесь, а не у потребителя. См. Артефакты сборки.

wippy publish

Опубликовать модуль в хаб.

wippy publish
wippy publish --version 1.0.0
wippy publish --dry-run

Читает из wippy.yaml в текущей директории.

Тип модуля обычно объявляется как type: в wippy.yaml (см. Публикация); --module-type переопределяет его для одной публикации. Если не задано ни то, ни другое, новые модули по умолчанию получают тип application с предупреждением об устаревании.

wippy search

Поиск модулей в хабе.

wippy search http
wippy search "sql driver" --limit 20
wippy search auth --json

wippy auth

Управление аутентификацией в реестре.

wippy auth login

wippy auth login
wippy auth login --token YOUR_TOKEN

wippy auth logout

wippy auth logout

wippy auth status

wippy auth status
wippy auth status --json

wippy readme

Получить README модуля из хаба.

wippy readme wippy/terminal
wippy readme wippy/terminal@1.2.3
wippy readme --json wippy/terminal@latest

wippy registry

Запрос и просмотр записей реестра. Обе подкоманды принимают --profile и --set, задающие объединённую конфигурацию среды выполнения, под которой загружаются записи.

wippy registry list

wippy registry list
wippy registry list --kind "function.lua.*"
wippy registry list --ns "app.*" --json
wippy registry list --meta "type=api" --meta "enabled=true"

Операторы метаданных для --meta:

wippy registry show

wippy registry show app:http:handler
wippy registry show app:config --yaml

wippy version

Вывести информацию о версии.

wippy version
wippy version --short

Пользовательские команды

Любая запись process.lua или process.wasm может быть зарегистрирована как именованная команда с помощью метаданных command:

entries:
  - name: migrate_runner
    kind: process.lua
    meta:
      command:
        name: migrate
        short: Run database migrations
    source: file://runner.lua
    method: main
    modules:
      - io
      - registry
      - funcs

Запуск:

wippy run migrate

Список всех доступных команд:

wippy run list

wippy run list принимает --profile и --set, поэтому список отражает ту же объединённую конфигурацию среды исполнения, которую использовал бы wippy run.

Поля метаданных команды

Подходит любой тип записи процесса (process.lua, process.wasm). Имена команд не проверяются на уникальность; когда несколько загруженных записей объявляют одно и то же имя, запускается первое совпадение в порядке реестра. Аргументы после имени команды передаются процессу в виде строкового payload.

Безопасность команды

Запись команды объявляет актора и область политик, под которыми выполняется её запуск из CLI:

entries:
  - name: migrate_runner
    kind: process.lua
    meta:
      command:
        name: migrate
        short: Run database migrations
        security:
          actor:
            id: system.migrations
            meta:
              role: operator
          policies:
            - app.security:migrations_policy
          groups:
            - app.security:operators
    source: file://runner.lua
    method: main

Блок находится внутри meta.command, потому что применяется только к пути запуска из CLI — оператор запустил команду на собственном развёртывании, и это якорь доверия. На обычные spawn той же записи процесса он не влияет; они следуют собственному блоку security: записи.

Объявление fail-closed и проверяется до старта процесса:

• Неизвестные поля внутри security отклоняются.
• Пустой блок security (без актора, политик и групп) отклоняется.
• security без name отклоняется — чтобы команду можно было запустить, она должна быть именуемой.
• Политика или группа, которую не удалось разрешить, запрещает запуск; разрешение атомарно, поэтому частичная область никогда не устанавливается.

Когда блок опускает actor, наследуется актор вызывающего. Когда он опускает и policies, и groups, наследуется область вызывающего.

Примеры

Рабочий процесс разработки

# Инициализация проекта
wippy init
wippy add wippy/test wippy/llm
wippy install

# Проверка на ошибки
wippy lint

# Запуск с отладочным выводом
wippy run -c -v

# Переопределение конфигурации для локальной разработки
wippy run -o app:db:host=localhost -o app:db:port=5432

Развёртывание в продакшен

# Создание релизного пакета с байткодом
wippy pack release.wapp --bytecode ** --exclude-ns test.**

# Запуск из пакета с лимитом памяти
wippy run release.wapp -m 2G

Отладка

# Выполнение одного процесса
wippy run --exec app:worker

# С включённым профилировщиком
wippy run -p -v
# Затем: go tool pprof http://localhost:6060/debug/pprof/heap

Управление зависимостями

# Добавить новую зависимость
wippy add acme/http@latest

# Принудительно перескачать
wippy install --force

# Обновить конкретный модуль
wippy update acme/http

Публикация

# Вход в хаб
wippy auth login

# Проверка модуля
wippy publish --dry-run

# Публикация
wippy publish --version 1.0.0 --release-notes "Initial release"

Переменные окружения

Значения в .wippy.yaml могут ссылаться на переменные окружения ОС через ${env:NAME}, разрешаемые при загрузке файла; отсутствующая переменная приводит к ошибке загрузки конфигурации. Голые ссылки ${name} разрешаются из секции vars: конфигурации.

Файл конфигурации

Создайте .wippy.yaml для постоянных настроек:

logger:
  encoding: console

logmanager:
  stream_to_events: true

profiler:
  enabled: true
  address: localhost:6060

override:
  app:gateway:addr: ":9090"
  app:db:host: "localhost"

Смотрите также

• Конфигурация — справочник по файлу конфигурации
• Наблюдаемость — мониторинг и логирование