CLI reference
Run a check from your terminal.
Run each command in the environment where the problem occurs. CLI examples below use the
GitHub v0.3.0 prerelease package and require
Node 24 and npm. npm exec downloads the pinned package without
a global install.
Terms on this page: Evidence is the single JSON EvidenceBundle that a CLI or Agent run writes to stdout: observed facts, explicit unknowns, policy decisions, and redaction notes. Bounded means each check has a fixed scope, time limit, and size limit, and changes nothing on your system.
Public IP · no CLI installation
Query the public IP NetOkay sees from this request. Curl is enough; Node is not required.
curl -fsS --max-time 10 -w '\n' https://netokay.net/v1/control/self
The JSON contains client_ip, ip_family, and
observed_at. Paste it into Compare environments. A
shared public IP does not establish the same DNS, certificate handling, or application
path.
HTTP target
npm exec --yes --package=https://github.com/flreey/netokay-cli/releases/download/v0.3.0/netokay-0.3.0.tgz -- netokay diagnose https://netokay.net/
Replace the URL with your public target. The default transport checks HTTP response
headers from this process; it does not validate response bodies, login, or your
application’s operation. Use http:80 or https:443. Private or
sensitive targets, query strings, fragments, userinfo, and arbitrary ports are rejected.
Streaming (SSE)
npm exec --yes --package=https://github.com/flreey/netokay-cli/releases/download/v0.3.0/netokay-0.3.0.tgz -- netokay diagnose https://netokay.net/v1/control/stream --transport sse
This example observes NetOkay’s short control stream. For your own public HTTPS endpoint, replace the URL and compare the expected completion signal with the observed events. Read the SSE observation’s status, completion, event count, and available arrival timing. Complete data and evenly paced delivery are different observations. Timing alone cannot identify which application, intermediary, or client caused grouped arrivals.
Secure WebSocket (WSS)
npm exec --yes --package=https://github.com/flreey/netokay-cli/releases/download/v0.3.0/netokay-0.3.0.tgz -- netokay diagnose https://netokay.net/v1/control/ws --transport wss
Supply an https:// URL on port 443; the CLI maps it to a secure WebSocket.
This bounded template sends a challenge and expects a byte-identical echo and a normal
close. A service using a different message protocol can fail this template while still
supporting WebSocket. Read the WSS observation’s echo and close facts before drawing a
conclusion.
MCP endpoint · replace the target
The following is a template for a public MCP Streamable HTTP endpoint you control or are
authorized to test. Replace https://mcp.example.com/mcp with the real
endpoint; the example hostname is a placeholder, not a working demo. NetOkay does not host
an MCP server.
npm exec --yes --package=https://github.com/flreey/netokay-cli/releases/download/v0.3.0/netokay-0.3.0.tgz -- netokay diagnose https://mcp.example.com/mcp --transport mcp
If authentication is required, make the token available in an environment variable in your
terminal and append --auth-token-env MCP_TOKEN. Pass the variable’s name,
never the token value. Do not put credentials in the URL or paste them into this website.
The check observes protocol negotiation and advertised capability categories. It does not invoke tools, resources, prompts, or business operations. A successful result does not prove that your Agent can complete a task. SSE, WSS, and MCP targets require public HTTPS on port 443, with no query strings, fragments, or userinfo.
Read the result
Stdout contains one JSON EvidenceBundle. Read the relevant entry in
observations, its status, result_code,
facts, and stated limitations. SSE, WSS, and MCP details are under
facts.template_facts. HTTPS baseline success does not make the selected
transport check successful; a failed or incomplete observation does not establish a unique
cause. Keep the process exit status with its output.
For the control examples above, look for SSE_PASSED with seven events, or
WSS_PASSED with byte_identical_echo and
normal_close
both true. The preliminary HEAD request to these transport URLs can receive a 4xx
response; that still records an HTTP response, not a transport failure. Read the selected
transport observation separately.
netokay version reports the package version and capabilities;
netokay schema returns its Evidence schema. The optional
--out writes a new local file with mode 0600, byte-identical to
stdout. It never overwrites an existing file. See
Evidence schema for result fields and
Agent invocation for the Skill handoff.