- Python 100%
b2561da7d1
- Compress the 15 phase plans plus 4 Phase 2 companion artifacts (19 files total) that lived directly under docs/plans/ into a single docs/plans-archive.zip, then remove the loose .md files from the working tree. They remain fully intact and readable by extracting the archive, and are also fully recoverable via git history; nothing is lost, they are just no longer individually present as plain text files that a glob/grep-based AI code reviewer would stumble onto and try to ingest. - Add docs/plans/README.md explaining the archive, where to find it, and pointing to docs/ARCHITECTURE.md as the actual day-to-day reference. - docs/plans/addenda/ (the three standalone deep-dive files extracted earlier) is deliberately left untouched and readable, since those are meant to stay directly accessible. - Update docs/ARCHITECTURE.md and the three addenda files so every in-text reference to one of the 19 archived filenames is now plain (non-linked) text with a pointer to docs/plans-archive.zip / docs/plans/README.md, instead of a now-broken Markdown link. - Update README.md's "Design and implementation history" section to describe the new archive layout. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> |
||
|---|---|---|
| .github | ||
| docs | ||
| src/getmyfs | ||
| tests | ||
| .env.example | ||
| .gitignore | ||
| .python-version | ||
| pyproject.toml | ||
| README.md | ||
| uv.lock | ||
GetMyFS
GetMyFS is a FamilySearch CLI for authenticated tree traversal that fetches a bounded ancestor/descendant graph for a seed person and persists both raw API payloads and query-friendly projections into local SQLite.
Requirements
- Python 3.12+
- uv
- A FamilySearch developer app key (
FS_CLIENT_ID) - A redirect URI registered for that app key (
FS_REDIRECT_URI)
Setup
uv sync
cp .env.example .env
Then edit .env and provide at least:
FS_CLIENT_IDFS_REDIRECT_URI
For legacy mode only (--legacy-auth), also set:
FS_USERNAMEFS_PASSWORD
CLI usage
Authenticate with strict PKCE mode:
uv run getmyfs login
Authenticate with legacy mode:
uv run getmyfs login --legacy-auth
Show auth status:
uv run getmyfs auth status --json
Fetch from a seed person:
uv run getmyfs fetch -i GM4H-3RC -a 1 -d 1 --json
Logout and clear stored token:
uv run getmyfs logout
Run uv run getmyfs --help and uv run getmyfs fetch --help for full argument details.
Data and logs
- Default database path:
data/getmyfs.sqlite - Default run logs:
data/logs/*.log
Optional overrides:
FS_DB(orfetch --db) for database locationfetch --logfilefor explicit log file pathFS_LOGS_KEPT/fetch --logs-keptfor log retention
Legacy auth caveat
--legacy-auth is a compatibility fallback and prints a warning banner when used. Prefer strict PKCE mode whenever your app key supports loopback redirect registration.
Architecture
For a reviewer-oriented map of the current system design (layers, auth, throttling, data model, sync engine, CLI, testing, security posture, and known deviations), see docs/ARCHITECTURE.md.
Design and implementation history
The detailed, phase-by-phase design/decision plans that produced this project are archived, unmodified, in docs/plans-archive.zip — kept out of the working tree on purpose so casual browsing and AI code-review tools don't try to ingest all 19 files. See docs/plans/README.md for details, and docs/plans/addenda/ for a few standalone deep-dive topics extracted from them (those remain plain, readable files). docs/ARCHITECTURE.md summarizes all of this for day-to-day use; consult the archive directly only when you need the full historical rationale.