CLI · EXECUTION

Results and diagnostics

Results are morphological candidates verified under the chosen query, POS, boundary, and resources. No matches does not prove that the source contains no relevant content. Diagnostic commands on this page use the native CLI.

No-match checks

Check the exit status and stderr first. For ordinary searches, 1 means no match and 2 means an error. If there is no error, compare one condition at a time on the same file.

# Inspect query analysis and resources
kfind --explain-query --pos verb 걷다

# Compare only the boundary condition on the same file
kfind --pos verb --boundary smart 걷다 sample.txt
kfind --pos verb --boundary any 걷다 sample.txt

# Search a known surface form from the source
kfind --literal 걸었다 sample.txt

If only any finds a match, boundary or structural constraints may have filtered the candidate. Inspect its context because any also includes unwanted word-internal candidates. If neither boundary finds it, check the lemma, POS, spelling, and resource coverage. Typo correction and synonym expansion are not supported.

Also verify that the file was searched. Native ignore, glob, and encoding settings differ from npm traversal rules. --explain-query describes query analysis and the search plan; it does not enumerate every rejected source candidate.

걷다 and 걸다 share the form 걸어, so searching for 걷다 can return both 길을 걸어 (walk along the road) and 전화를 걸어 (make a phone call). Even smart does not distinguish their meanings in context. A valid morphological candidate is not necessarily a match for the intended meaning.

Structural limits

Candidates that require structural verification use a bounded source window. The defaults are 256 raw bytes and 64 Unicode scalars after normalization, applied to the current token and required adjacent context. These are not limits on the entire input file.

If window extraction, structural graph preparation, or coordinate alignment fails, the candidate is excluded. The native CLI writes the path and structural_verification_incomplete to stderr and exits with status 2 while preserving matches already written to stdout. This applies to text, JSON Lines, count, file-list, and quiet modes.

The diagnostic identifies unavailable structural context verification, without counting candidates. Its absence does not guarantee coverage of unsupported morphology or input after an early exit. Rust callers can inspect the same state with find_all_with_diagnostics and SearchDiagnostics. This diagnostic contract does not apply to the npm CLI.

When omissions matter, compare any with literal searches for known source forms. This does not guarantee recovery of unsupported inflections, typos, or semantic matches.

Diagnostic format

Human-readable diagnostics go only to stderr, leaving match output on stdout. Messages identify the failing option, path, or resource condition.

JSON Lines mode does not mix diagnostics into JSON records. Callers should preserve both streams and the final status.

Error classes

Compile errors include empty queries, tag/global POS conflicts, invalid options, and plan-limit failures. Resource errors include missing data and failed version, schema, source-identity, or digest checks.

Input errors cover path lookup, decode, and reads. Output errors cover stdout writes other than a normal broken pipe.

Exit status

The native CLI follows command-specific status rules; the npm CLI returns 0 for matches, 1 for no match, and 2 for errors. A set -e shell must explicitly allow the no-match status when appropriate.

Partial stdout is not a complete result when the final status reports an error.