Configuration and Runtime Files

Indexly stores search runtime state outside the source tree by default. The main search files are resolved from INDEXLY_HOME when set, otherwise from the platform-specific user data directory.

Runtime Files

Default runtime directories:

Set a custom location when you want a portable or isolated environment:

set INDEXLY_HOME=D:\indexly-state
indexly stats

On PowerShell, use $env:INDEXLY_HOME = "D:\indexly-state" for the current session. Use only a trusted, user-owned location. If INDEXLY_HOME is a symbolic link, Indexly intentionally follows it as the configured runtime root.

Analysis Database

Analysis commands persist cleaned or summarized data in ~/.indexly/indexly.db unless persistence is disabled for the command. This database contains the cleaned_data table used by CSV, JSON, YAML, AutoDoctor-aware, and related analysis workflows.

When YAML or YML analysis runs through indexly analyze-file, metadata also carries a JSON-safe YAML table summary (yaml_table_output). Nested YAML analyses additionally write an artifact JSON under ~/.indexly/analysis/, and the persisted record stores that location in metadata_json.analysis_artifact_path with schema tag indexly.yaml.analysis.v1.

Keep this separate from fts_index.db when troubleshooting:

Use --no-persist on analysis commands when you want an in-memory or export-only run. For the full database boundary, see Database Design; for health checks, see Indexly Doctor.

Indexing Log Artifacts

Indexing writes structured NDJSON log artifacts under the configured runtime log/ directory. Current logs are partitioned by year and month, then rotated by date and size:

<runtime-dir>/log/YYYY/MM/YYYY-MM-DD_index_events.ndjson
<runtime-dir>/log/YYYY/MM/YYYY-MM-DD_index_events_1.ndjson

The log configuration is defined in code with conservative defaults: daily partitions, 5 MB rotation, and 30 days of retention. Treat these logs as analysis-ready artifacts, not just diagnostic text files:

indexly analyze-file "D:\indexly-state\log\2026\05\2026-05-21_index_events.ndjson"

For field structure, legacy .log conversion, and the full log pipeline, see Indexly Logging System.

Search Profiles

Profiles save repeatable search parameters:

indexly search "project plan" --filetype .pdf .docx --save-profile project_docs
indexly search "project plan" --profile project_docs

Profiles are useful when you repeatedly combine a term with the same filters, such as file type, path, tag, or date range.

Search Cache

Indexly can reuse cached results when the indexed files have not changed.

indexly search "policy"
indexly search "policy" --no-cache

Use --no-cache when validating fresh behavior without reading from or writing to search_cache.json. Full-text search cache keys include the current search index generation, so normal searches refresh automatically after an indexing run changes or prunes indexed rows.

Performance Record

For a non-WAL search database, indexly perf --show opens SQLite read-only, collects bounded evidence, and atomically refreshes the files under perf/. indexly perf --read validates the current record and then the previous copy, without opening SQLite or creating or changing files.

The record contains numeric measurements, calculation context, timestamps, a non-reversible local database identity, a checksum, and up to 30 numeric-only action outcomes. An outcome stores its action, timestamp, applied or no_op result, duration, and bounded before/after/delta values. It does not contain paths, source roots, filenames, indexed content, metadata JSON, query terms, usernames, hostnames, raw logs, or network telemetry.

The numeric measurements include SQLite’s observed database change counter from header offset 24. This counter contains no path or content and lets a guarded apply reject a database file changed since --show. Completed action outcomes survive same-database baseline resets, including a transition to a new size bucket; they reset when database identity changes.

If the primary record is invalid and the previous copy validates, --read reports recovery from the previous file without promoting or rewriting it. Applied performance maintenance does not accept that recovered copy: it requires a validated current primary record and an explicit, existing, non-symlink --backup-dir that differs from the live database directory. The verified generic SQLite backup is retained in that separate, user-selected directory rather than in the performance record. Its filename is accepted as complete only after backup-directory synchronization succeeds.

If backup creation fails and candidate cleanup is incomplete, the reported filename is unverified. Resolve it only inside the configured --backup-dir, inspect and remove it, and do not treat it as a recovery snapshot.

--show refuses WAL mode before opening SQLite; --read and plan-only --opti remain record-only. Indexly never checkpoints WAL or changes journal mode through the performance command. See Performance Diagnostics and Optimization before removing either record or applying database maintenance.

Tags

Tags are stored separately from extracted file content and can be used as search filters.

indexly tag add --files "notes.txt" --tags important
indexly tag add --files "./docs" --tags archive --recursive
indexly tag list --file "notes.txt"
indexly tag remove --files "notes.txt" --tags important
indexly search "keyword" --filter-tag important

For the full tagging workflow, see Tagging.

OCR and Document Extraction

PDF OCR behavior is controlled during indexing:

indexly index ./docs --filetype .pdf
indexly index ./docs --ocr
indexly index ./docs --no-ocr

--ocr forces OCR for PDFs. --no-ocr disables PDF OCR. Without either flag, Indexly uses its default PDF extraction policy.

Install document extras before indexing PDFs, Word documents, Outlook messages, or other rich document formats:

# Homebrew install
indexly extras install documents
indexly extras status

# pip or virtual-environment install
python -m pip install "indexly[documents]"

The managed command also works for pip installations. Homebrew users must use it: their extras live in a user-owned overlay scoped by Indexly version, Python ABI, and platform architecture outside the Cellar. Do not replace it with generic pip, pip --user, sudo pip, or a PYTHONPATH workaround.

The documents group supplies ordinary PDF extraction dependencies and the Python OCR integration. OCR itself also requires Tesseract on PATH; install it separately with brew install tesseract on Homebrew systems.

Maintenance Commands

Use these commands when behavior differs between machines or after upgrades:

indexly stats
indexly doctor
indexly doctor --analysis-db
indexly perf --show
indexly perf --read
indexly update-db
indexly migrate check

Related Pages

• Search Files with Indexly
• Install Indexly
• Indexly Developer Guide
• Index Files and Folders
• Indexly Logging System
• Indexly Doctor
• Performance Diagnostics and Optimization
• Database Design
• Ignore Rules and Index Hygiene
• DB Migration Utility