FAQ
Frequently asked questions for installing, using, troubleshooting, and maintaining Indexly across supported platforms.
Categories:
Who This Page Is For
- New users validating installation and first-run behavior
- Daily users checking file locations, command choice, and supported formats
- Developers and operators troubleshooting persistence, schema, logging, or performance issues
How To Use This FAQ
Start here when you need a short answer quickly, then follow the related documentation links for deeper steps and examples.
If you are working with structured datasets, AutoDoctor artifacts, or SQLite databases, the analysis guides linked in each answer will take you deeper than this page should.
Support
Indexly Frequently Asked Questions
Quick answers for installation, local storage paths, file support, troubleshooting, and day-to-day CLI workflows.
Installation
Start here when you are setting up Indexly or enabling optional feature groups.
On Windows, the recommended product install path is
py -m pip install indexly. On macOS and Linux, Homebrew is the most convenient product install path, while python -m pip install indexly remains a cross-platform fallback. If you are preparing a contributor workstation, use the maintained Windows or Linux environment setup guide instead of only installing the CLI. Always verify with indexly --version and indexly --help after installation.
Related documentation
That usually means the current terminal session does not yet see the Python or Homebrew scripts directory. Open a fresh terminal first. If it still fails, verify that the package is installed, then review the platform-specific setup notes for Windows Terminal or Linux shell initialization.
Related documentation
Use the maintained
dotfiles-linux workflow from the dotfiles repository. The default Linux path is to copy the bundle to ~/dotfiles-linux, run ./bootstrap.sh, reload Bash, then use show-help and idxdocs verify to confirm the shell and Project-Indexly docs toolchain. On development machines, use update-lp after changing the repo bundle so the live ~/dotfiles-linux profile is refreshed; use update-profile only when you need to relink an already-synced local bundle.
Related documentation
Indexly keeps the base install lightweight, so some commands depend on optional extras. Install only the pack you need, such as
indexly[analysis], indexly[documents], indexly[visualization], or indexly[pdf_export]. This avoids pulling in heavy dependencies when you only need the core search workflow.
Related documentation
Usage Basics
These answers help you choose the right command and get productive quickly.
A practical first session is: check
indexly --help, index a folder, run a simple search, then try one structured-data command. That sequence confirms the CLI is available, indexing works, and your environment is ready for the workflows you care about.
Related documentation
Use
analyze-file when you want Indexly to detect the best route automatically, especially for mixed structured formats or operational artifacts such as AutoDoctor JSON and SQLite outputs. Use analyze-json, analyze-csv, or analyze-db when you already know the file type and want a more direct route.
Related documentation
Yes. Indexly is designed for local-first workflows. Search, indexing, and most analysis operations run against local files and local SQLite state, so you can work without sending content to an external service.
Related documentation
File Locations
These paths matter when you need to inspect state files, logs, or runtime storage directly.
Indexly stores its main SQLite database as
fts_index.db inside its user-writable runtime base directory. By default that base is %APPDATA%\\indexly on Windows, ~/Library/Application Support/indexly on macOS, and $XDG_DATA_HOME/indexly or ~/.local/share/indexly on Linux. If INDEXLY_HOME is set, that override becomes the base directory instead.
Related documentation
The primary search cache file is
search_cache.json in the same runtime base directory as the database. Some command-specific caches can also live closer to the working data, such as organizer or lister cache files created under a local .indexly folder when those workflows are used.
Related documentation
Core runtime logs are written under the runtime base directory in the
log/ folder. Organizer workflows can also write JSON logs to a custom --log-dir, which is useful when you want audit trails stored beside the files you are organizing.
Related documentation
Supported File Types
Use these answers to understand both search-oriented and analysis-oriented format support.
Indexly supports a broad set of local file formats, including text files, Office documents, PDFs, spreadsheets, markdown, logs, and several image workflows when the matching extras are installed. Exact extraction depth depends on the file type and the optional dependency groups you have enabled.
Related documentation
Yes. Indexly’s analysis stack supports common tabular and semi-structured formats such as CSV, JSON, NDJSON, Excel, Parquet, and SQLite. The generic
analyze-file command is often the safest starting point when you are not fully sure which route will preserve the most meaning.
Related documentation
Yes. NDJSON is the preferred structured logging format in current Indexly workflows and can be summarized through the analysis pipeline. This makes it a good fit for machine-generated event streams and operational logs that would be awkward to manage as plain text.
Related documentation
Troubleshooting
These are the fastest checks when behavior looks wrong or a command seems to stop short.
The most common causes are: indexing has not been run yet, the database is stale, the query is too narrow, or the file type was never extracted the way you expected. Re-index the relevant folder, retry with a simpler query, and run
indexly doctor if the environment still feels inconsistent.
Related documentation
First confirm the file encoding and whether the input is really standard JSON, NDJSON, or an application-specific report format. Files with a UTF-8 BOM, mixed records, or operational report structures often work better through
analyze-file or a dedicated route such as analyze-autodoctor, because those paths can choose a better interpretation strategy than a strict JSON-first flow.
Related documentation
Use
indexly doctor to inspect the environment and database state. If the tool reports missing columns or schema drift, follow up with indexly doctor --fix-db after reviewing the message. That route is designed to surface problems before you try more invasive troubleshooting.
Related documentation
clear-search removes rows from the local FTS5 search index only; it does not delete source files. To recover search results, re-run indexly index on the folder that contains the files. If you used --all, re-index every folder you expect to search. If cache invalidation failed, remove search_cache.json from the Indexly runtime directory so future searches rebuild fresh cache entries.
Related documentation
Performance Tips
Use these suggestions when data volume grows and you want Indexly to stay responsive.
Scope the work intentionally. Index only the folders you actually need, apply ignore rules for generated or temporary files, and use file-type filters when your workflow targets a known subset. On the analysis side, prefer routes that stream or summarize instead of flattening everything into one big in-memory table.
Related documentation
Start with the command that can make the best routing choice. For example,
analyze-file is often better than forcing a JSON-only route when the input may actually be NDJSON, a report document, or an application-specific export. That keeps the analysis path closer to the file’s real structure and avoids unnecessary reshaping work.
Related documentation