Indexly Usage Guide

Practical Indexly usage guide for Windows, macOS, and Linux. Covers indexing, search, regex, tagging, analysis, organizing, backup/restore, and common troubleshooting.
Categories:
Tags:

What This Guide Covers

This guide is for everyday usage of Indexly on local files and folders. You will learn the most common workflows:

  • Index and re-index files quickly
  • Search with full-text and regex
  • Safely remove stale search index entries
  • Rename, tag, and organize content
  • Analyze CSV and other structured files
  • Compare, back up, and restore safely

If you have not installed Indexly yet, start with Install Indexly.

Quick Start 

indexly --help
indexly index /path/to/folder
indexly search "invoice"
indexly clear-search --path /path/to/old-folder --dry-run
indexly rename-file /path/to/incoming --pattern "{date}-{title}" --dry-run
indexly regex "[A-Z]{3}-\\d{4}"

Use indexly show-help for a compact overview of all commands.

Install And Optional Packs

For full platform-specific setup, use Install Indexly.

Indexly has a lightweight core install. Optional capability packs are installed only when needed:

python -m pip install "indexly[documents]"
python -m pip install "indexly[analysis]"
python -m pip install "indexly[visualization]"
python -m pip install "indexly[pdf_export]"
python -m pip install "indexly[backup]"

Install all optional packs at once:

python -m pip install "indexly[documents,analysis,visualization,pdf_export,backup]"

1) Index Files

Index a folder recursively:

indexly index /path/to/folder

Index only a specific extension:

indexly index /path/to/folder --filetype .pdf

Use a custom ignore file:

indexly index /path/to/folder --ignore /path/to/.indexlyignore

Fast re-indexing for stable folders:

indexly index /path/to/folder -r
indexly index /path/to/folder --only-changes

The -r mode skips files that are already indexed and whose current filesystem stat fingerprint matches the index. New files, edited files, legacy rows without fingerprints, and files that cannot be checked quickly are processed safely. Deleted or newly ignored files are still pruned from the search index during the run.

This is only the beginning of Indexly’s incremental indexing workflow. You can also scope work from previous index logs, combine that scope with fast change detection, and preview the complete plan without modifying the index. See Incremental Indexing: Fast, Safe Refreshes for the full guide.

OCR control for PDFs:

indexly index /path/to/folder --ocr
indexly index /path/to/folder --no-ocr

See Indexing and Ignore Rules & Index Hygiene.

2) Search And Regex

Full-text search:

indexly search "quarterly report"
indexly search "invoice AND 2026"
indexly search "\"quarterly report\"" --context 80

Use uppercase logical operators only when you mean FTS logic:

indexly search "docker OR kubernetes"
indexly search "cache NOT redis"
indexly search "authentication NEAR failure" --near-distance 8

Lowercase English words such as and, or, not, and near are treated as normal text. For example, indexly search "search and replace" searches for that literal phrase.

Filter search results:

indexly search "report" --filetype .pdf .md --filter-tag finance
indexly search "contract" --date-from 2026-01-01 --date-to 2026-03-31
indexly search "meeting" --path-contains "/projects/client-a"

Sort returned results:

indexly search "invoice" --sort-by relevance
indexly search "invoice" --sort-by newest
indexly search "invoice" --sort-by oldest
indexly search "invoice" --sort-by path

relevance is the default. Date sorting uses the indexed file modified timestamp.

Fuzzy search:

indexly search "projetc plan" --fuzzy --fuzzy-threshold 85

Regex search:

indexly regex "\\bINV-\\d{6}\\b"

Regex search uses Python regular expressions over indexed content. It does not use the FTS logical operators from indexly search.

Save and reuse profiles:

indexly search "budget" --filetype .csv --save-profile budget_csv
indexly search "budget" --profile budget_csv

Export results:

indexly search "invoice" --export-format md --output invoice_results.md
indexly regex "\\bTODO\\b" --export-format json --output todo_hits.json

See Configuration and Tagging.

3) Clear Search Results Safely

Use clear-search when search results should be removed from fts_index.db without deleting source files.

Preview by path:

indexly clear-search --path "/path/to/old-folder" --dry-run

Delete after reviewing the plan:

indexly clear-search --path "/path/to/old-folder"

Delete all files matching any listed tag:

indexly clear-search --tag archive stale --dry-run
indexly clear-search --tag archive stale

Clear the full search index before a rebuild:

indexly clear-search --all --dry-run
indexly clear-search --all
indexly index /path/to/folder

clear-search shows a pre-deletion report, asks for confirmation unless --yes is used, invalidates affected search cache entries, and logs the operation with an operation ID.

See Clear Search Results Safely.

4) Rename, Tag, And Organize

Use rename-file before organizing or analyzing files when names are inconsistent, duplicated, or missing useful context:

indexly rename-file /path/to/incoming --pattern "{date}-{title}" --dry-run
indexly rename-file /path/to/incoming --pattern "{date}-{title}" --recursive

For business folders, rename-file can pass its planned names directly into profile-based organization:

indexly rename-file /path/to/incoming \
  --business-naming \
  --pattern "{prefix}-{date}-{title}" \
  --organize \
  --profile business \
  --classify \
  --dry-run

Tag files and folders:

indexly tag add --files "/path/to/file.txt" --tags urgent finance
indexly tag add --files "/path/to/folder" --tags archive --recursive
indexly tag list --file "/path/to/file.txt"
indexly tag remove --files "/path/to/file.txt" --tags urgent

Organize by date/name/extension:

indexly organize /path/to/downloads --sort-by date
indexly organize /path/to/downloads --sort-by extension --backup /path/to/backup --log-dir /path/to/logs

Query organizer logs with lister:

indexly lister /path/to/logs --ext .pdf
indexly lister /path/to/logs --duplicates

See Rename File, Organizer, Organizer Profiler, and Lister.

5) Analyze Data

CSV analysis:

indexly rename-file ./exports --pattern "{date}-{title}" --dry-run
indexly analyze-csv sales.csv --show-summary
indexly analyze-csv sales.csv --auto-clean --show-summary
indexly analyze-csv sales.csv --show-chart ascii --chart-type bar

Analyze other formats with one command:

indexly analyze-file data.json --show-summary
indexly analyze-file config.yaml --show-summary
indexly analyze-json events.ndjson --show-summary
indexly analyze-json events.json --chunk-size 10000 --show-summary
indexly analyze-file dataset.xlsx --sheet-name Sheet1 --show-summary
indexly analyze-file metrics.parquet --show-summary

Use analyze-json for large JSON or NDJSON files when you need --chunk-size. Use analyze-file when you want one generic dispatcher for mixed structured files.

For YAML/YML through analyze-file, persistence is on by default and writes analysis data to ~/.indexly/indexly.db (with YAML-specific metadata/artifact references). Add --no-persist for a no-write run.

Analyze SQLite directly when you want schema-aware inspection:

indexly analyze-db chinook.db --show-summary
indexly analyze-db chinook.db --all-tables --export md

Analyze AutoDoctor artifacts with the dedicated operational route:

indexly analyze-autodoctor .\AutoDoctor_Report.json --show-summary
indexly analyze-autodoctor .\Telemetry_20260416-081258-BTNB05.json --summary-only
indexly analyze-autodoctor .\autodoctor.db --show-summary

If you prefer one generic command, analyze-file can also auto-detect AutoDoctor JSON and AutoDoctor SQLite databases:

indexly analyze-file .\AutoDoctor_Report.json --show-summary
indexly analyze-file .\autodoctor.db --show-summary

Run statistical inference on indexed CSV datasets:

indexly infer-csv sales_q1.csv sales_q2.csv --merge-on customer_id --test ttest --x group --y revenue

Use Rename File when exported datasets need predictable names before analysis. See Data Analysis Overview, Analyze JSON And NDJSON Files, and Time-Series Visualization.

For AutoDoctor-specific guidance, see Analyze AutoDoctor Artifacts.

6) Compare, Back Up, And Restore

Compare files or folders:

indexly compare /path/a /path/b
indexly compare /path/a /path/b --extensions .py,.md --context 5
indexly compare /path/a /path/b --ignore-file /path/to/.indexlyignore
indexly compare /path/a /path/b --no-project-ignore
indexly compare /path/a /path/b --json

Back up data:

indexly backup /path/to/folder
indexly backup /path/to/folder --incremental
indexly backup /path/to/folder --encrypt "your-password"

Restore from backup:

indexly restore backup_name --target /path/to/restore
indexly restore backup_name --target /path/to/restore --decrypt "your-password"

See Backup & Restore and File/Folder Comparison.

7) Health, Maintenance, And Monitoring

Environment and database health checks:

indexly doctor
indexly doctor --json
indexly doctor --full-integrity
indexly stats
indexly clear-search --tag stale-index --dry-run
indexly update-db
indexly migrate check

indexly doctor --full-integrity runs the slower read-only SQLite integrity check when the normal health check reports skipped integrity on a large database.

indexly stats gives a quick database summary: indexed files, tagged files, untagged files, tag coverage, database size, unique tags, total tag assignments, and top tags.

Semantic observers:

indexly observe --help
indexly observe run /path/to/folder --recursive
indexly observe run /path/to/file --log-dir /path/to/logs
indexly observe audit
indexly observe audit --id 20260201-patient-00001

CSV observer history is normally created by CSV analysis after cleaned data is persisted:

indexly analyze-csv sales.csv --show-summary

Live indexing:

indexly watch /path/to/folder

See Indexly Doctor, DB Migration Utility, and Observers.

Friendly Missing-Dependency Messages

When a feature needs an optional package group, Indexly prints a direct install hint.

Examples:

  • Analysis features: Feature requires: pip install indexly[analysis]
  • Document parsing features: Feature requires: pip install indexly[documents]
  • Visualization features: Feature requires: pip install indexly[visualization]
  • PDF export features: Feature requires: pip install indexly[pdf_export]
  • Encrypted backup/restore features: Feature requires: pip install indexly[backup]

This lets core commands like indexly --help and indexly --version remain usable even when optional packs are not installed.

Practical Tips

  • Quote paths that contain spaces.
  • Start with indexly <command> --help before trying advanced flags.
  • Use indexly doctor when behavior seems inconsistent between environments.
  • Keep your index and backup workflows separate for easier recovery.