READSEEK(1)

NAME
readseek - structural source reader with stable line hashes

SYNOPSIS
readseek [-h|--help]
readseek [-V|--version]
readseek file [--language language]
    (--stdin --path path | target)
readseek read [--language language]
    [--start line|--offset line]
    [--end line|--limit n]
    (--stdin --path path | target)
readseek map [--language language]
    (--stdin --path path | target)
readseek symbol [--language language] [--line line]
    (--stdin --path path [qualified-name] | target [qualified-name])
readseek identify [--language language]
    [--line line] [--column column]
    (--stdin --path path | target)
readseek definition [-c|--cached] [-o|--others]
    [-i|--ignored] [--language language]
    target name
readseek search [-c|--cached] [-o|--others]
    [-i|--ignored] [--language language]
    target pattern

DESCRIPTION
readseek reads source files and emits pretty-printed JSON for tools that need stable, line-addressable source context. It can detect file languages, return hashed line ranges, build structural source maps, read symbols, identify cursor context, find definitions, and run AST pattern searches.

Source-bearing output uses hashlines: a one-based line number, a 3-character line hash, and the original line text. Line hashes are short stable references that can be used as target suffixes in later calls.

readseek is intended for scripts, editors, and coding agents. Human-facing diagnostics are written separately from JSON output.

INPUTS AND TARGETS
Most commands read a target path. The file, read, map, symbol, and identify commands can instead read unsaved buffer text from standard input with --stdin and --path. With --stdin, --path is required, supplies the document name used for language detection, and is reported in JSON output. A positional target cannot be combined with --stdin.

A target may include a line or hash suffix:

    file:line
    file:hash

Line numbers are one-based. Hash suffixes are the 3-character hashes emitted by read, map, and search.

For symbol, a target may also name a symbol:

    file:symbol

The symbol can also be supplied as a separate qualified-name argument. Qualified names and unqualified names are matched against the structural source map; ambiguous names produce an error.

LANGUAGES
readseek detects languages from file names, extensions, shebangs, and syntax metadata. Use --language when detection is ambiguous, when input comes from a synthetic path, or when a file lacks a useful extension.

Accepted language identifiers are: assembly, bash, c, cpp, csharp, css, dockerfile, gdscript, go, html, java, javascript, json, jsx, just, kconfig, latex, lua, make, markdown, meson, nix, perl, php, puppet, python, riscv, ruby, rust, sql, swift, toml, tsx, typescript, typst, xml, yaml, and zig. The special value unknown forces text-only handling and disables parser-backed features.

COMMANDS

file
    Print detection metadata for the input, including file name, language, parser support, binary flag, MIME type, and syntax name.

read
    Print a line range with line numbers, line hashes, and text. Without a range, the whole file is returned. A target line or hash, --start, or --offset sets the first line. Use --end for an inclusive final line or --limit for a count.

map Print the structural source map: symbol kind, name, qualified name, start and end lines, and boundary hashes. Languages without symbol extraction return an empty symbol list.

symbol
    Print the source range for one symbol. Select it by qualified name, by unqualified name, by file:symbol, by target line or hash, or by --line.

identify
    Print the requested cursor line, line hash, identifier at the cursor, and the enclosing mapped symbol. If --column is omitted, column 1 is used. Columns are one-based byte offsets.

definition
    Find mapped symbol definitions in a file or directory. The name argument matches either a full qualified symbol name or an unqualified name. Directory traversal uses the same file selection rules as search.

search
    Run an AST pattern against a file or every supported source file below a directory. Unparseable and unsupported files are skipped. Pattern variables use $NAME for one node and $$$NAME for zero or more sibling nodes.

Search output is grouped by file and includes the file hash, matched ranges, captures, boundary hashes, and hashlines for each match.

OPTIONS

-h, --help
    Display usage information and exit.

-V, --version
    Print the program version and exit.

--language language
    Override language detection for commands that parse source text. See LANGUAGES.

--stdin
    Read document contents from standard input instead of opening a target path. Requires --path.

--path path
    Document path to associate with --stdin. The path is used for language detection and appears in JSON output.

--line line
    One-based target line for symbol or identify.

--column column
    One-based byte column for identify. Identifier ranges in JSON use a one-based inclusive start column and a one-based exclusive end column.

--start line
    First one-based line to include for read.

--offset line
    Alias for --start.

--end line
    Last one-based line to include for read. Cannot be combined with --limit.

--limit n
    Maximum number of lines to include for read. Cannot be combined with --end.

-c, --cached
    When searching a directory inside a Git repository, include tracked/indexed files.

-o, --others
    When searching a directory inside a Git repository, include untracked, non-ignored files.

-i, --ignored
    With --others, also include ignored untracked files. Inside a Git repository, --ignored requires --others.

DIRECTORY SEARCH
The definition and search commands accept either a file or a directory. A file target is searched directly. A directory target is searched recursively.

Inside a Git work tree, directory searches use Git-aware selection. With no selection flags, readseek searches tracked/indexed files and untracked, non-ignored files. Use --cached or --others to restrict the selection. Outside Git work trees, selection flags are ignored and normal recursive traversal is used.

ENVIRONMENT

READSEEK_CACHE_DIR
    Override the base cache directory. When set, readseek stores the source-map cache below READSEEK_CACHE_DIR/readseek.

EXIT STATUS

0   Success.

1   Operational error, such as a missing file, unsupported binary input, malformed input, cache error, or symbol lookup failure.

2   Usage error.

FILES

READSEEK_CACHE_DIR/readseek/cache.sqlite3
    Source-map cache when READSEEK_CACHE_DIR is set.

${XDG_CACHE_HOME:-~/.cache}/readseek/cache.sqlite3
    Typical Linux cache location.

EXAMPLES
Detect a file:

    readseek file src/main.rs

Read lines 10 through 20:

    readseek read src/main.rs --start 10 --end 20

Read 12 lines starting near a target line:

    readseek read src/main.rs:42 --limit 12

Read unsaved buffer text from standard input:

    printf '%s\n' 'fn main() {}' | readseek read --stdin --path scratch.rs

Build a structural map:

    readseek map src/main.rs

Read a symbol by suffix or by containing line:

    readseek symbol src/main.rs:run
    readseek symbol src/main.rs:270

Identify cursor context:

    readseek identify src/main.rs:42 --column 8

Find definitions in tracked files:

    readseek definition -c src run --language rust

Search Rust functions with an AST pattern:

    readseek search -c src 'fn $NAME() { $$$BODY }' --language rust

BUILDING
Build from source with:

    cargo build --release

The included Makefile also provides install and uninstall targets.

LICENSE
The native readseek program is licensed under LGPL-2.1-or-later.

SEE ALSO
cargo(1)