READSEEK(1)

NAME
readseek - structural source-code reader with stable line hashing

SYNOPSIS
readseek [-h|--help]
readseek [-V|--version]
readseek detect [--language language]
    (--stdin --path path | target)
readseek read [--language language]
    [--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 | target) [--name qualified-name]
readseek identify [--language language]
    [--line line] [--column column]
    (--stdin --path path | target)
readseek definition [--stdin] [--compact] [-c|--cached] [-o|--others]
    [-i|--ignored] [--language language]
    target [name]
readseek references [--compact] [-c|--cached] [-o|--others]
    [-i|--ignored] [--language language]
    target name
readseek search [-c|--cached] [-o|--others]
    [-i|--ignored] [--language language]
    target pattern
readseek init [path]

DESCRIPTION
readseek is a command-line tool that reads source files and outputs pretty-printed JSON. It is designed for scripts, editors, and coding agents that need stable addressable source context. Every output line carries a hashline: a line number, a short 3-character hash, and the original text. These hashes are stable anchors that let subsequent calls refer back to specific lines without depending on shifting line numbers. Diagnostics and errors are written separately from JSON output, making the tool safe to pipe into other programs.

INPUTS AND TARGETS
Most commands take a file or directory target on the command line. The detect, read, map, symbol, and identify commands can alternatively read from standard input with --stdin, which requires --path to supply a filename used for language detection and output metadata. You cannot combine --stdin with a positional target. A target path may carry a suffix that selects a specific line:
    file:line
    file:hash
Line numbers are one-based. A hash suffix is a 3-character string that was previously emitted by read, map, or search output. For symbol, you can also pass --name with a qualified or unqualified symbol name. If the name matches more than one symbol the command reports an error. For definition, the --stdin flag reads a JSON object previously produced by identify. The lookup tries symbol.qualified_name first and falls back to identifier.text.

LANGUAGES
readseek detects the language from the file name, extension, shebang line, and syntax hints. Pass --language when detection is ambiguous, when input comes from a synthetic path, or when a file has no meaningful extension. The following language identifiers are accepted: 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, vimscript, and zig. The special value unknown treats the input as plain text and disables any parser-based features.

COMMANDS

detect
    Print detection metadata for the input: filename, detected language, whether a parser is available, whether the content is binary, MIME type, and syntax name.

read
    Print line numbers, hashes, and text for a range of lines. Without any range options the entire file is returned. Use a line or hash suffix on the target path, or pass --offset, to set the first line. Use --end for the last line (inclusive) or --limit for a count; the two cannot be combined.

map Print the structural source map: each top-level symbol's kind, name, qualified name, start and end line, and boundary hashes. For languages that do not support symbol extraction the output contains an empty symbol list.

symbol
    Print the source range for one symbol. Pick it by --name (qualified or unqualified) or by --line. When only --line is given, the symbol that contains that line is resolved.

identify
    Print the requested cursor line, its hash, the identifier at the cursor position, and the enclosing mapped symbol. If --column is omitted, column 1 is used. Columns are one-based byte offsets. Identifier ranges in the JSON use a one-based inclusive start column and a one-based exclusive end column.

definition
    Find definitions of a mapped symbol in a file or directory. The name argument matches a fully qualified or unqualified symbol name. With --stdin and no name, the name is read from an identify JSON object on standard input. Directory search follows the same file-selection rules as search. Use --compact to emit quickfix-friendly location entries instead of full definition objects.

references
    Find all occurrences of an identifier in a file or directory. Output is a flat list of locations with file, line, column, line hash, line text, and the enclosing symbol when available. Directory search rules are the same as for search. Use --compact to flatten symbol metadata into each location entry.

search
    Run an AST pattern against a file or every supported source file under a directory. Files that cannot be parsed or are in unsupported languages are skipped. Pattern variables use $NAME to match a single node and $$$NAME to match zero or more sibling nodes. Output is grouped by file and includes the file hash, matched ranges, captures, boundary hashes, and hashlines for each match.

init
    Initialize a .readseek/ directory under path (defaults to the current directory). This directory holds the source-map cache used by other commands. When a .readseek/ directory exists, readseek refreshes the cache internally on each invocation.

OPTIONS

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

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

--language language
    Force a specific language instead of auto-detection. See LANGUAGES above.

--stdin
    Read input from standard input instead of a file. Requires --path. For definition this reads an identify JSON object instead.

--compact
    For definition and references, emit flat locations arrays with editor-friendly fields instead of the default command-specific JSON shape.

--path path
    Document path to associate with --stdin input. Used for language detection and reported 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.

--offset line
    First line to include when reading. Cannot be combined with --end or --limit when a target line suffix is also present.

--end line
    Last line to include when reading. Cannot be combined with --limit.

--limit n
    Maximum number of lines to include when reading. Cannot be combined with --end.

-c, --cached
    When searching a directory inside a Git repository, search tracked and indexed files.

-o, --others
    When searching a directory inside a Git repository, search untracked files that are not ignored.

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

DIRECTORY SEARCH
The definition, references, and search commands accept either a single file or a directory. A file is searched as-is; a directory is searched recursively. Inside a Git work tree, directory searches are Git-aware. Without any selection flags, readseek searches both tracked/indexed files and untracked, non-ignored files. Pass --cached or --others to restrict to one group. Outside a Git work tree the selection flags are ignored and a normal recursive walk is used.

ENVIRONMENT

READSEEK_CACHE_DIR
    Override the base cache directory. When set, the source-map cache is stored under READSEEK_CACHE_DIR/readseek.

EXIT STATUS

0   Success.

1   Operational error: file not found, binary input, malformed input, cache failure, or symbol lookup failure.

2   Usage error: incorrect invocation or argument combination.

FILES

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

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

EXAMPLES
Detect the language of a file:
    readseek detect src/main.rs
Read lines 10 through 20:
    readseek read src/main.rs --offset 10 --end 20
Read 12 lines starting from line 42:
    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 of a file:
    readseek map src/main.rs
Look up a symbol by name or by the line it's on:
    readseek symbol src/main.rs --name run
    readseek symbol src/main.rs:270
Identify what's under the cursor at line 42, column 8:
    readseek identify src/main.rs:42 --column 8
Find definitions of a symbol in tracked files:
    readseek definition -c src run --language rust
Find references to a symbol in tracked files:
    readseek references -c src main --language rust
Search Rust functions with an AST pattern:
    readseek search -c src 'fn $NAME() { $$$BODY }' --language rust

BUILDING
Build from source:
    cargo build --release
The included Makefile also provides install and uninstall targets.

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

SEE ALSO
cargo(1)