sync
Downloads Goodreads API data into a local SQLite database for instant full-text search, supporting resumable incremental updates and full refreshes.
Instructions
Sync data from the API into a local SQLite database. Supports resumable incremental sync (only fetches new data since last sync) and full resync. Once synced, use the 'search' command for instant full-text search.
Exit codes & warnings: Resources the API denies access to (HTTP 403, or HTTP 400 with an access-policy body) are reported as warnings rather than failing the run. In --json mode each is emitted as a {"event":"sync_warning",...} line carrying status, reason, and message fields, and a final {"event":"sync_summary",...} aggregates the run.
Exit 0 when at least one resource synced and no resource flagged in the spec as critical (x-critical: true) failed; non-critical failures emit {"event":"sync_warning","reason":"exit_policy_default_changed", ...} so callers can detect that a partial failure was tolerated. Pass --strict to exit non-zero on any per-resource failure. Exit is always non-zero when every selected resource failed, regardless of --strict.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| db | No | Database path (default: ~/.local/share/goodreads-cli/data.db) | |
| csv | No | Output as CSV (table and array responses) (default: false) | |
| yes | No | Skip confirmation prompts (for agents and scripts) (default: false) | |
| full | No | Full resync (ignore previous checkpoint) (default: false) | |
| json | No | Output as JSON (default: false) | |
| agent | No | Set all agent-friendly defaults (--json --compact --no-input --no-color --yes) (default: false) | |
| plain | No | Output as plain tab-separated text (default: false) | |
| quiet | No | Bare output, one value per line (default: false) | |
| since | No | Incremental sync duration (e.g. 7d, 24h, 1w, 30m) | |
| config | No | Config file path | |
| select | No | Comma-separated fields to include in output (e.g. --select id,name,status) | |
| strict | No | Exit non-zero on any per-resource failure (default: only critical failures or all-resource failure exit non-zero). (default: false) | |
| compact | No | Return only key fields (id, name, status, timestamps) for minimal token usage (default: false) | |
| deliver | No | Route output to a sink: stdout (default), file:<path>, webhook:<url> | |
| dry-run | No | Show request without sending (default: false) | |
| profile | No | Apply values from a saved profile (see 'goodreads profile list') | |
| timeout | No | Request timeout (default: 30s) | |
| no-cache | No | Bypass response cache (default: false) | |
| no-color | No | Disable colored output (default: false) | |
| no-input | No | Disable all interactive prompts (for CI/agents) (default: false) | |
| max-pages | No | Maximum pages to fetch per resource (0 = unlimited; cap-hit emits a sync_warning event) (default: 100) | |
| resources | No | Comma-separated resource types to sync | |
| idempotent | No | Treat already-existing create results as a successful no-op (default: false) | |
| rate-limit | No | Max requests per second (0 to disable) (default: 0) | |
| concurrency | No | Number of parallel sync workers (default: 4) | |
| data-source | No | Data source for read commands: auto (live with local fallback), live (API only), local (synced data only) (default: auto) | |
| latest-only | No | Refresh head of each resource only; clears resume cursor and caps pages at 1. Mutually exclusive with --since (--since wins). (default: false) | |
| human-friendly | No | Enable colored output and rich formatting (default: false) |