CLI

Команды CLI

perfscale run          Run a load test with k6, locust, JMeter, or the native step engine
perfscale serve        Start a local dev server that receives metrics from `run --report`
perfscale lint         Validate test/config YAML files without running them
perfscale install      Fetch remote libraries and pin them in perfscale.lock
perfscale burn         Build a standalone binary with WASM libraries embedded
perfscale convert k6   Convert a static k6 script to native test/config YAML
perfscale schema       Print the JSON Schema for test or config YAML files
perfscale metrics      List every metric the registered families declare
perfscale man          Print the bundled man page (or install it for `man perfscale`)
perfscale self-update  Update perfscale to the latest release for this platform
perfscale cache        Manage the local import/library cache (~/.cache/perfscale)

`perfscale run`

Требуется ровно один флаг движка: --k6, --locust, --jmeter или -f.

Флаг	Значение	Описание
`--k6 <FILE>`	`.js`-скрипт	Запуск через бинарник `k6` из `PATH`
`--locust <FILE>`	locustfile	Запуск через бинарник `locust` из `PATH`, в headless-режиме
`--jmeter <FILE>`	`.jmx` тест-план	Запуск через бинарник `jmeter` из `PATH`, без GUI (`jmeter -n -t -l <temp>/results.jtl`). План сам определяет профиль нагрузки; `.jtl` разбирается в полные метрики с перцентилями, гейты thresholds и отчёты
`-J, --jmeter-property <KEY=VALUE>`	повторяемый	Свойство JMeter для прогонов `--jmeter` (`-Jvus=50`, `-J vus=50`, `--jmeter-property vus=50`; значения могут содержать `=`). Собственные настройки JTL раннера всегда побеждают
`-f, --file <FILE>`	`test.yaml`	Запуск со встроенным нативным движком (требует `-c`)
`-c, --config <FILE>`	`config.yaml`	Конфигурация нагрузки: `vus`, `duration`, опционально `report.url`. Обязателен с `-f`, для `--locust` — опциональная подсказка о нагрузке, для `--k6` игнорируется. С `--jmeter` применяются только `report:` и гейты `std/thresholds@v1` из `after:` — профилем нагрузки управляет план
`--host <URL>`	базовый URL	Целевой хост для `--locust` (аналог `--host` у locust)
`--report <SPEC>`	повторяемый	Две формы. `http(s)://URL` — POST сводки (и артефакта report@v1, если настроены репортеры) на экземпляр `perfscale serve`; переопределяет `report.url`. `json:PATH` / `junit:PATH` / `html:PATH` — отчёт `report@v1` в конце запуска: канонический JSON, JUnit XML для CI (testcase на шаг, failures из вердиктов thresholds) или самодостаточная HTML-страница с тёмной темой (открывается офлайн, архивируется как артефакт CI). Флаг повторяем — несколько отчётов за один прогон
`--label <KEY=VALUE>`	повторяемый	Метка запуска в идентичности отчёта (`run.labels`), напр. `--label testid=smoke`
`-i, --input <KEY=VALUE>`	повторяемый	Переопределить типизированный вход из блока `inputs:` конфига (issue #11). Работает и форма через запятую: `-i users=10,env=prod`; запятая в значении экранируется как `\,`. Приоритет: `-i` > env-файл `-e` > `default:`
`-e, --env-file <FILE>`	путь, повторяемый	Прочитать значения входов из KEY=VALUE env-файла (используются только ключи объявленных входов); поздние файлы переопределяют ранние
`-q, --quiet`	—	Подавить вывод по каждому запросу; ошибки и итоговая сводка метрик по-прежнему печатаются. Нативный движок отбрасывает эти строки прямо у источника, что заодно убирает накладные расходы на их форматирование и ввод-вывод под высокой нагрузкой
`--summary-export <FILE>`	путь, повторяемый	После прогона записать в этот файл разобранную сводку метрик (запросы, RPS, перцентили задержки, доля ошибок) вместе с метаданными прогона (движок, VU, длительность, метка времени, версия perfscale). Повторите флаг, чтобы записать несколько экспортов за один прогон. Расширение `.md`/`.json` выбирает формат для каждого файла (по умолчанию JSON)
`--summary-format <json\|md>`	вместе с `--summary-export`	Формат для файлов экспорта без распознанного расширения. `md` рендерит таблицу для сводок заданий CI: `--summary-export "$GITHUB_STEP_SUMMARY" --summary-format md`
`--allow-remote-import`	—	Разрешить `import:` в документах `-f`/`-c` загружаться по сети (http(s) URL, git-репозитории). По умолчанию запрещено (fail-closed) — документ не может сам себе выдать доступ к сети. См. импорты
`--refresh-imports`	—	Повторно загрузить кэшированные git-импорты по тегу/ветке вместо доверия кэшу (импорты по SHA коммита неизменяемы и никогда не перезагружаются)

Стриминг-репортеры (Prometheus remote write, OTLP)

Блок report.reporters конфига умеет также стримить живые метрики во время прогона в подключаемые приёмники: std/report/serve@v1 (путь report.url как репортер), std/report/prometheus-rw@v1 (remote write со Snappy+protobuf) и std/report/otel@v1 (OTLP/gRPC). Каждый репортер задаёт during_run: true и ключи движка (interval_ms, labels, max_series) рядом с use: — см. Стриминг-репортеры для полной конфигурации и политики доставки (ограниченные очереди с потерей старейших, повторы с backoff, финальный сброс с пределом final_timeout; ошибки репортера предупреждают, но никогда не фейлят прогон, а потери считаются в perfscale_report_dropped_snapshots_total / perfscale_report_dropped_series_total / perfscale_report_errors_total и сводятся в stderr в конце запуска).

Семантика кодов выхода

0 — прогон завершён, даже если запросы или проверки завершались неудачей. Провалившиеся проверки — это обратная связь нагрузочного теста (видна в http_req_failed и в stderr), а не ошибка CLI — как поведение k6 по умолчанию без порогов (thresholds). Это также касается движков, которые выходят с ненулевым кодом при провалившихся запросах (k6 с thresholds, locust), если они выдали сводку результатов.
1 — прогон не удалось выполнить: файл не найден, некорректный YAML, бинарник движка не найден или движок упал до выдачи каких-либо результатов (ненулевой выход с нулевыми метриками — ошибка в скрипте или сломанная установка, а не обратная связь теста): error: engine exited with code 1 before producing any results. Кроме того: нативный прогон, у которого gate std/thresholds@v1 дал результат fail (error: thresholds failed: …) — gates позволяют CI превращать нарушения SLO в провалившуюся сборку, как thresholds в k6.
2 — некорректные аргументы командной строки.

Потоки вывода

stdout — вывод движка и итоговая сводка метрик (машиночитаемый формат)
stderr — ошибки, провалившиеся проверки и маркеры прогресса [system]. Прогоны, выполняемые через машинного агента, завершаются финальным маркером [sys] __perfscale_exit__=<code>, несущим код выхода движка — см. Раннеры → маркер выхода

Экспорт сводки

--summary-export записывает самоописательный файл результатов после прогона:

{
  "meta": {
    "perfscale_version": "0.2.0",
    "engine": "native",
    "vus": 10,
    "duration": "30s",
    "timestamp": "2026-07-08T11:11:17Z"
  },
  "summary": {
    "avg_ms": 0.09, "med_ms": 0.08, "p90_ms": 0.15, "p95_ms": 0.17,
    "p99_ms": 0.27, "min_ms": 0.02, "max_ms": 2.86,
    "error_rate": 0.0, "total_requests": 20872, "requests_per_sec": 20866.54
  }
}

vus/duration равны null для прогонов --k6 и --jmeter (профиль нагрузки задан в скрипте/плане). То же верно для нативных прогонов с профилем stages:/arrival: — фиксированного числа VU нет, поэтому vus равен null, а duration — суммарная длительность шагов (например, "90s"); строка vus в сводке в этом случае показывает наблюдаемый минимум/максимум параллелизма. summary равен null, если прогон не дал HTTP-метрик. Если в конфигурации был gate std/thresholds@v1, в экспорте появляется поле thresholds с результатом gate:

{
  "thresholds": {
    "status": "fail",
    "message": "db_query_failed rate=1 ≥ 0.05; checkout SLO",
    "violations": [{ "metric": "db_query_failed", "expr": "rate<0.05", "actual": 1.0 }]
  }
}

status равен pass, когда все выражения выполнились, иначе — severity gate (fail/warn/info). Статус fail также заставляет perfscale run завершиться с ненулевым кодом, так что CI падает на самом gate. С --summary-format md те же данные рендерятся как таблица Markdown — если направить её в $GITHUB_STEP_SUMMARY, она попадёт прямо в сводку задания GitHub Actions. Неудачная запись экспорта — ошибка CLI (код выхода 1), даже если сам прогон завершился успешно: CI не должен молча продолжаться без запрошенного артефакта.

Ошибки доступности движков

error: k6 not found in PATH — install from https://k6.io/docs/get-started/installation/
error: locust not found in PATH — install with `pip install locust` (...)
error: jmeter not found in PATH — install from https://jmeter.apache.org/download_jmeter.cgi (...)

Прогоны JMeter строят сводку из приватного CSV-файла results.jtl: полные перцентили http_req_duration (p50/p90/p95/p99), серии по label и гейты std/thresholds@v1 из блока after: конфигурации — нарушенный гейт severity: fail завершает прогон с кодом 1, как в нативном движке. План с нулевым числом сэмплов откатывается на трансляцию консольной строки summary = (только avg/min/max).

`perfscale serve`

Флаг	По умолчанию	Описание
`--port <PORT>`	`7999`	Порт для прослушивания; `0` выбирает свободный порт (печатается при запуске)
`--tls`	выкл.	Обслуживать HTTPS с самоподписанным сертификатом, сгенерированным при запуске, — локальная TLS-цель для нагрузочных тестов. Клиенты должны пропускать проверку сертификата (`insecure: true` в `std/http@v1`, `insecureSkipTLSVerify` у k6, `verify=False` у locust)
`--no-ui`	выкл.	Не обслуживать встроенный дашборд на `/`; API приёма метрик продолжает работать

Эндпоинты:

Метод	Путь	Описание
`GET`	`/`	Встроенный дашборд (отсутствует с `--no-ui`): живые временные ряды снапшотов во время прогона и последние сводки прогонов. Самодостаточный — без CDN; опрашивает `/api/v1/state`
`GET`	`/health`	Возвращает `ok`
`POST`	`/api/v1/report`	Принимает артефакт `report@v1` (`perfscale run --report json:…`/`junit:…`), хранится в памяти и отдаётся через `/api/v1/state`
`POST`	`/api/v1/metrics`	Принимает итоговую сводку `{"lines": ["...", ...]}` или снапшот во время прогона `{"samples": [...], "seq": N}` (`report.during_run`), печатает его и хранит в памяти для дашборда
`GET`	`/api/v1/state`	Недавние пакеты снапшотов и последние сводки прогонов в JSON — то, что опрашивает дашборд. Хранится только в памяти: последние 2000 пакетов снапшотов и 20 сводок
`GET`	`/ws`	WebSocket-эхо — каждое текстовое (и бинарное) сообщение возвращается дословно. Петлевая (loopback) цель для WebSocket-нагрузочных тестов и бенчмарк-набора `ws`

Дашборд

Дашборд включён по умолчанию — запустите perfscale serve и откройте http://localhost:7999/ (флага --ui нет; страница обслуживается, пока не передан --no-ui):

Дашборд perfscale serve: живые карточки метрик со спарклайнами и сводка последнего прогона

Каждый ряд из снапшотов report.during_run становится карточкой с последним значением и спарклайном; завершённые прогоны складываются блоками сводок ниже. Сортируемая таблица с фильтром перечисляет все ряды, а карточки и строки метрик ведут на соответствующие страницы встроенной документации. Страница опрашивает GET /api/v1/state каждые 2 секунды и имеет переключатель тёмной/светлой темы (по умолчанию — тема ОС).

Страница — один самодостаточный HTML-файл без CDN. Её исходники — React + TypeScript + Tailwind + shadcn/ui приложение в crates/perfscale-cli/ui/, собираемое Vite в закоммиченный src/commands/serve_ui.html, который CLI встраивает через include_str!, поэтому сборке Rust не нужен Node. Чтобы изменить дашборд: отредактируйте приложение, выполните pnpm install && pnpm build в crates/perfscale-cli/ui/ и закоммитьте обновлённый serve_ui.html — CI проверяет его свежесть (pnpm check-built).

На этой же странице встроена вся документация: вкладка Docs рендерит markdown из docs/ (английский и русский, переключатель EN/RU, по умолчанию — язык браузера) полностью офлайн. Встроенная копия генерируется из документации при сборке; после правок markdown контрибьюторы регенерируют её командой PERFSCALE_UPDATE_DOCS=1 cargo test -p perfscale-cli serve_docs.

# терминал 1 — дашборд обслуживается на /
perfscale serve

# терминал 2 — для живых рядов нужен report.during_run: true в конфиге
perfscale run -f test.yaml -c config.yaml --report http://127.0.0.1:7999

Это заменитель для разработки, а не control-plane: ни персистентности, ни аутентификации, ни агрегации между прогонами. Его может заменить всё, что умеет работать с этими эндпоинтами.

Бенчмаркинг

В perfscale нет подкоманды bench — сравнения движков запускаются через scripts/bench.sh, скрипт на базе hyperfine. Методология и использование описаны в разделе Бенчмарки.

`perfscale lint`

Проверяет YAML-файлы по тем же схемам, что использует run, — плюс проверки, которые схема выразить не может, — ничего не выполняя. Предназначен для редакторов, CI gate'ов и pre-commit-хуков.

perfscale lint test.yaml config.yaml
perfscale lint --schema config load.yaml

Флаг	По умолчанию	Описание
`FILE...`	обязательный	Один или несколько YAML-файлов
`--schema <auto\|test\|config>`	`auto`	`auto` определяет тип по файлу: ключ верхнего уровня `steps:` означает определение теста, всё остальное — конфигурация
`--offline`	выкл.	Пропустить сетевой проход (интроспекция GraphQL) — проверять только офлайн
`--allow-remote-import`	выкл.	Разрешить `import:` в проверяемых документах загружаться по сети, чтобы можно было валидировать объединённый результат
`--refresh-imports`	выкл.	Повторно загрузить кэшированные git-импорты по тегу/ветке вместо доверия кэшу
`-i, --input <KEY=VALUE>`	—	Переопределить объявленный вход — чистый lint конфига печатает разрешённые значения `inputs:`
`-e, --env-file <FILE>`	—	Прочитать значения входов из KEY=VALUE env-файла (как `run -e`)

Что проверяется:

Импорты — документы с ключом import: сначала разрешаются и объединяются, так что валидация видит то, что реально будет выполняться. Проблемы разрешения (отсутствующая база, цикл, удалённый импорт без --allow-remote-import) сообщаются как находки по адресу /import
Синтаксис YAML — ошибки разбора с подсказкой про отступы/кавычки
JSON Schema — обязательные поля, типы (та же валидация, что выполняет run)
Неизвестные/опечаточные поля — с подсказками «возможно, вы имели в виду» (chek → check), на каждом уровне: поля шагов, параметры with: каждого действия, ключи check:, поля конфигурации, поля report:
Неизвестные идентификаторы действий — std/htp@v1 → did you mean 'std/http@v1'?
GraphQL-документы — запросы std/graphql@v1 разбираются (синтаксические ошибки указывают на /steps/N/with/query) и, когда эндпоинт доступен, валидируются по его интроспектированной схеме. Шаги со schema_file валидируются по локальному SDL, а недоступные эндпоинты дают информационную заметку, но никогда не провал. --offline пропускает сетевой проход

Каждая находка показывает где (/steps/0/with), что не так и что использовать вместо, а вывод завершается ссылкой на справочник по YAML.

Код выхода: 0, если все файлы валидны, иначе 1 — безопасно использовать как CI gate:

- run: perfscale lint tests/*.yaml

`perfscale install`

Загружает удалённые библиотеки генераторов значений (RFC 005), объявленные в libraries:, и фиксирует их для офлайн-прогонов.

perfscale install test.yaml config.yaml
perfscale install test.yaml --refresh   # re-resolve git refs

Каждый use:, являющийся URL https://… или ссылкой git+<repo>@<ref>#<path>, загружается один раз — включая объявления, найденные через цепочки import: — проверяется по дайджесту на соответствие его пину sha256: (только объявленные пины; см. ниже), сохраняется в контентно-адресуемом кэше (<cache>/libraries/<sha256>.wasm) и записывается в TOML-файл perfscale.lock рядом с объявляющим файлом (git-ссылки фиксируются на разрешённый коммит). Закоммитьте lockfile: run и lint разрешают удалённые библиотеки через lock + кэш полностью офлайн, а отсутствующий пин или артефакт кэша — жёсткая ошибка с указанием запустить perfscale install.

sha256: опционален для источников https://… (как и в агенте perfscaled): без него дайджест загруженного артефакта вычисляется, фиксируется в lockfile и печатается с предупреждением, советующим добавить пин в YAML. При наличии пина несовпадение — жёсткая ошибка с указанием обоих дайджестов.

Код выхода: 0, если все удалённые библиотеки установлены (или уже зафиксированы), 1 при ошибках загрузки/проверки (несовпадение sha256 называет оба дайджеста).

install также встраивает (burn) каждую WASM-библиотеку — удалённую и локальную — в AOT- кэш (<cache>/libraries/<sha256>.cwasm), так что run/lint десериализуют предварительно скомпилированный артефакт вместо компиляции на каждый прогон. Эта операция необязательна: библиотека, которую не удалось предкомпилировать, понижается до предупреждения и компилируется во время выполнения. WASM-репортеры (report.reporters[].use: wasm:…) прожигаются так же в <cache>/reporters/<sha256>.cwasm — это явный прогрев кэша репортеров (lint пишет его только в фоне, поэтому workflow из одних lint может его так и не прогреть).

`perfscale burn`

Собирает автономный бинарник со встроенными WASM-библиотеками из документов:

perfscale burn -f test.yaml -c config.yaml -o ./perfscale+libs

Флаг	По умолчанию	Описание
`-f, --file <FILE>`	обязательный, повторяемый	YAML-документ(ы) теста, чьи `libraries:` нужно встроить
`-c, --config <FILE>`	—	Опциональная YAML-конфигурация, чьи `libraries:` также нужно встроить
`-o, --output <FILE>`	обязательный	Путь выходного производного бинарника

Результат — побайтовая копия запущенного бинарника perfscale плюс AOT-предкомпилированные (.cwasm) артефакты всех объявленных WASM-библиотек, дописанные за маркером-окончанием PFSEMBED. Производный бинарник разрешает эти библиотеки из самого себя — ни файлы .wasm, ни кэш, ни perfscale.lock на машине запуска не нужны — что делает его однофайловым дистрибутивом для генераторов нагрузки и контейнеров (см. Запуск perfscale в Docker).

Удалённые ссылки должны быть сначала установлены (perfscale install) — burn разрешает их через lock + кэш офлайн, как run. Встроенные @std — это нативный код, они пропускаются автоматически. Артефакты burn привязаны к сборке, которая их произвела (версия wasmtime, target triple, конфигурация движка): повторно запускайте perfscale burn после обновления perfscale. Burn устраняет компиляцию на прогон, но не накладные расходы на вызов — стоимость вызова библиотеки не меняется.

Код выхода: 0 при успехе, 1, если документ не загружается, WASM-библиотеки не объявлены или библиотека не компилируется как компонент.

`perfscale convert k6`

Конвертирует статически представимый k6-скрипт в нативный YAML без запуска k6 и без отправки запросов:

perfscale convert k6 script.js                         # test.yaml + config.yaml
perfscale convert k6 script.js -t tests/api.yaml -c load.yaml
perfscale convert k6 script.js --force                 # заменить существующие файлы

Флаг	По умолчанию	Описание
`-t, --test <FILE>`	`test.yaml`	Куда записать определение нативного теста
`-c, --config <FILE>`	`config.yaml`	Куда записать конфигурацию прогона
`--force`	выключен	Заменить существующие файлы; без флага коллизия любого выхода прерывает команду до записи

Конвертер разбирает настоящий JavaScript AST. Поддерживаются статические const, строки/конкатенация/templates и __ENV.NAME (→ ${{ env.NAME }}); http.get/post/put/patch/del/delete/head/options/request со статическими URL, телами, headers и timeout; JSON.stringify; проверки status и body.includes; sleep; имена group как префиксы шагов; фиксированные vus + duration, stages и один сценарий ramping-arrival-rate с startRate: 0; insecureSkipTLSVerify; thresholds для http_req_duration, http_req_failed, http_reqs, iterations и dropped_iterations. Перцентили p(50/90/95/99) преобразуются в p50/p90/p95/p99; abortOnFail: true — в отдельный gate abort_on_fail.

Динамический JavaScript, вызовы helpers, циклы/условия, setup/teardown, произвольные check-функции, xk6-модули и опции без точного нативного аналога — ошибка с номером строки и колонки, подсветкой исходника и подсказкой по исправлению, а не молчаливое удаление поведения. Скрипты вне этого подмножества по-прежнему запускаются через perfscale run --k6 script.js. Например:

 --> script.js:4:3
  |
4 |   if (true) {
  |   ^^^^^^^^^^^ unsupported statement `if_statement`; conditions, loops, helper calls, and assignments must be rewritten explicitly
  = help: conditional or repeated execution is not a linear YAML step list; use step-level `if:` where possible, split the flow into explicit steps, or keep this script on `perfscale run --k6`

Результат валидируется по схемам внутри команды; далее выполните:

perfscale lint test.yaml config.yaml
perfscale run -f test.yaml -c config.yaml   # начните с короткого безопасного прогона

`perfscale schema`

Печатает JSON Schema, по которой perfscale валидирует YAML-файлы, — точно те схемы, что используют lint и run, в виде форматированного JSON на stdout.

perfscale schema test     # schema for test definitions (steps)
perfscale schema config   # schema for run configs

Предназначен для всего, что программно создаёт YAML для perfscale:

Автодополнение в редакторе — направьте ваш языковой сервер YAML на этот вывод
Инструментарий агентов — MCP-сервер perfscale вызывает эту команду, чтобы дать моделям контракт авторинга

Код выхода: 0 при успехе.

`perfscale metrics`

Печатает каталог метрик: каждую метрику, объявленную зарегистрированными семействами, в виде таблицы — семейство, имя, вид (counter/gauge/histogram/rate), единица измерения и описание. Встроенные семейства http и llm присутствуют всегда; сборки с pro-модулями показывают и их семейства. См. Метрики.

perfscale metrics

Код выхода: 0 при успехе.

`perfscale man`

Печатает встроенную man-страницу — полный справочник CLI, вкомпилированный в бинарник при сборке. Это путь для Windows, где нет man(1):

perfscale man          # plain-text manual on stdout
perfscale man --raw    # the roff source instead

В Unix установите страницу один раз, чтобы работал man perfscale:

perfscale man --install                                # → ~/.local/share/man/man1
perfscale man --install --dir /usr/local/share/man/man1  # system-wide

--install записывает perfscale.1 в выбранную директорию и обновляет man-индекс, если доступен mandb. Если после этого man perfscale не находит страницу, добавьте родительскую директорию в MANPATH:

export MANPATH="$HOME/.local/share/man:$MANPATH"

Глобальная установка через npm (npm install -g @perfscale/exe) связывает man-страницу автоматически — поле man в npm помещает её в <prefix>/share/man/man1.

Код выхода: 0 при успехе, 1, если --install не может записать в директорию.

`perfscale self-update`

Заменяет запущенный бинарник на последний релиз GitHub для этой платформы. sha256 загрузки проверяется по sha256sums.txt релиза до замены, а сама замена атомарна (файл сначала подготавливается рядом с исполняемым, затем переименовывается) — неудачное обновление никогда не оставляет после себя сломанный бинарник.

perfscale self-update                       # обновиться до последнего релиза (спросит подтверждение)
perfscale self-update --check               # только проверить; exit 10 = обновление доступно
perfscale self-update --force               # переустановить, даже если уже актуально
perfscale self-update --non-interactive     # без вопроса-подтверждения (скрипты, CI)

Перед загрузкой команда спрашивает подтверждение в терминале:

Update perfscale 0.24.0 → 0.25.0? [Y/n]

Enter (пустой ответ) или y/yes продолжают; n/no отменяют с кодом выхода 0 (отказ от обновления — не ошибка). Вопрос выводится в stderr, поэтому stdout остаётся машиночитаемым. Когда stdin — не TTY (CI, пайпы) и --non-interactive не передан, команда завершается ошибкой с подсказкой вместо висящего вопроса, на который некому ответить. --check ничего не спрашивает.

Загрузки рассчитаны на медленные сети: нет общего бюджета времени (44 МиБ на медленном соединении законно качаются минуты), вместо него — лимит простоя 60 с на чтение, до 3 попыток с backoff при обрыве соединения и живая строка прогресса x.x/43.9 MiB в терминале. Обрыв посреди загрузки называется понятно («connection dropped mid-download»), а не сырым «error decoding response body» из reqwest.

Флаг	Описание
`--check`	Сообщить, есть ли обновление, не устанавливая его. Коды выхода: `0` — актуально, `10` — обновление доступно; удобно для скриптов в cron/CI
`--force`	Переустановить последний релиз, даже если версии совпадают
`--non-interactive`	Пропустить вопрос-подтверждение — для скриптов и CI

Установки через npm

Когда perfscale установлен через npm install -g @perfscale/exe, бинарник принадлежит npm — замена его на месте оставила бы метаданные пакета npm, утверждающие про старую версию. self-update обнаруживает это (исполняемый файл находится в node_modules/@perfscale/) и отказывается, предлагая правильную команду:

npm install -g @perfscale/exe@latest

--check по-прежнему работает, а пассивная подсказка ниже предлагает npm-команду для npm-установок автоматически.

Пассивная подсказка «доступно обновление»

Другие команды (run, serve, lint) печатают однострочную подсказку в stderr, когда известен более новый релиз:

perfscale v0.2.0 is available (you have 0.1.0) — run `perfscale self-update`

Проверка намеренно ненавязчива: не более одного сетевого запроса за 24 часа (кэшируется в пользовательской директории кэша), только в интерактивных терминалах (никогда в логах CI или пайпах), никогда не задерживает команду более чем на ~2 с и молчит офлайн.

Переменная	Эффект
`PERFSCALE_NO_UPDATE_CHECK=1`	Полностью отключить пассивную проверку и подсказку
`PERFSCALE_UPDATE_API_BASE`	Переопределить хост API релизов (по умолчанию `https://api.github.com`) — для зеркал/прокси
`PERFSCALE_UPDATE_DOWNLOAD_BASE`	Переопределить хост загрузки артефактов (по умолчанию `https://github.com`)

`perfscale cache`

Кэш импортов/библиотек (~/.cache/perfscale, переопределяется через PERFSCALE_CACHE_DIR) растёт бесконечно: каждый скачанный удалённый импорт и каждый скомпилированный WASM-артефакт адресуются по содержимому и хранятся вечно. Чистится явно:

perfscale cache clean              # удалить все кэшированные импорты и артефакты библиотек
perfscale cache clean --dry-run    # только показать, сколько освободится

Удаление всегда безопасно — всё в кэше перекачиваемо: следующий perfscale install или run пересоберёт то, на что ссылается закреплённый perfscale.lock (ценой одной повторной загрузки/компиляции).

`perfscale init-skills`

Устанавливает встроенные skill-папки для агентов (perfscale-cli, perfscale-library-sdk, perfscale-migration-k6) в .<loop>/skills/ — копируются как есть, повторный запуск перезаписывает:

perfscale init-skills                 # ./.claude/skills/<skill>   (цикл по умолчанию)
perfscale init-skills --loop agents   # ./.agents/skills/<skill>
perfscale init-skills -g              # ~/.claude/skills/<skill>

`perfscale init-agents`

Генерирует определения агентов perfscale-test-{planner,generator,healer} для одного цикла кодирования (по умолчанию claude; также codex, copilot, opencode, vscode, vscode-legacy), регистрирует MCP-сервер @perfscale/mcp в конфиге цикла (npx -y @perfscale/mcp) и инициализирует репозиторий: specs/README.md, «найденный-или-созданный» tests/seed.yaml и минимальный конфиг (или тот, что передан через -c). --prompts дополнительно устанавливает шаблоны промптов perfscale-{plan,generate,heal,threshold}. Перезапускайте после каждого обновления perfscale.

perfscale init-agents --loop vscode --prompts

Полная матрица циклов, генерируемые файлы и правила безопасности нагрузки — в Агентах кодирования.

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

Имя	Описание
`RUST_LOG`	фильтр `tracing`, например `RUST_LOG=debug perfscale run ...`
`PERFSCALE_NO_UPDATE_CHECK`	`1` отключает подсказку о доступном обновлении
`PERFSCALE_CACHE_DIR`	Корень кэша для git-клонов `import:` и установленных библиотек (по умолчанию `~/.cache/perfscale`)