---
source: crates/core/src/commands/docs/tests/docs_command_tests.rs
expression: output
---
# Options Reference

This document describes all configuration options available in caesura.
Options can be set via CLI flags or in `config.yml`.

| YAML Key / CLI Flag                                                      | Type                  | Default                                                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                | Commands                                                                                          |
| ------------------------------------------------------------------------ | --------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `allow_existing`<br><br>`--allow-existing`                               | `bool`                | `false`                                                         | Allow transcoding to existing formats.<br>Note: This is only useful for development and should probably not be used.                                                                                                                                                                                                                                                                                                       | `batch`, `cross`, `transcode`, `upload`, `verify`                                                 |
| `allow_less_specific`<br><br>`--allow-less-specific`                     | `bool`                | `false`                                                         | Allow transcoding when the source has empty edition fields but an existing torrent does not.                                                                                                                                                                                                                                                                                                                               | `batch`, `cross`, `transcode`, `upload`, `verify`                                                 |
| `announce_url`<br><br>`--announce-url`                                   | `String`              | `""`                                                            | Announce URL including passkey<br>Examples: `https://flacsfor.me/a1b2c3d4e5f6/announce`, `https://home.opsfet.ch/a1b2c3d4e5f6/announce`                                                                                                                                                                                                                                                                                    | All                                                                                               |
| `api_key`<br><br>`--api-key`                                             | `String`              | `""`                                                            | API key with torrent permissions for the indexer.                                                                                                                                                                                                                                                                                                                                                                          | All                                                                                               |
| `cache`<br><br>`--cache`                                                 | `PathBuf`             | `~/.cache/caesura/` or platform equivalent                      | Path to cache directory.                                                                                                                                                                                                                                                                                                                                                                                                   | `batch`, `cross`, `queue add`, `queue fetch`, `queue list`, `queue rm`, `queue summary`, `verify` |
| `config`<br><br>`--config`                                               | `Option<PathBuf>`     | `~/.config/caesura/config.yml` or platform equivalent           | Path to the configuration file.                                                                                                                                                                                                                                                                                                                                                                                            | All                                                                                               |
| `content`<br><br>`--content`                                             | `Vec<PathBuf>`        | `[]`                                                            | Directories containing torrent content.<br>Typically this is set as the download directory in your torrent client.                                                                                                                                                                                                                                                                                                         | All                                                                                               |
| `copy_cross_torrent_to`<br><br>`--copy-cross-torrent-to`                 | `Option<PathBuf>`     | ~                                                               | Directory the cross-seed `.torrent` file is copied to after download.<br>This should be set if you wish to auto-add to your torrent client via a watch directory.                                                                                                                                                                                                                                                          | `cross`                                                                                           |
| `copy_torrent_to`<br><br>`--copy-torrent-to`                             | `Option<PathBuf>`     | ~                                                               | Directory the torrent file is copied to.<br>This should be set if you wish to auto-add to your torrent client.                                                                                                                                                                                                                                                                                                             | `batch`, `upload`                                                                                 |
| `copy_transcode_to_content_dir`<br><br>`--copy-transcode-to-content-dir` | `bool`                | `false`                                                         | Should the transcoded files be copied to the content directory?                                                                                                                                                                                                                                                                                                                                                            | `batch`, `upload`                                                                                 |
| `copy_transcode_to`<br><br>`--copy-transcode-to`                         | `Option<PathBuf>`     | ~                                                               | Directory the transcoded files are copied to.<br>This should be set if you wish to auto-add to your torrent client.                                                                                                                                                                                                                                                                                                        | `batch`, `upload`                                                                                 |
| `cpus`<br><br>`--cpus`                                                   | `Option<u16>`         | Total CPUs                                                      | Number of cpus to use for processing.                                                                                                                                                                                                                                                                                                                                                                                      | `batch`, `spectrogram`, `transcode`                                                               |
| `cross_config`<br><br>`--cross-config`                                   | `Option<PathBuf>`     | ~                                                               | Path to a config file for the cross indexer.<br>Only `api_key`, `indexer`, and `indexer_url` are used.                                                                                                                                                                                                                                                                                                                     | `cross`                                                                                           |
| `dry_run`<br><br>`--dry-run`                                             | `bool`                | `false`                                                         | Perform the cross seed lookup but skip downloading and injection.                                                                                                                                                                                                                                                                                                                                                          | `cross`                                                                                           |
| `dry_run`<br><br>`--dry-run`                                             | `bool`                | `false`                                                         | Is this a dry run?<br>If enabled data won't be uploaded and will instead be printed to the console.                                                                                                                                                                                                                                                                                                                        | `batch`, `upload`                                                                                 |
| `exclude_tags`<br><br>`--exclude-tags`                                   | `Option<Vec<String>>` | ~                                                               | Should sources with specific tags be excluded?                                                                                                                                                                                                                                                                                                                                                                             | `batch`, `verify`                                                                                 |
| `exclude_vorbis_comments`<br><br>`--exclude-vorbis-comments`             | `Vec<String>`         | `["COMMENT", "ENCODER", "ENCODING", "RATING", "WORK"]`          | Vorbis comment tag names to exclude from transcoded output.                                                                                                                                                                                                                                                                                                                                                                | `batch`, `cross`, `transcode`, `upload`, `verify`                                                 |
| `hard_link`<br><br>`--hard-link`                                         | `bool`                | `false`                                                         | Should files be hard linked instead of copied?<br>Enabling this option requires the source and destination to be on the same filesystem or mounted volume.                                                                                                                                                                                                                                                                 | `batch`, `cross`, `transcode`, `upload`                                                           |
| `indexer_url`<br><br>`--indexer-url`                                     | `String`              | from announce_url                                               | URL of the indexer.<br>Examples: `https://redacted.sh`, `https://orpheus.network`                                                                                                                                                                                                                                                                                                                                          | All                                                                                               |
| `indexer`<br><br>`--indexer`                                             | `String`              | from announce_url                                               | ID of the tracker as it appears in the source field of a torrent.<br>Examples: `red`, `pth`, `ops`                                                                                                                                                                                                                                                                                                                         | All                                                                                               |
| `inject_torrent`<br><br>`--inject-torrent`                               | `bool`                | `false`                                                         | Should the torrent be injected into qBittorrent after upload?                                                                                                                                                                                                                                                                                                                                                              | `batch`, `upload`                                                                                 |
| `inspect_path`                                                           | `PathBuf`             | `""`                                                            | Path to directory containing audio files.                                                                                                                                                                                                                                                                                                                                                                                  | `inspect`                                                                                         |
| `jpg_quality`<br><br>`--jpg-quality`                                     | `u8`                  | `80`                                                            | Quality percentage to apply for jpg compression.<br>Only applied if the image is greater than `max_file_size`.                                                                                                                                                                                                                                                                                                             | `batch`, `cross`, `transcode`                                                                     |
| `limit`<br><br>`--limit`                                                 | `usize`               | `3`                                                             | Limit the number of torrents to batch process.<br>If `no_limit` is set, this option is ignored.                                                                                                                                                                                                                                                                                                                            | `batch`, `queue list`                                                                             |
| `log_time`<br><br>`--log-time`                                           | `TimeFormat`          | `"local"`                                                       | Time format to use in logs.                                                                                                                                                                                                                                                                                                                                                                                                | All                                                                                               |
| `max_file_size`<br><br>`--max-file-size`                                 | `u64`                 | `750000`                                                        | Maximum file size in bytes beyond which images are compressed.<br>Only applies to image files.                                                                                                                                                                                                                                                                                                                             | `batch`, `cross`, `transcode`                                                                     |
| `max_pixel_size`<br><br>`--max-pixel-size`                               | `u32`                 | `1280`                                                          | Maximum size in pixels for images.<br>Only applied if the image is greater than `max_file_size`.                                                                                                                                                                                                                                                                                                                           | `batch`, `cross`, `transcode`                                                                     |
| `no_hash_check`<br><br>`--no-hash-check`                                 | `bool`                | `false`                                                         | Should the hash check of source files be skipped?<br>Note: This is only useful for development and should probably not be used.                                                                                                                                                                                                                                                                                            | `batch`, `verify`                                                                                 |
| `no_image_compression`<br><br>`--no-image-compression`                   | `bool`                | `false`                                                         | Should compression of images be disabled?                                                                                                                                                                                                                                                                                                                                                                                  | `batch`, `cross`, `transcode`                                                                     |
| `no_limit`<br><br>`--no-limit`                                           | `bool`                | `false`                                                         | Should the `limit` option be ignored?                                                                                                                                                                                                                                                                                                                                                                                      | `batch`, `queue list`                                                                             |
| `no_png_to_jpg`<br><br>`--no-png-to-jpg`                                 | `bool`                | `false`                                                         | Should conversion of png images to jpg be disabled?<br>Only applied if the image is greater than `max_file_size`.                                                                                                                                                                                                                                                                                                          | `batch`, `cross`, `transcode`                                                                     |
| `no_reports`<br><br>`--no-reports`                                       | `bool`                | `false`                                                         | Disable automatic report generation.                                                                                                                                                                                                                                                                                                                                                                                       | `batch`, `verify`                                                                                 |
| `output`<br><br>`--output`                                               | `PathBuf`             | `~/.local/share/caesura/output/` or platform equivalent         | Directory where transcodes and spectrograms will be written.                                                                                                                                                                                                                                                                                                                                                               | All                                                                                               |
| `qbit_cross_category`<br><br>`--qbit-cross-category`                     | `Option<String>`      | ~                                                               | qBittorrent category for cross-seed torrents.<br>Default: `caesura`                                                                                                                                                                                                                                                                                                                                                        | `cross`                                                                                           |
| `qbit_cross_paused`<br><br>`--qbit-cross-paused`                         | `Option<bool>`        | ~                                                               | Add cross-seed torrents in paused state.                                                                                                                                                                                                                                                                                                                                                                                   | `cross`                                                                                           |
| `qbit_cross_savepath`<br><br>`--qbit-cross-savepath`                     | `Option<String>`      | ~                                                               | qBittorrent save path for cross-seed torrents.                                                                                                                                                                                                                                                                                                                                                                             | `cross`                                                                                           |
| `qbit_cross_skip_checking`<br><br>`--qbit-cross-skip-checking`           | `Option<bool>`        | ~                                                               | Skip hash checking when injecting cross-seed torrents.                                                                                                                                                                                                                                                                                                                                                                     | `cross`                                                                                           |
| `qbit_cross_tags`<br><br>`--qbit-cross-tags`                             | `Option<Vec<String>>` | ~                                                               | qBittorrent tags for cross-seed torrents.<br>Default: `["caesura"]`                                                                                                                                                                                                                                                                                                                                                        | `cross`                                                                                           |
| `qbit_cross`<br><br>`--qbit-cross`                                       | `bool`                | `false`                                                         | Should the cross-seed torrent be injected into qBittorrent?                                                                                                                                                                                                                                                                                                                                                                | `cross`                                                                                           |
| `qbit_fetch_categories`<br><br>`--qbit-fetch-categories`                 | `Vec<String>`         | `[]`                                                            | qBittorrent categories to discover torrents from.<br>`queue fetch` queries the qBittorrent API filtered by these categories<br>and adds any fully downloaded torrents that are not already in the queue.<br>An empty string (`""`) fetches torrents that have no category assigned.                                                                                                                                        | `queue fetch`                                                                                     |
| `qbit_inject_category`<br><br>`--qbit-inject-category`                   | `Option<String>`      | ~                                                               | qBittorrent category for injected torrents.                                                                                                                                                                                                                                                                                                                                                                                | `batch`, `upload`                                                                                 |
| `qbit_inject_paused`<br><br>`--qbit-inject-paused`                       | `Option<bool>`        | ~                                                               | Add injected torrents in paused state.                                                                                                                                                                                                                                                                                                                                                                                     | `batch`, `upload`                                                                                 |
| `qbit_inject_savepath`<br><br>`--qbit-inject-savepath`                   | `Option<String>`      | ~                                                               | qBittorrent save path for injected torrents.                                                                                                                                                                                                                                                                                                                                                                               | `batch`, `upload`                                                                                 |
| `qbit_inject_skip_checking`<br><br>`--qbit-inject-skip-checking`         | `Option<bool>`        | ~                                                               | Skip hash checking when injecting torrents.                                                                                                                                                                                                                                                                                                                                                                                | `batch`, `upload`                                                                                 |
| `qbit_inject_tags`<br><br>`--qbit-inject-tags`                           | `Option<Vec<String>>` | ~                                                               | qBittorrent tags for injected torrents.                                                                                                                                                                                                                                                                                                                                                                                    | `batch`, `upload`                                                                                 |
| `qbit_password`<br><br>`--qbit-password`                                 | `Option<String>`      | ~                                                               | qBittorrent password.<br>Not required when using qui reverse proxy.                                                                                                                                                                                                                                                                                                                                                        | `batch`, `cross`, `queue fetch`, `upload`                                                         |
| `qbit_url`<br><br>`--qbit-url`                                           | `Option<String>`      | ~                                                               | qBittorrent API base URL<br>The base URL for your qBittorrent instance<br>Examples: `http://localhost:8080`, `http://qbit`, `https://qbit.example.com`<br>Or, the proxy URL with key if using [qui reverse proxy](https://getqui.com/docs/features/reverse-proxy)<br>Examples:<br>- `http://localhost:7476/proxy/YOUR_CLIENT_PROXY_KEY`<br>- `https://qui.example.com/proxy/YOUR_CLIENT_PROXY_KEY`                         | `batch`, `cross`, `queue fetch`, `upload`                                                         |
| `qbit_username`<br><br>`--qbit-username`                                 | `Option<String>`      | ~                                                               | qBittorrent username.<br>Not required when using qui reverse proxy.                                                                                                                                                                                                                                                                                                                                                        | `batch`, `cross`, `queue fetch`, `upload`                                                         |
| `queue_add_path`                                                         | `Option<PathBuf>`     | ~                                                               | A path to either a directory of `.torrent` files or a single YAML queue file.<br>If you set this to the directory your torrent client stores `.torrent` files then caesura<br>will automatically load everything from your client.<br>- For qBittorrent use the `BT_backup` directory<br>- For deluge use the `state` directory<br>Examples:<br>- `/srv/qBittorrent/BT_backup`<br>- `/srv/deluge/state`<br>- `./queue.yml` | `queue add`                                                                                       |
| `queue_rm_hash`                                                          | `String`              | `""`                                                            | A torrent hash                                                                                                                                                                                                                                                                                                                                                                                                             | `queue rm`                                                                                        |
| `rename_tracks`<br><br>`--rename-tracks`                                 | `bool`                | `false`                                                         | Should transcoded files be renamed?<br>If enabled then tracks are renamed into a standardized format: `{number} {title}.{ext}`.<br>Multi-disc releases will be organized into `CD1/`, `CD2/` subfolders.<br>- `1 Example track title.flac`<br>- `CD1/10 Example track title.mp3`                                                                                                                                           | `batch`, `cross`, `transcode`                                                                     |
| `reports_dir`<br><br>`--reports-dir`                                     | `PathBuf`             | `~/.local/share/caesura/output/reports/` or platform equivalent | Path to the directory where generated reports are written.                                                                                                                                                                                                                                                                                                                                                                 | `batch`, `verify`                                                                                 |
| `retry_transcode`<br><br>`--retry-transcode`                             | `bool`                | `false`                                                         | Should failed transcodes be retried?                                                                                                                                                                                                                                                                                                                                                                                       | `batch`, `queue list`                                                                             |
| `source`                                                                 | `String`              | `""`                                                            | Source as: torrent id, path to torrent file, indexer url, or 40-character info hash.<br>Examples:<br>`4871992`,<br>`path/to/something.torrent`,<br>`https://example.com/torrents.php?id=2259978&torrentid=4871992#torrent4871992`,<br>`https://example.com/torrents.php?torrentid=4871992`, or<br>`0123456789abcdef0123456789abcdef01234567`                                                                               | `cross`, `spectrogram`, `transcode`, `upload`, `verify`                                           |
| `sox_ng`<br><br>`--sox-ng`                                               | `bool`                | Detected based on binary name or --version info                 | Is `SoX_ng` in use?<br>If `true` then `sox_ng` specific CLI options are used.                                                                                                                                                                                                                                                                                                                                              | `batch`, `spectrogram`, `transcode`, `version`                                                    |
| `sox_path`<br><br>`--sox-path`                                           | `Option<PathBuf>`     | Detected based on sox_ng flag                                   | Name or path to the sox binary.<br>Examples: `sox`, `sox_ng`, `/usr/bin/sox`                                                                                                                                                                                                                                                                                                                                               | `batch`, `spectrogram`, `transcode`, `version`                                                    |
| `sox_random_dither`<br><br>`--sox-random-dither`                         | `bool`                | `false`                                                         | Use random dithering when resampling with `SoX`.<br>By default, `SoX` runs in repeatable mode (`-R`) which seeds the dither<br>random number generator with a fixed value, producing deterministic output.<br>Set this to `true` to use random dithering instead.                                                                                                                                                          | `batch`, `cross`, `transcode`, `upload`, `verify`                                                 |
| `spectrogram_size`<br><br>`--spectrogram-size`                           | `Vec<Size>`           | `["full", "zoom"]`                                              | Sizes of spectrograms to generate.                                                                                                                                                                                                                                                                                                                                                                                         | `batch`, `spectrogram`                                                                            |
| `spectrogram`<br><br>`--spectrogram`                                     | `bool`                | `false`                                                         | Should the spectrogram command be executed?                                                                                                                                                                                                                                                                                                                                                                                | `batch`, `queue list`                                                                             |
| `target`<br><br>`--target`                                               | `Vec<TargetFormat>`   | `["flac", "320", "v0"]`                                         | Formats to attempt to transcode to.                                                                                                                                                                                                                                                                                                                                                                                        | `batch`, `cross`, `transcode`, `upload`, `verify`                                                 |
| `transcode`<br><br>`--transcode`                                         | `bool`                | `false`                                                         | Should the transcode command be executed?                                                                                                                                                                                                                                                                                                                                                                                  | `batch`, `queue list`                                                                             |
| `upload`<br><br>`--upload`                                               | `bool`                | `false`                                                         | Should the upload command be executed?                                                                                                                                                                                                                                                                                                                                                                                     | `batch`, `queue list`                                                                             |
| `verbosity`<br><br>`--verbosity`                                         | `Verbosity`           | `"info"`                                                        | Level of logs to display.                                                                                                                                                                                                                                                                                                                                                                                                  | All                                                                                               |
| `wait_before_upload`<br><br>`--wait-before-upload`                       | `Option<String>`      | ~                                                               | Wait for a duration before uploading the torrent.<br>The duration is a string that can be parsed such as `500ms`, `5m`, `1h30m15s`.                                                                                                                                                                                                                                                                                        | `batch`, `queue list`                                                                             |
