CLI Reference

onprest-gateway

create-agent-secret prints the private key for the agent’s gateway.agent_private_key and the public key for GATEWAY_AGENT_PUBLIC_KEY.

create-key takes a comma-separated capability list, or "*" for all capabilities:

./onprest-gateway create-key --name partner-a --capabilities "get_customer,get_orders"

Store only the printed key_hash in GATEWAY_API_KEYS_JSON and give the plaintext key to the caller.

onprest-agent

The configuration path is taken from --config (alias --capability-file), then the AGENT_CAPABILITY_FILE environment variable, then capability.yaml next to the binary.

Validate the configuration

./onprest-agent validate --config ./capability.yaml
./onprest-agent validate --config ./capability.yaml --format json

validate loads the configuration and prepares every referenced source, exactly as startup does: for databases it connects (waiting up to 10 seconds) and runs EXPLAIN for each statement; HTTP sources are not called. It never runs a capability or contacts the gateway, so success does not prove that the gateway is reachable.

Success prints one line, or JSON with --format json:

validation succeeded: driver=postgres capabilities=2

{ "valid": true, "database_driver": "postgres", "capabilities": 2 }

Without DB capabilities, the driver is empty. On failure, text goes to stderr and JSON to stdout with valid: false, a stage (config, busy, detail_log, database_open, database_ping, capability_explain, canceled, or internal), and a message. If the failure was recorded in a log file, its path is printed (detail_log in JSON); see Agent Local Logs.

Diagnose the gateway connection

./onprest-agent doctor --config ./capability.yaml --format json

doctor runs the validate checks, then the gateway’s DNS, TCP connection, TLS, challenge, and key verification, each bounded to 10 seconds (60 seconds in total). It prints one line per check, or JSON:

{
  "ok": true,
  "checks": [
    { "stage": "config", "status": "passed", "code": "OK", "message": "configuration is valid" }
  ]
}

A failed check is failed and the checks that depend on it are skipped. With ws://, the TLS check is skipped. doctor does not replace a running agent’s connection or run a capability. See Troubleshooting for what each failure means.

Run as a service

./onprest-agent service install --config /absolute/path/capability.yaml
./onprest-agent service start
./onprest-agent service stop
./onprest-agent service status
./onprest-agent service uninstall

The commands use systemd on Linux, launchd on macOS, and Windows Service on Windows. install without --config registers capability.yaml next to the binary, and does not enable start on boot. remove is an alias for uninstall. There is no restart; use the change procedure, which validates first.

Run every command except status with administrator rights; see Capability Changes.

Author commands

These run on the machine where you write code, not on the agent host. Writing code in Go shows them in context.

onprest-agent code build --source DIR --output FILE
onprest-agent code build --config FILE --capability NAME [--source DIR]
onprest-agent code validate --module FILE
onprest-agent code test --config FILE --capability NAME [options]
onprest-agent code test --build --config FILE --capability NAME [--source DIR] [options]

Without --input-mime, code test takes the MIME type from common extensions, ignoring case (.txt, .csv, .json, .pdf, .png, .jpg, .jpeg, .gif, .mp4, .zip), and uses application/octet-stream for any other file. Use --input-mime with the same pointer to send a different type.

code build needs Go 1.26.9 or later and keeps an existing module if the build fails. code test really performs whatever the capability does; its result goes to stdout and diagnostics to stderr. Exit codes: 0 success, 1 failure, 2 usage error.

Build from source

Building is optional; release archives need no source or Go toolchain. With the Go version in go.mod:

make build        # dist/onprest-gateway, dist/onprest-agent
make build-cross  # dist/<os>-<arch>/ for every supported platform

Set VERSION=x.y.z to embed a version in both binaries; otherwise they report dev. The binaries are built with CGO_ENABLED=0.