Advanced commands and structured output

Use the executable built in the first-check guide, from the Glassknock project folder on the intended receiving computer or at the same network viewpoint. You need an approved RTSP or RTSPS endpoint and permission to test it. The tool receives video during a sample; it creates no recording.

Feed configuration

{
  "id": "rear-gate",
  "url": "rtsp://192.0.2.10:554/live",
  "duration_seconds": 30,
  "timeout_seconds": 5,
  "gap_seconds": 3
}

Field	Meaning	Bounds/default
id	A stable local label for this feed. Use a non-sensitive label. It appears in reports.	1–64 letters, digits, _, or -; first character is a letter or digit.
url	The supplied RTSP or RTSPS endpoint. Do not include a username, password, or access token. It is excluded from reports.	Required. Without an explicit port, RTSP uses 554 and RTSPS uses 322.
duration_seconds	Requested reception sample duration.	1–300; default 30.
timeout_seconds	Connection/request timeout.	1–30; default 5.
gap_seconds	Maximum allowed media gap during the sample.	1–sample duration; default 3, capped to duration for samples shorter than 3 seconds.
allow_plaintext_credentials	Explicit approval to use the viewing account over plain RTSP.	Default false.

These settings describe one feed. An RTSP path identifies the requested video. The same camera may expose different paths for different feeds. Test the path that the monitoring system intends to use.

Check

Choose one command below. These are alternatives; use a new report filename for each run.

./glassknock check --config feed.json
./glassknock check --config feed.json --output before.json
./glassknock check --config feed.json --json --output before.json

Text is the default. --json sends the versioned report to standard output. --output also saves a JSON report at the specified path. The file is created with restrictive permissions and is not overwritten.

The command does not discover endpoints, guess accounts, select other video paths, or change camera settings. Run ./glassknock check --help for accepted flags.

Credentials

For a protected endpoint, select local terminal entry explicitly:

./glassknock check --config feed.json --credentials --output before.json

This needs an interactive terminal and hides credential entry. The tool does not prompt without a credential option. Have the human enter the approved viewing account locally; keep credentials out of the agent conversation.

If the endpoint is plain rtsp://, the tool requires "allow_plaintext_credentials": true in the feed configuration before using credentials. This is explicit approval to use an unencrypted transport. Digest authentication does not encrypt video or the connection. Prefer rtsps:// when the equipment supports it and its certificate can be verified. Do not disable certificate verification to obtain a pass.

For a local secret integration, use:

./glassknock check --config feed.json --credentials-stdin --output before.json

This reads one JSON object from standard input with the fields username and password. The username must be nonempty when a credential input is selected. Credentials are used in memory for this run. Supply them from a local secret source, outside the AI conversation. --credentials and --credentials-stdin are mutually exclusive.

If you already have a private local credential file, you can redirect it:

./glassknock check --config feed.json --credentials-stdin --output before.json < /private/path/viewer.json

The file contains the viewing account as JSON. This file is a secret source; Glassknock does not create it or remove it. Protect it using your operating system’s permissions. A secret manager that writes this JSON to standard output can also provide input. Do not put the JSON, password, or a credential-bearing URL in shell arguments, the configuration, a report, or the agent chat.

An agent must not read the secret source into its context. Have the human or an approved local secret integration supply it directly to the tool. The tool supports diagnosis without credentials and reports protected access as incomplete.

Compare

After a correction, repeat the same configuration from the same computer:

./glassknock check --config feed.json --output after.json
./glassknock compare before.json after.json
./glassknock compare before.json after.json --json

Supply the approved credentials again if the first test used them. Corrected credentials can differ from the failed attempt. The comparison checks report compatibility before interpreting the result. It cannot prove a fix when the feed was not rechecked or the later result is unknown. See comparison rules.

Exit statuses

For check:

Status	Meaning
0	All applicable checks passed.
1	Findings were observed.
2	The test was incomplete or an execution/input error occurred.

A command can return structured results with a nonzero status. Agents should inspect that output. With --json, usage/input errors are credential-safe JSON on standard output. Without --json, errors are text on standard error.

For compare, 0 means the reports were compared successfully; read the individual changes to see whether a finding was resolved. 2 means an error or incompatible reports. A successful comparison does not mean every check passed.

Version

./glassknock version

Include the version, operating system, and sanitized report when asking for help. Never attach the feed configuration or credential source without a separate review.

Structured output, version 1

State strings use the exact spelling in the results guide. Agents should use check IDs, states, and codes rather than parse the human-readable message. Device text and URLs are not part of the report.

Field	Purpose
schema_version	Output contract version, "1".
rules_version	Measurement rule version, "1".
tool_version	Glassknock version used for the run.
target_id	User-supplied local feed label.
target_fingerprint	Correlation hash for endpoint and test configuration; excludes credentials.
runner_id	Hash of this computer’s hostname. Computers can share a hostname; this does not prove machine identity or an unchanged network route.
started_at	Test start time in UTC.
observation_seconds	Actual media observation duration.
requested_seconds	Requested sample duration. Compare it with the actual observation duration.
complete	A completed sample or confirmed failure ended the run. It can be true with no video sample. True does not mean video works; review states and observation time.
checks	Results with id, state, code, and message.
metrics	Measured packet/frame counts, gaps, and processing errors.
limits	Statements that qualify the results.

Metric	Meaning
rtp_packets	Received RTP media packets. Packets alone do not prove usable video.
decoded_frames	Frames actually decoded by FFmpeg.
first_frame_seconds	Time to the first decoded frame, when available.
max_packet_gap_seconds	Longest observed gap in received media packets.
max_frame_gap_seconds	Longest observed gap in decoded frames.
rtp_decode_errors	Errors while assembling received media.
local_queue_drops	Media dropped by the local processing queue.

Frame times are local decoder output times. They do not measure the camera’s frame rate or end-to-end video delay.

Reports exclude endpoint URLs, credentials, and free-form device text. The local target ID remains visible. Review it before sharing. The hashes support comparison; they are not guarantees of anonymity.

Comparison output

The comparison JSON contains schema_version, target_id, and changes. Each change has id, before, after, and change. Change values are resolved, persistent, new, not reverified, changed, or unchanged. A general changed state is not a verified repair.