Documentation
¶
Overview ¶
Copyright © 2026 nmdra
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Copyright © 2026 nmdra ¶
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Copyright © 2026 nmdra ¶
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Copyright © 2026 nmdra ¶
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Copyright © 2026 nmdra ¶
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Copyright © 2026 nmdra ¶
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Copyright © 2026 nmdra ¶
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Copyright © 2026 nmdra ¶
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Copyright © 2026 nmdra ¶
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Copyright © 2026 nmdra ¶
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Index ¶
- func ObsidianURI(vaultName, filePath string) string
- func ParseAndRun(ctx context.Context, version, commit, date string, defaultConfig []byte, ...) error
- type BacklinksCmd
- type BoostedCmd
- type CLI
- type ChunkDisplayFlags
- type ConnectionsCmd
- type DoctorCmd
- type DoctorProbeCmd
- type GetCmd
- type Globals
- type HiddenCmd
- type IngestCmd
- type InitCmd
- type JSONEnvelopeError
- type RefsCmd
- type ResetCmd
- type SearchCmd
- type StatsCmd
- type SuggestNotesCmd
- type TagsCmd
- type UsageError
- type VersionCmd
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ObsidianURI ¶ added in v2.13.0
ObsidianURI builds an obsidian://open URI for a vault-relative file path.
Types ¶
type BacklinksCmd ¶
type BacklinksCmd struct {
Note string `arg:"" help:"note slug, title, or file path (auto-resolved)" completion-predictor:"note-slug"`
}
func (*BacklinksCmd) Run ¶
func (c *BacklinksCmd) Run(globals *Globals) error
type BoostedCmd ¶
type BoostedCmd struct {
Query string `arg:"" help:"search query text"`
Limit int `group:"boosted" help:"maximum number of results" default:"10"`
Seed string `` /* 142-byte string literal not displayed */
Boost float64 `group:"boosted" help:"score multiplier for graph-connected results (e.g. 1.5 = 50% boost)" default:"1.5"`
WithPDF bool `group:"boosted" help:"include PDF results in search"`
ChunkDisplayFlags
}
func (*BoostedCmd) Run ¶
func (c *BoostedCmd) Run(globals *Globals) error
type CLI ¶
type CLI struct {
Globals
Ingest IngestCmd `cmd:"" help:"Ingest markdown files from a vault"`
Search SearchCmd `cmd:"" help:"Semantic search across indexed notes"`
Backlinks BacklinksCmd `cmd:"" help:"Find incoming links to a note"`
Connections ConnectionsCmd `cmd:"" help:"Find notes connected via wikilinks (graph traversal)"`
Hidden HiddenCmd `cmd:"" help:"Discover semantically related but unlinked notes"`
Tags TagsCmd `cmd:"" help:"Find notes sharing common tags"`
Boosted BoostedCmd `cmd:"" help:"Semantic search boosted by wikilink graph proximity"`
Stats StatsCmd `cmd:"" help:"Show collection statistics"`
Get GetCmd `cmd:"" help:"Retrieve the full text of an indexed note"`
Refs RefsCmd `cmd:"" help:"List a note's attachments and external links"`
Reset ResetCmd `cmd:"" help:"Delete all indexed data and reset the database"`
Doctor DoctorCmd `cmd:"" help:"Run diagnostics to check system dependencies and configurations"`
DoctorProbe DoctorProbeCmd `cmd:"" hidden:"" help:"internal: verify the database can be opened (used by doctor)"`
SuggestNotes SuggestNotesCmd `cmd:"" hidden:"" help:"internal: list indexed note slugs, one per line (used by shell completion)"`
Init InitCmd `cmd:"" help:"Initialize NoteBrain configuration interactively"`
Version VersionCmd `cmd:"" help:"Show version information"`
Completion kongcompletion.Completion `cmd:"" help:"Output shell code for initializing tab completions"`
}
CLI is the top-level Kong command tree.
type ChunkDisplayFlags ¶ added in v2.7.0
type ChunkDisplayFlags struct {
IncludeText bool `group:"display" help:"include the matched markdown text in each result"`
ContextWindow int `group:"display" name:"context-window" help:"fetch ±N surrounding chunks around each match (0=off)" default:"0"`
MinScore float64 `group:"display" help:"minimum similarity score to include in results (0.0–1.0)" default:"0"`
GroupByNote bool `` /* 180-byte string literal not displayed */
}
ChunkDisplayFlags holds options for semantic search commands that return text chunks.
type ConnectionsCmd ¶
type ConnectionsCmd struct {
Note string `arg:"" help:"note slug, title, or file path (auto-resolved)" completion-predictor:"note-slug"`
Hops int `group:"connections" help:"graph traversal depth (keep 1-2 to avoid exponential blowup)" default:"2"`
}
func (*ConnectionsCmd) Run ¶
func (c *ConnectionsCmd) Run(globals *Globals) error
type DoctorProbeCmd ¶ added in v2.11.0
type DoctorProbeCmd struct{}
DoctorProbeCmd is an internal hidden command used by `notebrain doctor` to test whether the ChromaDB store can be opened. A corrupted native HNSW index aborts the process with SIGABRT; doctor interprets that as database corruption, so this must run in its own process.
func (*DoctorProbeCmd) Run ¶ added in v2.11.0
func (c *DoctorProbeCmd) Run(globals *Globals) error
Run opens the store and forces both HNSW indexes to load. Success is reported via exit code 0; any Go-level failure is returned as an error and a native abort kills the process (parent sees the signal).
type GetCmd ¶
type GetCmd struct {
Note string `arg:"" help:"note slug, title, or file path (auto-resolved)" completion-predictor:"note-slug"`
Meta bool `group:"get" help:"show only the note header (title, path, tags, chunk count) without any text" default:"false"`
Head int `group:"get" help:"show only the first N chunks of text (0 = full note)" default:"0"`
}
type Globals ¶
type Globals struct {
ChromaPath string `group:"global" help:"path to ChromaDB persistent storage directory" default:"~/.notebrain/chroma"`
VaultPath string `group:"global" name:"vault-path" help:"path to the Obsidian vault directory"`
VaultName string `group:"global" name:"vault-name" help:"vault display name for Obsidian URI links (defaults to basename of --vault-path)"`
Format string `group:"global" help:"output format: text, json, or tsv" enum:"text,json,tsv" default:"text"`
JSONPath string `group:"global" name:"jsonpath" help:"extract fields using JSONPath (e.g. '$.results[*].note_slug')"`
LogLevel string `` /* 150-byte string literal not displayed */
LogFile string `` /* 133-byte string literal not displayed */
LogMaxSizeMB int `group:"global" name:"log-max-size-mb" help:"max size of each log file in MiB before rotation (0 = default 10)" default:"10"`
LogMaxBackups int `group:"global" name:"log-max-backups" help:"number of rotated log file backups to keep (0 = default 5)" default:"5"`
SkipPhantom bool `group:"global" name:"skip-phantom" help:"exclude phantom (uncreated) notes from results" default:"true"`
ShowTags bool `group:"global" name:"show-tags" help:"include tag names (#tag) in output" default:"false"`
ShowFilePath bool `group:"global" name:"show-file-path" help:"include file_path in output (use --show-file-path=false to hide)" default:"true"`
Version kong.VersionFlag `group:"global" name:"version" help:"show version information"`
// Internal fields, not exposed as flags
Ctx context.Context `kong:"-"`
VersionString string `kong:"-"`
DefaultConfig []byte `kong:"-"`
Config kong.ConfigFlag `group:"global" placeholder:"path" help:"path to config file (default: ~/.notebrain/config/config.toml)" type:"path"`
}
Globals holds shared configuration available to all subcommands.
type HiddenCmd ¶
type HiddenCmd struct {
Note string `arg:"" help:"note slug, title, or file path (auto-resolved)" completion-predictor:"note-slug"`
Limit int `group:"hidden" help:"maximum number of hidden connections to return" default:"10"`
Deep bool `group:"hidden" help:"analyze each chunk individually for granular section-level matches"`
CandidateChunks int `group:"hidden" name:"candidate-chunks" help:"chunks to evaluate per candidate note in --deep mode" default:"3"`
IncludeLinked bool `group:"hidden" name:"include-linked" help:"include notes even if they are already linked directly or indirectly"`
ChunkDisplayFlags
}
type IngestCmd ¶
type IngestCmd struct {
Glob string `arg:"" optional:"" help:"glob pattern to filter files (default: all .md files)"`
Workers int `group:"ingest" help:"number of concurrent ingestion workers" default:"4"`
MinChunkWords int `group:"ingest" name:"min-chunk-words" help:"skip chunks with fewer words" default:"10"`
ChunkSize int `group:"ingest" name:"chunk-size" help:"max runes per chunk" default:"800"`
ChunkOverlap int `group:"ingest" name:"chunk-overlap" help:"overlap runes between sub-chunks" default:"100"`
RespectExclude bool `group:"ingest" help:"respect Obsidian userIgnoreFilters and attachmentFolderPath settings during ingest" default:"false"`
WithPDF bool `group:"ingest" name:"with-pdf" help:"include PDF attachments in indexing" default:"false"`
LLMModel string `` /* 198-byte string literal not displayed */
LLMContextWindow int `` /* 151-byte string literal not displayed */
}
type JSONEnvelopeError ¶ added in v2.13.0
type JSONEnvelopeError struct{ Err error }
JSONEnvelopeError marks an error that has already been emitted as a machine-readable {"error": "..."} object on stdout. runMain skips the human-readable stderr line for these, so --format json scripts get exactly one error representation.
func (*JSONEnvelopeError) Error ¶ added in v2.13.0
func (e *JSONEnvelopeError) Error() string
func (*JSONEnvelopeError) Unwrap ¶ added in v2.13.0
func (e *JSONEnvelopeError) Unwrap() error
type RefsCmd ¶ added in v2.13.0
type RefsCmd struct {
Note string `arg:"" help:"note slug, title, or file path (auto-resolved)" completion-predictor:"note-slug"`
OnlyImages bool `` /* 131-byte string literal not displayed */
OnlyPDF bool `` /* 126-byte string literal not displayed */
OnlyOther bool `` /* 168-byte string literal not displayed */
OnlyExternal bool `` /* 151-byte string literal not displayed */
IncludeMissing bool `group:"refs" name:"include-missing" help:"include references whose file is missing from the vault" default:"false"`
}
type ResetCmd ¶
type ResetCmd struct {
Yes bool `group:"reset" short:"y" help:"skip confirmation prompt (use in scripts and automation)"`
}
type SearchCmd ¶
type SearchCmd struct {
Queries []string `group:"search" arg:"" optional:"" name:"query" help:"search query (multiple args for multi-hit boosting)"`
Limit int `group:"search" help:"maximum number of results" default:"10"`
TopKPerNote int `group:"search" name:"top-k" help:"maximum chunks to retain per note (prevents one note dominating)" default:"3"`
Section string `group:"search" help:"filter results to chunks under this heading path (e.g. 'Architecture > Components')"`
Tag string `group:"search" help:"filter results to notes with this tag"`
HasTasks bool `group:"search" help:"only return chunks containing task lists (checkboxes)"`
HasCode bool `group:"search" help:"only return chunks containing fenced code blocks"`
WithPDF bool `group:"search" help:"include PDF results in search"`
ExcludeNotes []string `` /* 156-byte string literal not displayed */
ChunkDisplayFlags
}
type SuggestNotesCmd ¶ added in v2.11.0
type SuggestNotesCmd struct{}
SuggestNotesCmd lists all indexed note slugs, one per line. It is hidden from help and shell completion; the note-slug completion predictor shells out to it to fetch dynamic slug candidates.
func (*SuggestNotesCmd) Run ¶ added in v2.11.0
func (c *SuggestNotesCmd) Run(globals *Globals) error
type TagsCmd ¶
type TagsCmd struct {
Query string `` /* 156-byte string literal not displayed */
List bool `group:"tags" help:"List all indexed tags with note counts instead of searching (query is ignored)." default:"false"`
ForNote bool `group:"tags" name:"for-note" help:"Alias for --shared."`
Children bool `group:"tags" help:"Include child tags in the hierarchy (e.g. 'kubernetes' also matches 'kubernetes/cka')." default:"false"`
Limit int `group:"tags" help:"maximum number of results (0 = no limit for --list; searches default to 50)" default:"0"`
ChunkDisplayFlags
}
type UsageError ¶ added in v2.12.0
type UsageError struct{ Err error }
UsageError marks an error as a command-line usage error. runMain maps it to exit code 2, so automation can distinguish bad invocations (2) from operational failures (1).
func (*UsageError) Error ¶ added in v2.12.0
func (e *UsageError) Error() string
func (*UsageError) Unwrap ¶ added in v2.12.0
func (e *UsageError) Unwrap() error
type VersionCmd ¶
type VersionCmd struct {
// Writer allows overriding destination for testing (defaults to os.Stdout)
Writer io.Writer `kong:"-"`
}
VersionCmd prints version information.
func (*VersionCmd) Run ¶
func (c *VersionCmd) Run(globals *Globals) error
Run executes the version command.