Skip to main content
With npx, put npx @webhooktrap/agent@1 in place of webhooktrap. Every command prints its usage with --help. An unknown command exits 2.

version

Prints the version, commit, protocol, Go version, OS and architecture. webhooktrap with no arguments and webhooktrap --version do the same.

pair

Joins this machine to the workspace that showed the code in its browser. The code is 10 characters, accepted in any case, with or without the hyphen; it expires after 10 minutes. The agent creates a key for the server, sends the code, prints the server, the workspace, the agent name and the key’s fingerprint (SHA256:…, as the browser shows it), and asks Join? [y/N]. When you don’t join, it unpairs and deletes the key.
Pair an agent page with the code and the npx pair command framed.

Agents › Pair a new agent shows the code and the command.

The code can come before or after the flags. webhooktrap agent pair <CODE> is the same command.
The built-in default server of agent 1.0.0 is https://webhooktrap.dev. Pass --server https://app.webhooktrap.dev (or set WEBHOOKTRAP_SERVER) until a release changes it.
https:// is required and verified against the system roots. Redirects are never followed. Without a terminal, pair can’t ask and doesn’t join, unless --yes applies.

agent

Connects to the server this machine is paired with and runs the scenarios started from the browser against the target declared in webhooktrap.yml. It sends a heartbeat every 20 seconds, waits for jobs, and reconnects with backoff (up to 60 s) when the connection drops. Ctrl-C stops it. Before a run reaches a new target, the agent asks in the terminal whether runs from the browser may send to it, with the side-effect warning. If webhooktrap.yml has cmd: probes or a reset, it lists them and asks again whenever the file changes. Without a terminal it declines the job as needing confirmation, prints one line, and checks again after 5 s, 10 s, 20 s, up to 1 minute. webhooktrap agent unpair [--server URL] removes the agent on the server and deletes its local key.

test

Runs the scenarios against the target in webhooktrap.yml with local fixtures, prints the verdict, writes the run document and exits per --fail-on. No server is involved. See Test in CI.

rejudge

Recomputes the verdict from a local run document’s plan and observations, with the pack version named in the document, and checks it matches.

Environment variables

Server commands

The image also runs the engine as services: serve-sandbox and its health check sandbox-ping (the app’s network-free sandbox), and serve-run (the server runner). They are started by Docker Compose and are not meant to be run by hand. See Self-host.