goget/docs/migration.md

# Migration from curl & wget

goget is designed as a drop-in replacement for `curl` and `wget` in most workflows. This guide helps you migrate existing scripts and commands.

## Quick Translation

### curl → goget

| curl | goget | Notes |
|---|---|---|
| `curl -O <URL>` | `goget --url <URL>` | Download with auto filename |
| `curl -o file.zip <URL>` | `goget --url <URL> --output file.zip` | Named output |
| `curl -C - <URL>` | `goget --url <URL> --resume` | Resume download |
| `curl -L <URL>` | `goget --url <URL>` | Redirects followed by default |
| `curl -H "K: V" <URL>` | `goget --header "K: V" --url <URL>` | Custom headers |
| `curl -d "data" <URL>` | `goget --data "data" --url <URL>` | POST data |
| `curl -F "f=@file" <URL>` | `goget --form "f=@file" --url <URL>` | Multipart upload |
| `curl -k <URL>` | `goget --insecure --url <URL>` | Skip TLS verify |
| `curl -x <proxy> <URL>` | `goget --proxy <proxy> --url <URL>` | HTTP proxy |
| `curl -I <URL>` | `goget --spider --url <URL>` | HEAD request only |
| `curl --create-dirs <URL>` | `goget --url <URL>` | Create dirs (default in goget) |
| `curl --max-time 30 <URL>` | `goget --max-time 30s --url <URL>` | Max transfer time |
| `curl --cert cert.pem --key key.pem` | `goget --cert cert.pem --key key.pem --url <URL>` | mTLS |
| `curl -w "%{http_code}" <URL>` | `goget --write-out "%{http_code}" --url <URL>` | Metadata output |
| `curl -s <URL>` | `goget --quiet --url <URL>` | Silent mode |
| `curl -v <URL>` | `goget --verbose --url <URL>` | Verbose mode |
| `curl -b cookies.txt <URL>` | `goget --cookie-jar cookies.txt --url <URL>` | Cookies |
| `curl --ssl-key-log-file keys.log` | `goget --ssl-key-log keys.log --url <URL>` | SSL key log |
| `curl --retry-all-errors <URL>` | `goget --retry-all-errors --url <URL>` | Retry on all errors |

### wget → goget

| wget | goget | Notes |
|---|---|---|
| `wget <URL>` | `goget --url <URL>` | Basic download |
| `wget -O file.zip <URL>` | `goget --url <URL> --output file.zip` | Named output |
| `wget -c <URL>` | `goget --url <URL> --resume` | Resume download |
| `wget -r <URL>` | `goget --url <URL> --recursive` | Recursive download |
| `wget -r -l 3 <URL>` | `goget --url <URL> --recursive --max-depth 3` | Depth limit |
| `wget -m <URL>` | `goget --url <URL> --mirror` | Full mirror |
| `wget --mirror --convert-links` | `goget --url <URL> --mirror` | Mirror + convert links |
| `wget -p <URL>` | `goget --url <URL> --page-requisites` | Page requisites |
| `wget -A "*.pdf" <URL>` | `goget --url <URL> --accept "*.pdf"` | Accept pattern |
| `wget -R "*.zip" <URL>` | `goget --url <URL> --reject "*.zip"` | Reject pattern |
| `wget -np <URL>` | `goget --url <URL> --no-parent` | No parent dir |
| `wget -H <URL>` | `goget --url <URL> --span-hosts` | Span hosts |
| `wget -D a.com,b.com <URL>` | `goget --url <URL> --domains a.com,b.com` | Limit domains |
| `wget -w 2 <URL>` | `goget --url <URL> --wait 2s` | Delay between requests |
| `wget --random-wait <URL>` | `goget --url <URL> --random-wait` | Random delay |
| `wget --limit-rate 1M <URL>` | `goget --url <URL> --rate-limit 1MB/s` | Rate limit |
| `wget --warc-file=archive` | `goget --url <URL> --warc-file archive.warc` | WARC output |
| `wget --progress=dot <URL>` | `goget --url <URL> --progress=dot` | Dot progress |
| `wget --adjust-extension <URL>` | `goget --url <URL> --adjust-extension` | Add .html extension |
| `wget --no-clobber <URL>` | `goget --url <URL> --no-clobber` | Skip existing files |
| `wget --timestamping <URL>` | `goget --url <URL> --timestamping` | Time-stamp check |
| `wget --continue <URL>` | `goget --url <URL> --continue` | Continue partial |
| `wget -nc <URL>` | `goget --url <URL> --no-clobber` | No clobber |
| `wget -nd <URL>` | `goget --url <URL> --cut-dirs 999` | No directories |
| `wget --no-directories <URL>` | `goget --url <URL>` | Create dirs (default in goget) |
| `wget -E <URL>` | `goget --url <URL> --adjust-extension` | Adjust extension |

## Behavior Differences

### Redirects

| Tool | Default Behavior |
|---|---|
| **curl** | Does **not** follow redirects by default |
| **wget** | Follows redirects by default |
| **goget** | Follows redirects by default (use `--no-redirect` to disable) |

### Output Filenames

| Tool | Default Output |
|---|---|
| **curl** | stdout |
| **wget** | Auto-detected from URL |
| **goget** | Auto-detected from URL (use `--output -` for stdout) |

### Verbosity

| Tool | Default |
|---|---|
| **curl** | Silent (progress bar) |
| **wget** | Verbose (progress + status) |
| **goget** | Verbose (progress bar + status, use `--quiet` for silent) |

## Features Unique to goget

These features have no direct curl/wget equivalent:

| Feature | Flag |
|---|---|
| **IPv6-first connections** | Always on (disable with `--no-ipv4`) |
| **Smart timeout** | `--timeout 0` (auto-calculates from file size) |
| **9 protocols** | HTTP, FTP, SFTP, WebDAV, Gemini, Gopher, data:, file:// |
| **Quantum-safe checksums** | `--checksum-algo sha3-256`, `--checksum-algo sha3-512`, `--checksum-algo blake2b` |
| **Download queue** | `--queue`, `--queue-list`, `--queue-process` |
| **Scheduling** | `--schedule "0 2 * * *"` |
| **Post-download hooks** | `--on-complete "script.sh"` |
| **JSON progress** | `--json --no-progress` |
| **Metalink** | `--metalink`, `--metalink-file` |
| **HSTS cache** | `--hsts-file` (RFC 6797) |
| **Go library API** | `import "codeberg.org/petrbalvin/goget/pkg/api"` |
| **`--create-dirs` (default true)** | Auto-creates missing parent directories of target file |
| **SOCKS5 proxy** | `socks5://` (local DNS) and `socks5h://` (remote DNS) |
| **Shell completion** | `--completion bash`, `--completion zsh`, `--completion fish` |

## Script Migration Patterns

### CI/CD Download Script

```bash
# Before (wget)
wget -q -O data.zip https://example.com/data.zip && unzip data.zip

# After (goget)
goget --quiet --url https://example.com/data.zip --output data.zip && unzip data.zip
```

### API Request

```bash
# Before (curl)
curl -s -H "Authorization: Bearer $TOKEN" -o output.json https://api.example.com/data

# After (goget)
goget --quiet --header "Authorization: Bearer $TOKEN" --url https://api.example.com/data --output output.json
```

### Mirror Website

```bash
# Before (wget)
wget --mirror --convert-links --adjust-extension --page-requisites --no-parent https://example.com

# After (goget)
goget --url https://example.com --mirror
```

### Scheduled Download

```bash
# Before (cron + wget)
# crontab: 0 2 * * * wget -q -O /backup/daily.zip https://example.com/daily.zip

# After (goget with built-in scheduling)
goget --url https://example.com/daily.zip --output /backup/daily.zip --schedule "0 2 * * *"
```

### Multi-File Download with Checksums

```bash
# Before (curl + sha256sum)
curl -O https://example.com/file.zip
curl -O https://example.com/SHA256SUMS
sha256sum -c SHA256SUMS

# After (goget)
goget --url https://example.com/file.zip --checksum-file SHA256SUMS
```

## What's Missing

Features from curl/wget not yet available in goget:

| Feature | Status |
|---|---|
| **Bandwidth throttling per-domain** | Global rate limit only |
| **DNS-over-HTTPS** | Not yet implemented |
| **Short flags** (`-O`, `-o`, `-s`, `-v`) | Long flags only (`--output`, `--quiet`, `--verbose`) |
| **MIME type detection for local files** | Not implemented |
| **Brotli decompression** | gzip/deflate only |