Indexly FAQ
Frequently asked questions for installing, using, automating file renames, 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
Rename Automation
Choose and operate Indexly's on-demand and watch-folder renaming commands safely.
Use
rename-file for an on-demand file or folder that already exists, especially when you need optional database path sync or organizer handoff. Use rename-watch when files arrive over time and should pass through a repeatable JSON-defined pipeline with settling, filters, counters, quarantine, operator retry, and crash recovery.
Related documentation
Create the starter configuration, validate it, and then run
indexly rename-watch --config "./rename-watch.json" --once --dry-run. The preview freezes the initial file set, models counters and collisions, and does not move files or consume counter state.
Related documentation
Rename Watch never overwrites an existing destination. Depending on the job configuration and failure type, it applies bounded retries, leaves the unchanged source in place, or moves it to a unique quarantine incident directory.
--status reports durable active failures and their IDs; --retry-failures performs a guarded operator retry under the same watch-root lock.
Related documentation
No.
rename-watch is a standalone filesystem rename pipeline. Use indexly watch when you want live indexing, or use rename-file --update-db for an on-demand rename that should also synchronize existing Indexly database paths.
Related documentation
Use the supported WinSW workflow with a dedicated Indexly environment, a separate
INDEXLY_HOME, and NT AUTHORITY\LocalService for local folders. After installing the wrapper, always run sc.exe qc IndexlyRenameWatch before the first start and after an upgrade. It must report NT AUTHORITY\LocalService, not LocalSystem; the service guide includes the safe correction command and health checks.
Related documentation
First inspect the WinSW wrapper and child error logs. An access-denied message for
python.exe means the service account can reach the wrapper but not the complete Python runtime. Stop the service, grant its identity read and execute access to both the versioned environment and its base Python installation, then repeat --check-config and --once --dry-run before starting it again. A dedicated runtime outside a personal user profile is the safer long-term layout.
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.
Run
indexly perf --show. For a non-WAL database it opens SQLite read-only, runs bounded local probes, and refreshes only the checksummed performance record. It refuses WAL mode before opening SQLite so a read-only connection cannot create or update shared-memory state; it never checkpoints WAL or changes journal mode. Use indexly perf --read to read the latest validated record without opening SQLite or writing files. Values are labelled Observed, Indexly-derived, or Theoretical and compare this installation with its own baseline; they are not a hardware benchmark or a direct comparison with another machine.
Related documentation
Only action-specific evidence can qualify
planner-optimize or fts-merge; database size, page count, and a generic performance grade are not enough. Both actions require measured canonical Indexly FTS5 readiness 1 (match). A legacy record missing the readiness metric returns collect_evidence; run a fresh perf --show. Unmeasured or budget-unavailable readiness returns unavailable without inferring schema damage. Measured readiness 0 for an actually inspected noncanonical, missing, drifted, external-content, malformed, unsupported, or uninspectable definition returns repair_required and routes to Doctor. Apply also requires a current report, exact database bindings, WAL refusal, free space, a writer reservation, a verified synchronized backup, and confirmation. The result omits the private identity salt and indexed paths or content.
Related documentation
Exit
2 means no database mutation committed: preflight or backup failed, the action transaction rolled back, or follow-up failed after a no_op. If backup cleanup is incomplete, indexly.performance-error/v1 reports mutation_applied: false, backup_verified: false, cleanup_incomplete: true, and only the unverified candidate filename. Inspect and remove that named candidate in the configured backup directory before retrying; do not use it for recovery. A rollback after verified backup creation instead uses indexly.performance-action/v1. Exit 3 means a mutation was applied but audit persistence or the post-action report failed; treat it as partial success and do not retry blindly.
Related documentation
No. Database size, document count, vocabulary size, and theoretical capacity values are not corruption findings.
Elevated means repeated baseline-relative degradation was observed, while ungraded states such as collecting_baseline or inconclusive mean there is not enough comparable evidence. Review indexly perf --show; use the separate read-only indexly doctor --full-integrity check only when integrity is in question.
Related documentation
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