Skip to main content

How to run proximamp from scripts and AI agents

Add --json to a command: the answer comes as one JSON line, an error too, and the exit code says what happened. That is how scripts, CI and AI agents read proximamp.

The answer in JSON​

Every command takes --json: the answer is printed as one JSON line to standard output, and nothing goes to standard error. An error looks like this:

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

When the program has advice to give, the error also has a hint field. The docs field comes with an error that has a page with its causes and steps on this site; without --json its address is the message's last line. Non-Latin letters are written as \uXXXX, so the answer reads the same in any terminal encoding.

The tcp, udp, http, https and up commands print one line per tunnel event. The first is {"event":"open","tunnelId":"t1","type":"tcp","address":"…","localPort":25565}, then reconnecting, connected, addressChanged and closed with the same fields. Every event of up also has name, the tunnel's name, and a tunnel that could not open comes as a failed event (refused with --wait-sign-in). While up --wait-sign-in waits for a sign-in, it prints {"event":"waitingSignIn"}, and while ProximaMP can't be reached, {"event":"waitingService"}. With --inspect, http and https also print the inspector's address, {"event":"inspector","url":"…","expiresInSeconds":60}, and its notes, the inspectorNote event.

Exit codes​

The exit code names the cause: 0 is done, 2 is a mistyped command, 3 is not signed in, 4 is no connection to ProximaMP, 5 is a ProximaMP refusal. The codes keep their meaning from version to version; all of them are in the reference and in the output of proximamp help exit-codes.

No prompts​

Without a terminal, in CI or with --json for example, a command asks nothing: everything it needs comes in options, or it exits with code 2 and a hint at what to pass. A password or a key goes in on standard input, never as an argument:

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

PowerShell has no printf, and < doesn't work there:

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

Windows PowerShell 5.1 passes letters other than Latin as "?": if your password has them, sign in with a key. For scripts and CI, a device key is better than the account password.

A tunnel's address in a script​

A tunnel command runs while the tunnel is open, so start it in the background and wait for the first line:

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

The first line opens the tunnel in the background and writes its address to addr.txt, the second waits until the address is in the file, the third prints it. If the address changes, the command adds a line with the new one to the file: tail -1 addr.txt gives the current address.

In 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

If there is no address and the tunnel command has ended, the same command in an ordinary window shows why:

proximamp tcp 25565

To close this tunnel:

proximamp close $t.address

Environment variables​

  • PROXIMAMP_LANG: the language of messages, ru or en. Without it, the language comes from the system's settings.
  • PROXIMAMP_KEY: a device key the program signs in with when it starts. The variable shows, for example, in docker inspect, so --key-stdin from a file is better.
  • PROXIMAMP_LOG: error, warn, info or debug, a log to standard error.
  • PROXIMAMP_NO_UPDATE_CHECK: any value turns off the daily check for a new version.

For AI agents​

proximamp help --json gives every command, its options, the exit codes and the addresses of the error pages as one JSON line. Help on one command:

proximamp help tcp --json

Check​

proximamp whoami --json
echo $?

In PowerShell the exit code is in $LASTEXITCODE:

proximamp whoami --json
$LASTEXITCODE

Signed in, the first command prints a JSON line with your login and the second the code 0; not signed in, the not_signed_in error and the code 3.