Legacy Camply CLI inventory
Audited: 2026-11-08. Baseline: juftin/camply v0.34.4, the latest published release observed during this audit. “v1” means the legacy product generation; the upstream release is not tagged v1.0. Runtime behavior below is a static source audit, supported by upstream tests, not a claim that old endpoints still work. Replacement ideas record the design at audit time; the specification and CLI guide define the implemented initial scope.
Implementation scope notice
This file preserves the complete historical baseline. Its replacement ideas describe possible future work, not the initial implementation scope. The specification's scope registry governs: D01–D13 are TODOs and must not be implemented yet. That includes site listing/selection, full notification/campground parity, YAML, permits/non-camping inventory, equipment, TUI, Rich-click, configure, legacy mode compatibility, first-batch flags and offline history.
The intended new default is search forever; run-mode design is deferred for brainstorming. Statements below about legacy one-pass defaults, YAML modes, 5/20 notification caps, lifetime suppression or proposed state migration document the old behavior or earlier replacement ideas. They do not select those behaviors for the initial CLI. Initial CLI output is console-only: Pushover, all other external delivery, --notifications, credential migration and test-notifications are deferred under D03. Existing server/web notification behavior remains unchanged. General permits are a future requested feature, not established legacy support.
Evidence
All upstream links are pinned to the baseline tag. When prose and source disagree, executable source takes precedence.
- Command definitions and option wiring — eight core commands, root flags, optional Trogon command.
- CLI guide and provider guide — user workflows; some prose is stale.
- Search engine and defaults — run modes, weekdays, consecutive stays, state, notifications.
- Recreation.gov search, GoingToCamp search, Yellowstone search — provider-specific behavior.
- Provider registry, GoingToCamp IDs, API configuration.
- YAML schema, YAML loader, date/day helpers, data models.
- Notification registry/fan-out, notification configuration, configuration wizard, file fields, logging.
- CLI tests, particularly ticket/timed-entry cases, and YAML fixtures.
Command inventory and replacement map
IDs in this document are coverage identifiers for the spec and future contract tests. “Gap” means the current repository does not expose the complete required public capability, even if private provider code already obtains some data.
| ID | Legacy surface and behavior | Replacement and present gap |
|---|---|---|
| C01 | camply, --help, per-command help, --version; python -m camply also invokes the old CLI. Rich help and a welcome/exit banner. | Preserve familiar commands and readable help; preserve current python -m camply.cli; add the legacy module entrypoint. Exact colors/banners are not contractual. |
| C02 | Root and relevant subcommand --provider; case-insensitive names; CAMPLY_PROVIDER; default RecreationDotGov. Command selection overrides root selection. | Alias registry maps legacy names to current identities; report availability/capabilities. Keep ID handling provider-scoped and string-based. |
| C03 | Root and most commands --debug/--no-debug; root debug takes precedence when explicitly supplied. Rich tracebacks can show locals. CAMPLY_LOG_HANDLER=rich/python, LOG_LEVEL. | Preserve switches and legacy logging environment names; use structlog with readable terminal/plain output and secret redaction, including debug. |
| C04 | providers [--debug/--no-debug] lists registered search providers and descriptions. | Show usable providers, legacy aliases and explicitly unavailable compatibility entries with reasons; no database/network required. |
| C05 | recreation-areas --search TEXT --state CODE [--provider ...] [--debug/--no-debug] finds parks/areas and IDs. Yellowstone is a fixed area; GoingToCamp lists deployments. State-only searches are rejected for these two providers. | Use BaseProvider.search(entity_type="recreation_area") for native providers. Legacy GoingToCamp needs a deployment facade. New supported state filtering is an extension; no fabricated areas for providers without them. |
| C06 | campgrounds --search TEXT --state CODE --rec-area ID --campground ID --campsite ID with repeatable IDs, provider/debug. Most providers require at least one selector; Yellowstone and GoingToCamp permit browse. Site IDs can resolve parent facilities. | Use direct upstream search plus explicit ID/parent resolution capabilities. Feature 025 covers text/state/single-parent discovery, not site-to-parent or exact-ID lookups. Preserve selector validation for legacy aliases. |
| C07 | list-campsites --campground ID --rec-area ID (repeatable), provider/debug. Requires a parent selector. Lists names and IDs, not availability. Internally constructs a tomorrow/next-day window; GoingToCamp and Yellowstone explicitly disallow it. | Add date-independent public site-catalog capability. Distinguish unsupported from empty; later support on more providers is additive. |
| C08 | equipment-types --rec-area ID (repeatable), provider. Recreation.gov returns Tent/RV/Trailer/Vehicle; GoingToCamp requires an area and uses only the first supplied value. Other providers warn and exit successfully. | Public equipment capability, with deployment/park scope and lengths/units. Reject ambiguous multiple contexts rather than silently taking the first. |
| C09 | campsites with every option in the next table, provider/debug. Finds availability and logs grouped dates, areas, facilities, counts and booking links. | Translate options into one typed request and invoke shared async providers/filtering through a local runner. No account, API, catalog import, or running web app required. |
| C10 | configure [--debug/--no-debug] interactively writes dotenv-style ~/.camply; blank answers use defaults; existing-file overwrite and final write receive confirmations. | Read existing configuration; edit/write atomically with masked secrets and restrictive permissions. Preserve unrelated fields and never overwrite without explicit consent. |
| C11 | test-notifications --notifications NAME (required, repeatable), debug. Sends one sample campsite through selected channels plus console logging. | Reuse delivery adapters and show per-channel success/failure. Never require a scan or real availability; no test sends during help/config parsing. |
| C12 | tui exists only when optional Trogon is importable (camply[tui]); generated form builds/runs normal CLI commands. | Optional tui extra using the same command schema; preview equivalent command, validate and execute through the same runner. Missing extra gives installation guidance. |
Availability options and semantics
| ID | Option(s) | Legacy behavior | Proposed replacement |
|---|---|---|---|
| S01 | --rec-area ID, --campground ID, --campsite ID | Each repeatable. Recreation.gov selects sites over campgrounds over areas. Other providers can require both parent and site; GoingToCamp requires exactly one deployment area. | Resolve to unique provider/campground/site targets, preserve provider-specific precedence and required context. Do not union ignored Recreation.gov parents. |
| S02 | --start-date YYYY-MM-DD, --end-date YYYY-MM-DD | Repeatable, paired by position with equal counts; arrival inclusive, checkout exclusive. Overlapping windows union nights. Past starts clamp to local today; past end fails. | Preserve pairing/exclusive checkout, overlap deduplication and past-start clamp with warning. Use documented UTC day cutoff consistent with current engine. No future nights is a validation error. |
| S03 | --day NAME | Repeatable, full English names or MON/TUE/TUES/WED/THU/THUR/THURS/FRI/SAT/SUN, advertised case-insensitive. | Normalize names before lookup; restrict eligible nights before stay matching. |
| S04 | --weekends | Adds Friday and Saturday to selected weekdays; with --day it is a union. With no day restrictions, search all seven days. | Preserve union semantics, including Sunday + weekends = Fri/Sat/Sun. |
| S05 | --nights INTEGER | Default 1. Builds sliding exact-length consecutive stays at the same site. If requested nights exceed the longest eligible run, silently reduces the request with a warning. | Preserve sliding exact-length stay output; reject impossible lengths instead of reducing them. Current web minimum-stay blocks need a separate CLI presentation step. |
| S06 | No run-mode flag | One live search; logs results; no external notification. | Preserve. Empty successful search exits 0 and reports no matches. |
| S07 | --continuous | Poll until availability is found, then exit. | Foreground async loop with immediate first check, bounded retries and cancellation. |
| S08 | --search-forever | Implies continuous; continues after matches; suppresses already-seen identical availability across the run, even after disappearance/reappearance. | Preserve CLI lifetime suppression; keep web new-opening policy unchanged. Stop when all search nights expire. |
| S09 | --search-once | One cycle with continuous-mode notifications, suitable for cron; incompatible with explicit --continuous or --search-forever on flag path. | Preserve single notification cycle and validate conflicts in both flag and YAML paths. |
| S10 | --polling-interval INTEGER | Minutes; implies continuous, default 10, values below 5 clamp to 5. Engine also has POLLING_INTERVAL fallback, but CLI supplies 10 when omitted, so that environment fallback is not generally reached. Yellowstone has a separate 45-minute minimum configuration. | Preserve default/minimum with visible effective interval; honor stricter provider pacing and Retry-After. Do not claim POLLING_INTERVAL is a reliable legacy CLI option. |
| S11 | --notifications NAME | Repeatable, case-insensitive; any explicit channel, including silent, implies continuous. Default silent. Console is always included alongside external channels. | Fan out through common notification interfaces. Selected unsupported/misconfigured channels fail before provider IO. |
| S12 | --notify-first-try | Implies continuous. Normally the first immediate batch is capped at 5 external campsite notifications; warns about excess. Flag bypasses that cap but general batch limiting still caps at 20. Later retry/loop batches use 20. | Preserve 5/20 limits, deterministic selection and visible suppressed counts. Flag does not mean unlimited. |
| S13 | --equipment NAME LENGTH | Repeatable pairs; Recreation.gov matches any requested equipment type, case-insensitive, with per-type max length. Length 0 disables length restriction; CLI rounds numeric lengths and treats unparsable lengths as unrestricted. | Preserve OR matching and 0 sentinel; document provider units (feet for Recreation.gov). Reject invalid/negative lengths. Use typed capability data, not broad campsite type as a substitute. |
| S14 | --equipment-id ID | GoingToCamp deployment-specific equipment category; discovered with equipment-types. | Public provider filter/capability required; validate scope and availability before running. Never silently ignore it. |
| S15 | --yaml-config PATH, --yml-config PATH | Reads a search file instead of search options; see schema below. | Keep both spellings and file precedence, with diagnostics for ignored explicit flags. |
| S16 | --offline-search, --offline-search-path PATH | Persists seen results, reloads before searching; explicit path enables it. Default ./camply_campsites.json; JSON or .pkl/.pickle. Does not eliminate network requests. Writes when newly found results increase the set. | Preserve JSON history/cron suppression with validated import and atomic writes. Reject pickle with export guidance; do not deserialize executable state. Keep historical records distinct from live availability. |
Source nuances: Click advertises case-insensitive weekdays, but the old flag-path dictionary lookup uses the original token and can fail on lowercase input. End-date prose in the old guide sometimes disagrees with the exclusive implementation. These are defects/documentation errors, not desired compatibility.
YAML contract
The old file has these exact keys, from YamlSearchFile:
| Keys | Shape and default |
|---|---|
provider | Case-insensitive legacy name; RecreationDotGov. |
recreation_area, campgrounds, campsites | Scalar string/integer or list; null when absent. |
start_date, end_date | Required date scalar or date list, paired in order. |
days | List of weekday names/abbreviations; null. |
weekends, nights | Boolean false; integer 1. |
continuous, polling_interval | True, 10 minutes. Different continuous default from flag-only searches. |
notifications | Scalar or list of names; silent. |
search_forever, search_once, notify_first_try | Boolean false. |
equipment | One [name, length] pair or list of pairs; null. |
offline_search, offline_search_path | False; null (runner chooses default JSON path). |
The loader expands ${VAR_NAME} in scalar values; missing variables are replaced with the variable's bare name. YAML supplies provider/search arguments wholesale: explicit search flags, including command-level provider, are bypassed. Because the schema supplies a provider default, that also overrides a root provider for omitted YAML provider. equipment_id is absent from the old schema/translation. Flag-path implicit-continuous logic is not reused by YAML, so combining continuous: false with notification/forever fields is inconsistent.
Replacement: retain listed keys, defaults, scalar/list normalization and file authority. Expand environment references consistently, but fail on missing variables. Reject unknown keys and inconsistent run modes with field paths; add equipment_id as an extension. For YAML, search_once: true overrides the implicit default continuous: true; explicitly contradictory true values fail. Apply implicit continuous triggers when YAML does not explicitly choose continuous: false; with explicit false, reject contradictory notification/loop requests. Document these repairs in migration notes.
Provider coverage
The old registry has 19 selectable names. Shared API families do not imply interchangeable IDs.
| Legacy name(s) | Current implementation | Replacement scope |
|---|---|---|
RecreationDotGov | RecreationGovProvider | Preserve alias; direct discovery and availability exist. Exact/site/area target expansion and equipment/site catalog need public contracts. |
ReserveCalifornia, ArizonaStateParks, FloridaStateParks, MinnesotaStateParks, MissouriStateParks, OhioStateParks, VirginiaStateParks, NorthernTerritory, FairfaxCountyParks, OregonMetro | Corresponding UseDirect provider classes | Reuse modern async adapters; expose required capabilities and validate old IDs against current catalogs. Endpoint migrations do not guarantee ID stability. |
AlabamaStateParks, MaricopaCountyParks | Not registered; discovery blockers already tracked in feature 007 | Keep recognized names with explicit unavailable status until verified replacement endpoints/adapters exist. No fallback to unrelated providers. |
Yellowstone | Not registered | Dedicated verified Xanterra adapter needed. Old facility IDs: YLYB:RV Bridge Bay, YLYC:RV Canyon, YLYF:RV Fishing Bridge, YLYG:RV Grant, YLYM:RV Madison. Defaults to all five; these are facility/room-type availability, not necessarily individually numbered sites. ReserveAmerica is not an equivalent alias. |
GoingToCamp | Only WashingtonStateParksProvider registered | Legacy deployment facade plus remaining deployments. --rec-area means a deployment selector here, not current park identity. Washington legacy selector 3 must map to provider 12 and then expand parks, never to native park 3. |
RecreationDotGovTicket, RecreationDotGovTimedEntry, RecreationDotGovDailyTicket, RecreationDotGovDailyTimedEntry | Not registered | Dedicated non-camping inventory contracts/adapters. Facility/tour IDs reuse campground/site CLI terminology. Daily variants support slot time (HHMM) and ticket quantity through equipment pairs, e.g. --equipment 1300 4; do not interpret these as vehicle lengths. |
| No legacy equivalent | ReserveAmericaProvider | Additive CLI support through existing registry; opaque contract-scoped IDs must survive unchanged. Not evidence of missing legacy parity being complete. |
GoingToCamp deployment selectors in source (not current API park IDs):
| Legacy ID | Deployment | Current coverage |
|---|---|---|
| 1 | Long Point Region | Missing |
| 2 | St. Clair Region | Missing |
| 3 | Washington State Parks | Adapter exists; compatibility facade missing |
| 4 | Maitland Valley | Missing |
| 5 | Saugeen Valley | Missing |
| 6 | Tacoma Power Parks | Missing |
| 7 | Wisconsin State Parks | Missing |
| 8 | Algonquin Highlands | Missing |
| 9 | Maryland State Parks | Missing |
| 10 | Gatineau Park | Missing |
| 11 | Newfoundland & Labrador Provincial Parks | Missing |
| 12 | BC Parks | Missing |
| 13 | Nova Scotia Parks | Missing |
| 14 | Parks Canada | Missing |
| 15 | Manitoba Parks | Missing |
| 16 | New Brunswick Provincial Parks | Missing |
| 17 | Michigan State Parks | Missing |
Source uses parcsnbparks.ca for New Brunswick while the old provider guide lists a different domain. Verify live endpoints during provider implementation; neither this inventory nor copied historical tests establishes current service health.
Notification and environment compatibility
| Channel | Legacy environment inputs | Replacement |
|---|---|---|
silent | None | Always show console results; no external delivery. |
pushover | PUSHOVER_PUSH_USER, optional PUSHOVER_PUSH_TOKEN | Adapt existing async Pushover provider; map user/app token explicitly. Current server uses PUSHOVER_APP_TOKEN plus per-user keys. No copied legacy embedded token. |
email | EMAIL_TO_ADDRESS, EMAIL_USERNAME, EMAIL_PASSWORD; optional EMAIL_FROM_ADDRESS, EMAIL_SUBJECT_LINE, EMAIL_SMTP_SERVER, EMAIL_SMTP_PORT | SMTP adapter or verified Apprise equivalent. Legacy defaults: camply@juftin.com, Camply Notification, smtp.gmail.com, 465. Clearly document any changed sender default. |
ntfy | NTFY_TOPIC | ntfy adapter/verified Apprise mapping; old default service ntfy.sh. |
apprise | APPRISE_URL | Optional Apprise integration with equivalent URL interpretation. |
pushbullet | PUSHBULLET_API_TOKEN | Adapter/verified Apprise mapping. |
slack | SLACK_WEBHOOK | Webhook adapter/verified Apprise mapping. |
telegram | TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID | Adapter/verified Apprise mapping. |
twilio | TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_SOURCE_NUMBER, comma-separated TWILIO_DEST_NUMBERS | Preserve multi-recipient SMS fan-out and report recipient failures without exposing numbers. |
webhook | WEBHOOK_URL, JSON WEBHOOK_HEADERS | Preserve POST payload contract (campsites, timestamp, legacy campsite fields) through a compatibility serializer; test auth-header handling and redaction. |
The notification layer loads ~/.camply without overriding process environment. The wizard covers common fields, not every optional setting above. RIDB_API_KEY overrides legacy RIDB discovery credentials; new public discovery may not need it. Preserve explicit credentials only where the replacement actually consumes them, and explain obsolete settings. Never carry embedded upstream service credentials forward.
MultiNotifier always includes silent logging, even when only external channels are requested. It supports terminal “last gasp” error messages after search attempts, except where a channel disables that behavior. Replace with one sanitized terminal failure event per selected capable channel; failure to send must not obscure the original error. Legacy sequential fan-out can abort on one channel's exception; replacement isolates channel outcomes.
Intentional differences and exclusions
- Stable user outcomes and commands matter; byte-identical Rich layout, unordered set result order, tracebacks containing locals and arbitrary internal Python import compatibility do not.
- Replace pickle state with JSON; reject unknown YAML fields, missing environment references, invalid equipment lengths, ambiguous equipment context, impossible stays and invalid windows before requests.
- Retain lifetime seen-result suppression for CLI, independently of web alerts that can notify after an opening disappears and returns. Do not import a legacy history file into a live result cache.
- Retain checkout-exclusive dates; align expiration with current UTC rules and document timezone differences from legacy local-today behavior.
- Legacy installation (
camplyon PyPI, pipx, Docker, cron) is part of migration documentation. This repository currently publishescamply-web; do not take over the old PyPI name orghcr.io/juftin/camplyas part of parity implementation. - No auto-booking, checkout, payment, hosted-account requirement, remote API CLI, shell-completion guarantee, or new JSON-output CLI contract is implied by the legacy surface.