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.