# Backend-only CLI

The `bdm` entrypoint no longer executes or installs yt-dlp, ffmpeg, Deno, aria2c
or Python. The backend owns inspection, exact-format selection validation,
downloading, merging/conversion, verification and completion tracking. The client
only displays formats/progress and streams the live response to disk.

The interactive picker and `--list-formats` collapse raw duplicates using the
same compatibility ranking as the web: one actual ID per resolution, H.264/MP4
preferred, then one audio source. `--format` still accepts any advertised real ID.
The picker offers original audio and an MP3 action for that same source. Size
estimates are source sizes, not promises about merged or converted output size.
TTY progress distinguishes inspection/startup and the live transfer. Verified HTTP
lengths provide exact percentages; muxed streams use labelled source-size estimates
when available, capped below 100% until saved. Non-TTY logs have no ANSI codes.

## Configure and use

```sh
bdm config set backendUrl https://your-api.example/api/v1
bdm "https://youtu.be/VIDEO_ID" --quality 1080p
bdm "https://youtu.be/VIDEO_ID" --audio
bdm "https://youtu.be/VIDEO_ID" --list-formats
bdm "https://youtu.be/VIDEO_ID" --format 137
bdm --batch urls.txt ~/Videos --quality 720p
bdm doctor
```

Backend URL priority: `--backend`, `BDM_BACKEND_URL`, saved `backendUrl`, then
the verified production API (`https://download-me.up.railway.app/api/v1`). Remote
servers require HTTPS. Override the default to point at your own deployment when
needed. Never embed worker tokens in the client.

The client is stateless: the backend scopes anonymous jobs to the request IP, so
there is no session bootstrap or CSRF token. CLI jobs carry `source: CLI`; only
completed worker streams increment CLI completion totals, not merely ticket issuance. The source label is
client-reported, not authenticated installation identity. Optional
`--report-usage` records a CLI visit; the download request itself necessarily
exposes a request IP/agent to the server. No separate visit report is sent
without opt-in.

CLI 2.0.11 opts in with `liveStream: true`, preserving the stored-file path for old
clients. `STREAMABLE` returns a job-bound signed `artifactUrl`, which the client
opens immediately without complete-file preparation. In 2.0.12, dropped transfers
retry with `Range` and `If-Range`, verified against the original strong ETag.
Local offsets come from the closed partial file's actual size, not UI counters.
An inconsistent range is rejected; a full 200 response restarts rather than
appending a different entity. Retry-After is honoured while a mux finishes.
`DELIVERED` means the worker successfully sent the stream, not proof of disk save.
Legacy `READY` files still support the previous storage/range path.

Ctrl+C during setup or transfer requests backend cancellation. Polling is bounded to
15 minutes. Transfers stream to a private random `.part` file; incomplete files
are cleaned up. Destination files are never overwritten unless `--overwrite` is
set. The filename comes from the backend attachment header and is stripped of
directory components/unsafe characters.

## No Node installation for users

Build on the release platform with `npm ci && npm run build:standalone`. Build
tools need Node/npm, but the resulting archive contains a client executable with
its runtime embedded. End users need neither Node nor media tools installed.
Extract it and run `./bdm`, or use `./install.sh` on Linux/macOS. Windows users
run `bdm.exe`. npm/source installs still require Node; use the standalone archive
for Node-free installation. Supported binaries target Windows x64, macOS x64/ARM64,
and Linux x64/ARM64. CI runs the actual binary's help/version and mock live API
download with an empty PATH on every build platform, not just JavaScript tests.
A backend must be reachable for all downloads.

## Compatibility changes

- Only single YouTube videos are currently supported by the backend. The old
  CLI's TikTok/Facebook/Instagram/playlist support is not provided by this server.
- Batch input is sequential single-video API requests, not a server playlist job.
- Quality is exact: unavailable requested heights fail rather than downgrade.
- Local `--proxy`, cookies-from-browser, custom media User-Agent, subtitles,
  connections, aria2 and playlist flags are removed; they must be implemented as
  explicit backend features before the client can offer them.
- Server resource/file-size/duration restrictions still apply.
- Old local-engine source modules remain for reference and existing unit tests,
  but the CLI entrypoint and standalone bundle do not import them.

Apply backend Flyway migrations on restart before using the new client. V4 adds
job source attribution; V3 adds page-view request metadata.
