Перейти к основному содержимому

Как запускать proximamp из скриптов и ИИ-агентов

Добавьте к команде --json: ответ придёт одной строкой JSON, ошибка тоже, а код выхода скажет, что случилось. Так proximamp читают скрипты, CI и ИИ-агенты.

Ответ в JSON​

У каждой команды есть параметр --json: ответ печатается одной строкой JSON в стандартный вывод, а в поток ошибок ничего не пишется. Ошибка приходит так:

{"error":{"code":"not_signed_in","exitCode":3,"message":"...","docs":"https://docs.proximamp.com/errors/not-signed-in"}}

Если программе есть что подсказать, в ошибке есть и поле hint. Поле docs есть у ошибки, для которой на этом сайте есть страница с причинами и шагами; без --json её адрес стоит последней строкой сообщения. Буквы не латиницы записываются как \uXXXX, поэтому ответ читается одинаково при любой кодировке терминала.

Команды tcp, udp, http, https и up печатают по строке на каждое событие туннеля. Первая — {"event":"open","tunnelId":"t1","type":"tcp","address":"…","localPort":25565}, дальше reconnecting, connected, addressChanged и closed с теми же полями. У up в каждом событии есть ещё name, имя туннеля, а туннель, который открыть не удалось, приходит событием failed (с --wait-sign-in — refused). Пока up --wait-sign-in ждёт входа, он печатает {"event":"waitingSignIn"}, а пока нет связи с ProximaMP — {"event":"waitingService"}. У http и https с --inspect приходит и адрес инспектора, {"event":"inspector","url":"…","expiresInSeconds":60}, и его подсказки, событие inspectorNote.

Коды выхода​

Код выхода называет причину: 0 — готово, 2 — команда набрана неверно, 3 — вход не выполнен, 4 — нет связи с ProximaMP, 5 — ProximaMP отказал. Смысл кодов не меняется от версии к версии; все коды — в справочнике и в выводе proximamp help exit-codes.

Без вопросов​

Без терминала, например в CI или с --json, команда ничего не спрашивает: всё нужное передаётся параметрами, иначе она завершается с кодом 2 и подсказкой, что передать. Пароль и ключ передаются на стандартный ввод, а не аргументом:

printf '%s\n' "$PASS" | proximamp login alice --password-stdin
proximamp login --key-stdin < key.txt

В PowerShell нет printf, а < не работает:

$env:PASS | proximamp login alice --password-stdin
Get-Content key.txt | proximamp login --key-stdin

Буквы не латиницы Windows PowerShell 5.1 передаёт как «?»: если они есть в пароле, входите ключом. Для скриптов и CI лучше ключ устройства, чем пароль аккаунта.

Адрес туннеля в скрипте​

Команда туннеля работает, пока туннель открыт, поэтому запустите её в фоне и дождитесь первой строки:

proximamp tcp 25565 > addr.txt &
until [ -s addr.txt ]; do sleep 1; done
head -1 addr.txt

Первая строка открывает туннель в фоне и пишет его адрес в addr.txt, вторая ждёт, пока адрес появится в файле, третья печатает его. Если адрес сменится, команда допишет в файл строку с новым: нынешний адрес даёт tail -1 addr.txt.

В PowerShell:

$p = Start-Process proximamp -ArgumentList 'tcp', '25565' -WindowStyle Hidden -PassThru
do {
    Start-Sleep 1
    $t = (proximamp ls --json | ConvertFrom-Json).tunnels | Where-Object { $_.here -and $_.localPort -eq 25565 -and $_.address } | Select-Object -First 1
} until ($t -or $p.HasExited)
$t.address

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

proximamp tcp 25565

Закрыть этот туннель:

proximamp close $t.address

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

  • PROXIMAMP_LANG: язык сообщений, ru или en. Без неё язык берётся из настроек системы.
  • PROXIMAMP_KEY: ключ устройства, которым программа входит при запуске. Переменную видно, например, в docker inspect, поэтому лучше --key-stdin из файла.
  • PROXIMAMP_LOG: error, warn, info или debug, журнал в поток ошибок.
  • PROXIMAMP_NO_UPDATE_CHECK: любое значение выключает ежедневную проверку новой версии.

Для ИИ-агентов​

proximamp help --json отдаёт все команды, их параметры, коды выхода и адреса страниц ошибок одной строкой JSON. Справка по одной команде:

proximamp help tcp --json

Проверьте​

proximamp whoami --json
echo $?

В PowerShell код выхода хранится в $LASTEXITCODE:

proximamp whoami --json
$LASTEXITCODE

Вошли — первая команда печатает строку JSON с вашим логином, вторая — код 0; не вошли — ошибку not_signed_in и код 3.