rekordbox-edit 0.6.0.dev14__tar.gz → 0.6.0.dev40__tar.gz

rekordbox_edit-0.6.0.dev40/.github/actions/e2e/action.yml

@@ -0,0 +1,27 @@
+name: "Run E2E Tests"
+description: "Install platform ffmpeg, set up Python, run the e2e journey suite"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Setup UV
+      uses: ./.github/actions/install
+
+    - name: Install ffmpeg (macOS)
+      if: runner.os == 'macOS'
+      shell: bash
+      run: brew install ffmpeg
+
+    - name: Install ffmpeg (Windows)
+      if: runner.os == 'Windows'
+      shell: pwsh
+      run: choco install ffmpeg -y
+
+    - name: Run e2e suite
+      shell: bash
+      env:
+        RBE_RUN_E2E: "1"
+        TZ: "UTC"
+      run: |
+        : "${RBE_DB_VERSION:?RBE_DB_VERSION must be set by the caller (matrix dimension).}"
+        uv run pytest tests/e2e --snapshot-warn-unused

{rekordbox_edit-0.6.0.dev14 → rekordbox_edit-0.6.0.dev40}/.github/workflows/ci.yml

@@ -66,16 +66,41 @@ jobs:
 
       - name: Run unit tests
         uses: ./.github/actions/test
+
+  e2e-tests:
+    name: 🎚️ E2E
+    needs: code-change
+    if: ${{ needs.code-change.outputs.should_skip != 'true' && !fromJSON(needs.code-change.outputs.paths_result || '{}').code.should_skip }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ["macos-latest", "windows-latest"]
+        python-version: ["3.11", "3.14"]
+        rb-version: ["6.8.6"]
+    runs-on: ${{ matrix.os }}
+    env:
+      OS: ${{ matrix.os }}
+      PYTHON: ${{ matrix.python-version }}
+      RBE_DB_VERSION: ${{ matrix.rb-version }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Run e2e tests
+        uses: ./.github/actions/e2e
+
   all-green:
     name: ✅ All Green
     if: always()
     needs:
       - lint
       - unit-tests
+      - e2e-tests
     runs-on: Ubuntu-latest
 
     steps:
       - uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe # release/v1
         with:
-          allowed-skips: unit-tests, lint
+          allowed-skips: unit-tests, lint, e2e-tests
           jobs: ${{ toJSON(needs) }}

{rekordbox_edit-0.6.0.dev14 → rekordbox_edit-0.6.0.dev40}/.gitignore

@@ -49,3 +49,6 @@ Thumbs.db
 
 .claude
 docs/superpowers
+
+# MkDocs build output
+site/

{rekordbox_edit-0.6.0.dev14 → rekordbox_edit-0.6.0.dev40}/.pre-commit-config.yaml

@@ -7,7 +7,9 @@ repos:
     rev: v6.0.0
     hooks:
     -   id: trailing-whitespace
+        exclude: '^tests/e2e/__snapshots__/'
     -   id: end-of-file-fixer
+        exclude: '^tests/e2e/__snapshots__/'
     -   id: check-yaml
     -   id: check-added-large-files
         args: [--maxkb=1024]

rekordbox_edit-0.6.0.dev40/.readthedocs.yaml

@@ -0,0 +1,22 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  jobs:
+    create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    install:
+      - uv sync --frozen --group docs
+    build:
+      html:
+        - uv run --group docs mkdocs build --strict --site-dir $READTHEDOCS_OUTPUT/html
+
+mkdocs:
+  configuration: mkdocs.yml

{rekordbox_edit-0.6.0.dev14 → rekordbox_edit-0.6.0.dev40}/CHANGELOG.md

@@ -1,6 +1,74 @@
-## v0.6.0.dev14 (2026-06-09)
-
-
+## v0.6.0.dev40 (2026-06-11)
+
+
+- docs: add api reference page
+- docs: add convert command page
+- docs: add edit command page
+- docs: add search command page
+- docs: add filtering page
+- docs: configure read the docs build
+- docs: scaffold mkdocs material site
+- docs: trim README to overview and quick start
+- chore: add docs dependency group
+- feat: add --last filter to return only the last N results
+- feat: add --first filter to return only the first N results
+- test(e2e): update windows snapshot with unicode representation
+- test(e2e): force utf-8 encoding of stdout
+- test(e2e): align TZ to UTC
+- test(ci): parameterize the db version as an env var
+- ci(e2e): add windows-latest to the e2e matrix
+- test: add windows snapshots for e2e journey
+- test(e2e): parameterize snapshots by fixture DB
+- Routes the two contract snapshots through SNAPSHOT_KEY (macos/windows)
+so the Windows fixture can land its own snapshot alongside the macOS
+one. Docker reuses the macOS DB and therefore the macos key.
+Renames the existing snapshot entries to the [macos] variant.
+- test: adds 6.8.6 db fixture for windows
+- test(e2e): pretty-print JSON snapshots via JSONSnapshotExtension
+- The single-line raw CLI output made snapshot diffs unreadable when a contract
+field changed. Use syrupy's JSONSnapshotExtension for the search-json test:
+the parsed payload is dumped as indented JSON to its own .json file under
+__snapshots__/test_journey/, so post-update diffs land per-field.
+- The IDs snapshot stays on AmberExtension; it's already one short line.
+- ci(e2e): add macos-latest e2e job to the matrix and require it
+- Adds a new e2e-tests job to ci.yml matrix'd over macos-latest × Python
+{3.11, 3.14}, wiring it into the all-green aggregate so branch protection
+gates on it. Windows joins in a follow-up PR once a windows master.db
+fixture exists.
+- The composite action at .github/actions/e2e/ installs ffmpeg on the runner,
+sets RBE_RUN_E2E=1, and runs pytest against tests/e2e directly.
+- test(e2e): add docker leg and make targets
+- Local e2e validation runs through a Linux container; the conftest refuses to
+run on bare macOS/Windows. `make test-e2e-docker` builds the image (Python
+3.14 + ffmpeg + uv-synced project) and runs the journey suite;
+`make test-e2e-snapshot-update` regenerates snapshots inside the container so
+the host's working tree picks them up via the volume mount.
+- `make test-e2e` runs the suite directly with uv; useful inside the container
+itself or in CI runners where the platform check passes.
+- test(e2e): add journey suite, conftest, and macOS snapshots
+- A single ordered file walks search → edit → convert against the committed
+macOS master.6.8.6.db, exercising filter narrowing, dry-run safety, stdin-pipe
+edits, unicode metadata, and the convert row-swap. Snapshots lock the JSON
+and IDs print contracts for `search`.
+- The conftest gates the suite behind RBE_RUN_E2E=1 and refuses to run on
+macOS/Windows outside CI, pointing local users at the Docker leg. The
+canonical staging path is /private/tmp/rbedit-e2e/music — macOS resolves
+/tmp through that symlink, so the DB stores the canonical form.
+- Excludes tests/e2e/__snapshots__/ from the trailing-whitespace and
+end-of-file pre-commit hooks; syrupy-generated whitespace is meaningful.
+- test(e2e): register marker, exclude from default collection, add syrupy
+- Adds the `e2e` pytest marker, sets `norecursedirs` so default `make test` runs
+do not collect the suite, and pins syrupy>=5 for snapshot assertions.
+- test: add macos 6.8.6 db fixture
+- test(e2e): rename audio fixtures to property-encoded scheme
+- Filenames now describe the audio's discriminating properties
+(NN-<codec>-<rate>-<depth-or-bitrate>[-encmode].<ext>) so each file's purpose
+is obvious in a directory listing and in test code. Codec stays in the name
+even for unambiguous extensions to keep the convention uniform and to
+disambiguate ALAC vs AAC inside .m4a.
+- Required before Phase 3 (Rekordbox import) so master.db references the new
+paths. Generator script and library table updated in gist
+https://gist.github.com/jviall/18107ca35e0e7f38cf02ba50e3b9cc77
 - test(e2e): add 10-track audio fixture for end-to-end suite
 - Synthesized sine-wave audio covering FLAC (16/24-bit), ALAC, AIFF, WAV,
 MP3 (CBR + VBR), AAC, and a unicode-tagged FLAC. Used by the e2e journey

rekordbox_edit-0.6.0.dev40/Makefile

@@ -0,0 +1,42 @@
+.PHONY: test test-e2e test-e2e-docker test-e2e-snapshot-update coverage lint format typecheck install-hooks run-hooks docs docs-build
+
+test:
+	uv run pytest tests
+
+RBE_DB_VERSION ?= 6.8.6
+
+test-e2e:
+	RBE_DB_VERSION=$(RBE_DB_VERSION) uv run pytest tests/e2e --snapshot-warn-unused
+
+test-e2e-docker:
+	RBE_DB_VERSION=$(RBE_DB_VERSION) docker compose run --rm e2e
+
+test-e2e-snapshot-update:
+	RBE_DB_VERSION=$(RBE_DB_VERSION) docker compose run --rm e2e uv run pytest tests/e2e --snapshot-update
+
+watch:
+	uv run ptw .
+
+coverage:
+	uv run pytest tests --cov=rekordbox_edit --junitxml=.coverage/junit.xml --cov-report=term-missing --cov-report=html --cov-report=xml
+
+lint:
+	uv run ruff check --fix
+
+format:
+	uv run ruff format
+
+typecheck:
+	uv run ty check
+
+install-hooks:
+	uv run pre-commit install --hook-type pre-commit --hook-type commit-msg
+
+run-hooks:
+	uv run pre-commit run --all-files
+
+docs:
+	uv run --group docs mkdocs serve
+
+docs-build:
+	uv run --group docs mkdocs build --strict

rekordbox_edit-0.6.0.dev40/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: rekordbox-edit
+Version: 0.6.0.dev40
+Summary: Tools for managing and modifying a RekordBox library en-masse
+Project-URL: Homepage, https://github.com/jviall/rekordbox-edit
+Project-URL: Repository, https://github.com/jviall/rekordbox-edit
+Project-URL: Issues, https://github.com/jviall/rekordbox-edit/issues
+Author-email: James Viall <jamesviall@pm.me>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bulk,convert,database,dj,edit,music,rekordbox
+Requires-Python: >=3.11
+Requires-Dist: click<=9.0.0,>=8.0.0
+Requires-Dist: ffmpeg-python>=0.2.0
+Requires-Dist: platformdirs<5.0.0,>=4.3.8
+Requires-Dist: pydantic<3,>=2.0
+Requires-Dist: pyrekordbox==0.4.4
+Requires-Dist: rich<15.1.0,>=15.0.0
+Description-Content-Type: text/markdown
+
+# rekordbox-edit
+
+[![Build](https://img.shields.io/github/actions/workflow/status/jviall/rekordbox-edit/cd.yml?branch=main&logo=github&style=flat)](https://github.com/jviall/rekordbox-edit/blob/main/.github/workflows/cd.yml)
+[![Coverage](https://codecov.io/gh/jviall/rekordbox-edit/graph/badge.svg?token=ILZ1XHE61V)](https://codecov.io/gh/jviall/rekordbox-edit)
+[![Version](https://img.shields.io/pypi/v/rekordbox-edit?style=flat)](https://pypi.org/project/rekordbox-edit/)
+[![Platforms](https://img.shields.io/badge/platform-win%20%7C%20osx-blue?style=flat)](https://pypi.org/project/rekordbox-edit/)
+[![License](https://img.shields.io/pypi/l/rekordbox-edit?color=lightgrey)](https://github.com/jviall/rekordbox-edit/blob/main/LICENSE)
+
+A command-line tool for bulk operations on your Rekordbox library. Search tracks, edit metadata, and convert audio formats — updating your database while preserving all your cues, analysis, and metadata.
+
+> [!CAUTION]
+> This tool can modify your Rekordbox database and audio files. Always back up your data first.
+> No warranty is provided--you assume all risk and liability of data loss in using this.
+> See [Safety and Best Practices](#safety-and-best-practices)
+
+**Full documentation: [rekordbox-edit.readthedocs.io](https://rekordbox-edit.readthedocs.io/)**
+
+## Installation
+
+```bash
+pip install rekordbox-edit
+```
+
+**Requirements:**
+
+- Python 3.11+
+- FFmpeg (for audio conversion)
+
+## Quick Start
+
+Search your library:
+
+```bash
+rbe search --artist "Daft Punk" --format flac
+rbe search --playlist "House Favorites"
+```
+
+Edit track metadata:
+
+```bash
+# Fix a typo across every matching title (previews and confirms first)
+rbe edit --title "Teh" Title --match "Teh" --replace "The" --multi
+```
+
+Convert audio files:
+
+```bash
+# Preview what would be converted
+rbe convert --artist "Daft Punk" --dry-run
+
+# Convert all FLAC or WAV files to AIFF (default output format)
+rbe convert --format flac --format wav --yes
+```
+
+See the [documentation](https://rekordbox-edit.readthedocs.io/) for every command, the full filtering language, and scripting recipes.
+
+## Safety and Best Practices
+
+**Before using this tool:**
+
+1. **Back up your Rekordbox database**
+
+   Rekordbox already keeps multiple backups. But every time you close it, it creates a fresh one and deletes the oldest, so repetitive exits will quickly make those backups fairly useless.
+
+   You should make manual copies of RB's database backups before using this. You can usually find them in `~/Library/Pioneer/rekordbox/` on macOS or `%APPDATA%\Pioneer\rekordbox\` on Windows.
+
+2. **Back up your music library**
+
+   If you don't have a back up already it's a very worthwhile investment, even if you don't plan to use this tool! Find yourself a cheap external drive, you won't regret it.
+
+And generally limit the potential impact of a mistake by using filters to target a few tracks at a time e.g. `--artist "Crazy Frog" --first 5` before targeting a larger set, and always run with `--dry-run` first.
+
+## AI Usage
+
+I believe it's important to be aware of and to disclose AI usage. In many ways it's being forced upon us without us having much choice in the matter, and it's a gross and oppressive experience. While it has lots of potential to benefit the common good, mostly it's only furthered capitalist greed.
+
+I'm mostly attempting to thoughtfully disclose that generative AI _has_ been a significant tool in building out this project. I don't personally enjoy too much coding in my personal time, but I feel passionate about making `rekordbox-edit`--AI has admittedly helped me bridge that gap between my capacity and my vision. I'm a career professional software engineer who takes pride in their work, and I don't want to produce a vibe coded mess any more than you want to experience it. Please validate the quality of this project yourself--at the end of the day it's just code written by some stranger.
+
+If it's any consolation, my main test subject has been my own 10,000+ track RekordBox library--a risk I do not take lightly!
+
+## Credits
+
+This project exists thanks to [@dylanjones](https://github.com/dylanjones), the creator of [pyrekordbox](https://github.com/dylanljones/pyrekordbox), which provides the Python API for Rekordbox databases.
+
+I built this tool to help correct my own bad habits and missteps in managing and organizing my rekordbox library. If it helps you too, great! If you find issues or have ideas, contributions are welcome.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/jviall/rekordbox-edit/blob/main/CONTRIBUTING.md) for development setup, testing, and contribution guidelines.

rekordbox_edit-0.6.0.dev40/README.md

@@ -0,0 +1,89 @@
+# rekordbox-edit
+
+[![Build](https://img.shields.io/github/actions/workflow/status/jviall/rekordbox-edit/cd.yml?branch=main&logo=github&style=flat)](https://github.com/jviall/rekordbox-edit/blob/main/.github/workflows/cd.yml)
+[![Coverage](https://codecov.io/gh/jviall/rekordbox-edit/graph/badge.svg?token=ILZ1XHE61V)](https://codecov.io/gh/jviall/rekordbox-edit)
+[![Version](https://img.shields.io/pypi/v/rekordbox-edit?style=flat)](https://pypi.org/project/rekordbox-edit/)
+[![Platforms](https://img.shields.io/badge/platform-win%20%7C%20osx-blue?style=flat)](https://pypi.org/project/rekordbox-edit/)
+[![License](https://img.shields.io/pypi/l/rekordbox-edit?color=lightgrey)](https://github.com/jviall/rekordbox-edit/blob/main/LICENSE)
+
+A command-line tool for bulk operations on your Rekordbox library. Search tracks, edit metadata, and convert audio formats — updating your database while preserving all your cues, analysis, and metadata.
+
+> [!CAUTION]
+> This tool can modify your Rekordbox database and audio files. Always back up your data first.
+> No warranty is provided--you assume all risk and liability of data loss in using this.
+> See [Safety and Best Practices](#safety-and-best-practices)
+
+**Full documentation: [rekordbox-edit.readthedocs.io](https://rekordbox-edit.readthedocs.io/)**
+
+## Installation
+
+```bash
+pip install rekordbox-edit
+```
+
+**Requirements:**
+
+- Python 3.11+
+- FFmpeg (for audio conversion)
+
+## Quick Start
+
+Search your library:
+
+```bash
+rbe search --artist "Daft Punk" --format flac
+rbe search --playlist "House Favorites"
+```
+
+Edit track metadata:
+
+```bash
+# Fix a typo across every matching title (previews and confirms first)
+rbe edit --title "Teh" Title --match "Teh" --replace "The" --multi
+```
+
+Convert audio files:
+
+```bash
+# Preview what would be converted
+rbe convert --artist "Daft Punk" --dry-run
+
+# Convert all FLAC or WAV files to AIFF (default output format)
+rbe convert --format flac --format wav --yes
+```
+
+See the [documentation](https://rekordbox-edit.readthedocs.io/) for every command, the full filtering language, and scripting recipes.
+
+## Safety and Best Practices
+
+**Before using this tool:**
+
+1. **Back up your Rekordbox database**
+
+   Rekordbox already keeps multiple backups. But every time you close it, it creates a fresh one and deletes the oldest, so repetitive exits will quickly make those backups fairly useless.
+
+   You should make manual copies of RB's database backups before using this. You can usually find them in `~/Library/Pioneer/rekordbox/` on macOS or `%APPDATA%\Pioneer\rekordbox\` on Windows.
+
+2. **Back up your music library**
+
+   If you don't have a back up already it's a very worthwhile investment, even if you don't plan to use this tool! Find yourself a cheap external drive, you won't regret it.
+
+And generally limit the potential impact of a mistake by using filters to target a few tracks at a time e.g. `--artist "Crazy Frog" --first 5` before targeting a larger set, and always run with `--dry-run` first.
+
+## AI Usage
+
+I believe it's important to be aware of and to disclose AI usage. In many ways it's being forced upon us without us having much choice in the matter, and it's a gross and oppressive experience. While it has lots of potential to benefit the common good, mostly it's only furthered capitalist greed.
+
+I'm mostly attempting to thoughtfully disclose that generative AI _has_ been a significant tool in building out this project. I don't personally enjoy too much coding in my personal time, but I feel passionate about making `rekordbox-edit`--AI has admittedly helped me bridge that gap between my capacity and my vision. I'm a career professional software engineer who takes pride in their work, and I don't want to produce a vibe coded mess any more than you want to experience it. Please validate the quality of this project yourself--at the end of the day it's just code written by some stranger.
+
+If it's any consolation, my main test subject has been my own 10,000+ track RekordBox library--a risk I do not take lightly!
+
+## Credits
+
+This project exists thanks to [@dylanjones](https://github.com/dylanjones), the creator of [pyrekordbox](https://github.com/dylanljones/pyrekordbox), which provides the Python API for Rekordbox databases.
+
+I built this tool to help correct my own bad habits and missteps in managing and organizing my rekordbox library. If it helps you too, great! If you find issues or have ideas, contributions are welcome.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/jviall/rekordbox-edit/blob/main/CONTRIBUTING.md) for development setup, testing, and contribution guidelines.

rekordbox_edit-0.6.0.dev40/docker-compose.yml

@@ -0,0 +1,14 @@
+services:
+  e2e:
+    build:
+      context: .
+      dockerfile: tests/e2e/Dockerfile
+    environment:
+      RBE_RUN_E2E: "1"
+      RBE_DB_VERSION: "${RBE_DB_VERSION:?RBE_DB_VERSION must be set (e.g. 6.8.6)}"
+      TZ: "UTC"
+    volumes:
+      # Mount the source tree so generated snapshots flow back to the host;
+      # uv.lock is read from the image's pre-built .venv at /app/.venv.
+      - .:/app
+      - /app/.venv

rekordbox_edit-0.6.0.dev40/docs/api.md

@@ -0,0 +1,28 @@
+# API Reference
+
+Everything the CLI does is available from Python. The public surface is the three functions in `rekordbox_edit.api` and the Pydantic models in `rekordbox_edit.models` that describe their inputs and outputs.
+
+```python
+from pyrekordbox import Rekordbox6Database
+from rekordbox_edit.api import search
+from rekordbox_edit.models import SearchArgs
+
+db = Rekordbox6Database()
+response = search(db, SearchArgs(artist=["Daft Punk"], format=["flac"], match_all=True))
+for track in response.tracks:
+    print(track.ID, track.Title)
+```
+
+`--print json` on any CLI command emits exactly these response envelopes, so the models below also document the JSON you get when scripting.
+
+## Functions
+
+::: rekordbox_edit.api.search
+
+::: rekordbox_edit.api.edit
+
+::: rekordbox_edit.api.convert
+
+## Models
+
+::: rekordbox_edit.models

rekordbox_edit-0.6.0.dev40/docs/commands/convert.md

@@ -0,0 +1,46 @@
+# convert
+
+Convert audio files between formats and update the Rekordbox database to point at the new files. Your cues, analysis, beatgrids, and all metadata are preserved.
+
+## Supported Formats
+
+- **Input:** FLAC, AIFF, WAV (lossless only — lossy sources are skipped)
+- **Output:** AIFF (default), FLAC, WAV, ALAC, or MP3 (320kbps CBR)
+
+Tracks already in the target format are skipped, as are tracks whose output file already exists (override with `--overwrite`).
+
+## Originals: Delete or Keep
+
+After a successful conversion the original file is **deleted** for lossless output (you can always convert back) and **kept** for MP3 output (the quality loss is one-way). Override either default with `--delete` or `--keep`.
+
+## Examples
+
+```bash
+# Preview conversion
+rbe convert --format-out aiff --format flac --dry-run
+
+# Convert and skip confirmation
+rbe convert --format-out wav --artist "Burial" --yes
+
+# Convert to MP3 but delete originals
+rbe convert --format-out mp3 --playlist "Export" --yes --delete
+
+# Keep originals when converting to AIFF
+rbe convert --format-out aiff --format flac --yes --keep
+
+# Get just the IDs of files that would be converted
+rbe convert --format-out aiff --format flac --print ids --dry-run
+
+# Convert everything a search finds
+rbe search --artist "Lauryn Hill" --print ids | rbe convert --yes
+```
+
+`--interactive` confirms each file individually; like `edit`, converting while Rekordbox is open triggers a warning (or a refusal in scripting modes). See [Filtering](../filtering.md) for the full filter language.
+
+## Reference
+
+::: mkdocs-click
+    :module: rekordbox_edit.cli.convert
+    :command: convert_command
+    :prog_name: rbe convert
+    :depth: 1

rekordbox_edit-0.6.0.dev40/docs/commands/edit.md

@@ -0,0 +1,48 @@
+# edit
+
+Bulk-edit a metadata field on tracks in your Rekordbox database.
+
+```bash
+rbe edit [OPTIONS] [TRACK-IDS]... FIELD
+```
+
+`FIELD` names the metadata field to change. Currently `Title` is the only editable field; more are planned.
+
+`--replace` supplies the new value. On its own it overwrites the whole field; add `--match PATTERN` to find that literal text within the field and replace only that portion:
+
+```bash
+# Rename one track outright
+rbe edit --exact-title "Untitled 3" Title --replace "Acid Rain"
+
+# Fix a typo across many titles (substring replacement)
+rbe edit --title "Teh" Title --match "Teh" --replace "The" --multi
+```
+
+## Safety Rails
+
+- **Preview and confirm by default.** Without flags, `edit` shows every planned change and asks once before applying. `--interactive` confirms each track individually; `--dry-run` previews without writing; `--yes` skips the prompt.
+- **Single-track by default.** When filters match more than one track, `edit` refuses unless you pass `--multi`. This keeps a too-broad filter from rewriting your whole library.
+- **Rekordbox running:** editing while Rekordbox is open risks conflicts, so `edit` warns (or refuses, in scripting modes).
+
+## Examples
+
+```bash
+# Preview a cleanup without touching the database
+rbe edit --title "(Original Mix)" Title --match " (Original Mix)" --replace "" --multi --dry-run
+
+# Apply it, confirming each track
+rbe edit --title "(Original Mix)" Title --match " (Original Mix)" --replace "" --multi --interactive
+
+# Pipe a search result in and edit those exact tracks
+rbe search --playlist "Mislabeled" --print ids | rbe edit Title --match "  " --replace " " --multi --yes
+```
+
+See [Filtering](../filtering.md) for the full filter language.
+
+## Reference
+
+::: mkdocs-click
+    :module: rekordbox_edit.cli.edit
+    :command: edit_command
+    :prog_name: rbe edit
+    :depth: 1

rekordbox_edit-0.6.0.dev40/docs/commands/search.md

@@ -0,0 +1,29 @@
+# search
+
+Find and display tracks in your Rekordbox database. `search` is read-only: it never modifies the database or your files, which makes it the safe way to rehearse a [filter](../filtering.md) before handing it to `edit` or `convert`.
+
+## Examples
+
+```bash
+# Show all FLAC tracks by an artist
+rbe search --artist "Aphex Twin" --format flac
+
+# Get all the track IDs in a playlist
+rbe search --playlist "Techno" --print ids
+
+# Find tracks matching ALL filters (AND logic)
+rbe search --artist "Burial" --album "Untrue" --match-all
+
+# Feed results to another command
+rbe search --artist "Lauryn Hill" --print ids | rbe convert --yes
+```
+
+See [Filtering](../filtering.md) for the full filter language and piping recipes.
+
+## Reference
+
+::: mkdocs-click
+    :module: rekordbox_edit.cli.search
+    :command: search_command
+    :prog_name: rbe search
+    :depth: 1