{
  "markdown": "# FYI CLI\n\n**A multi-jurisdiction Freedom-of-Information (FOI) client for Alaveteli-based platforms** — track,\nsubmit, and archive official information requests across New Zealand, Australia, the UK, and any\nother [Alaveteli](https://alaveteli.org/) deployment (foi-repository, WhatDoTheyKnow, FragDenStaat, and\nmore), from a single privacy-focused CLI.\n\n[![PyPI version](https://badge.fury.io/py/fyi-cli.svg)](https://badge.fury.io/py/fyi-cli)\n[![Crates.io](https://img.shields.io/crates/v/fyi-cli.svg)](https://crates.io/crates/fyi-cli)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![CI](https://github.com/edithatogo/fyi-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/edithatogo/fyi-cli/actions/workflows/ci.yml)\n[![Codecov](https://codecov.io/gh/edithatogo/fyi-cli/branch/master/graph/badge.svg)](https://codecov.io/gh/edithatogo/fyi-cli)\n[![smithery badge](https://smithery.ai/badge/edithatogo/fyi-mcp)](https://smithery.ai/server/@edithatogo/fyi-mcp)\n[![Glama](https://glama.ai/mcp/servers/edithatogo/fyi-cli/badges/score.svg)](https://glama.ai/mcp/servers/edithatogo/fyi-cli)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.edithatogo%2Ffyi--mcp-blue)](https://registry.modelcontextprotocol.io/)\n\nThe project's core is a **Rust workspace** (`fyi-core`, `fyi-cli`, `fyi-mcp`); a legacy Python\npackage (`fyi_system`) remains available as a reference implementation but is no longer extended.\n\n### Where fyi-cli / fyi-mcp is listed\n\n| Registry / catalog | Package / server | Status | Link |\n|--------------------|------------------|--------|------|\n| **Official MCP Registry** | `io.github.edithatogo/fyi-mcp` @ `0.1.2` | Live | [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/) · [`server.json`](server.json) |\n| **OpenAI plugin directory (Codex)** | `fyi-mcp` plugin packet | Assets ready — external submission pending | [`packaging/ai-plugins/codex/`](packaging/ai-plugins/codex/) |\n| **Anthropic Claude Connectors** | `fyi-mcp` connector packet | Assets ready — hosted HTTPS deployment and external submission pending | [`packaging/ai-plugins/anthropic/`](packaging/ai-plugins/anthropic/) |\n| **Glama** | `edithatogo/fyi-cli` (`fyi-mcp`) | Live | [glama.ai/mcp/servers/edithatogo/fyi-cli](https://glama.ai/mcp/servers/edithatogo/fyi-cli) · [scores](https://glama.ai/mcp/servers/edithatogo/fyi-cli/score) |\n| **Smithery** | `edithatogo/fyi-mcp` | Live (score pending) | [smithery.ai/server/@edithatogo/fyi-mcp](https://smithery.ai/server/@edithatogo/fyi-mcp) |\n| **PyPI** | `fyi-cli` (legacy Python package) | Live | [pypi.org/project/fyi-cli](https://pypi.org/project/fyi-cli/) |\n| **Crates.io** | `fyi-cli` / workspace crates | Published / release flow | [crates.io/crates/fyi-cli](https://crates.io/crates/fyi-cli) |\n| **GitHub Releases** | CLI + MCPB assets | Live | [Releases](https://github.com/edithatogo/fyi-cli/releases) |\n| **Awesome-MCP-Servers** | Legal section entry | PR submitted | [PR #9693](https://github.com/punkpeye/awesome-mcp-servers/pull/9693) |\n| **GitHub curated MCP** (`github.com/mcp`) | — | Blocked external (manual onboarding) | Tracked in [#32](https://github.com/edithatogo/fyi-cli/issues/32) |\n\n**Draft / not yet submitted:** Scoop, WinGet, Homebrew, Chocolatey, GHCR multi-arch workflow, PulseMCP, mcp.so, Docker MCP Catalog, mcp-get, OpenTools, AUR, nixpkgs, Snap, Flatpak, asdf/mise, Debian/PPA, Fedora/COPR.\n\n`cargo-binstall` is already **assets-ready** and wired in-repo, but still depends on matching GitHub Release assets before it can be treated as a live distribution path. Codex and Anthropic packets are assets-ready but still require external submission.\n\nFull status matrix (including planned channels): [`docs/registry-distribution-matrix.md`](docs/registry-distribution-matrix.md).\n\n---\n\n## 🚀 Quick Start\n\n```bash\n# Install (Rust workspace, recommended)\ncargo install --path crates/fyi-cli\n# or: cargo install fyi-cli   (once published to crates.io)\n\n# Initialize\nfyi-cli init-db\n\n# Create your first request\nfyi-cli register-request ministry-of-justice \"OIA Request\" \"Request body...\" --status draft\n\n# Track and manage requests\nfyi-cli list-requests\n```\n\n**Full guide:** [QUICKSTART.md](QUICKSTART.md)\n\n---\n\n## ✨ Features\n\n- **🌐 Multi-Jurisdiction**: Works with any Alaveteli deployment — foi-repository (NZ), WhatDoTheyKnow\n  (UK), FragDenStaat (Germany), righttoknow.org.au (Australia), and more, with jurisdiction-aware\n  metadata and localization on the way\n- **🔒 Privacy-First**: All data stored locally, optional encryption, Tor support\n- **📊 Track Requests**: Monitor FOI/OIA requests from creation to completion\n- **🤖 Automated Monitoring**: Watch instances for updates automatically\n- **📈 Reports & Analytics**: Generate dashboards, attention reports, handover docs\n- **🔐 Secure Storage**: Encrypted credentials, OS keyring integration\n- **💻 CLI + MCP**: Command-line tool and an [MCP server](crates/fyi-mcp) for AI assistants\n- **📦 Export Options**: JSON, CSV, HTML export capabilities\n- **🗄️ Faithful Archiving**: WARC/WACZ capture of requests, correspondence, and attachments\n\n---\n\n## 📦 Installation\n\n**Full guide (Rust-first, all channels):** **[INSTALL.md](INSTALL.md)** · version **0.1.2** · homepage [github.com/edithatogo/fyi-cli](https://github.com/edithatogo/fyi-cli)\n\n| Path | Command / location | Notes |\n|------|--------------------|--------|\n| **Cargo (clone)** | `cargo install --path crates/fyi-cli` | Recommended |\n| **Cargo (crates.io)** | `cargo install fyi-cli` | When published |\n| **cargo-binstall** | `cargo binstall fyi-cli` | **assets-ready** — needs matching release assets |\n| **GitHub Releases** | [Releases](https://github.com/edithatogo/fyi-cli/releases) | Prebuilt CLI / MCPB; check asset names per tag |\n| **PyPI (legacy)** | `pip install fyi-cli` | Python `fyi_system`; not extended |\n| **MCP binary** | `cargo install --path crates/fyi-mcp` | Or MCPB from Releases |\n| **MCP registries** | Official / Glama / Smithery | **live** — see table above |\n| **Containers** | `ghcr.io/edithatogo/fyi-mcp` | **assets-ready** — [docs/containers.md](docs/containers.md) |\n| **Scoop, WinGet, Homebrew, Chocolatey, AUR, nix, Snap, Flatpak, Debian, Fedora, asdf, mise** | Drafts under [`packaging/`](packaging/) | **Not claimed live** — [docs/installation-package-managers.md](docs/installation-package-managers.md) |\n\n```bash\ngit clone https://github.com/edithatogo/fyi-cli.git\ncd fyi-cli\ncargo install --path crates/fyi-cli --locked\nfyi-cli --help\n```\n\nLive listings and draft status: **[Where fyi-cli / fyi-mcp is listed](#where-fyi-cli--fyi-mcp-is-listed)** · full matrix: [`docs/registry-distribution-matrix.md`](docs/registry-distribution-matrix.md) · MCP catalog checklist: [`packaging/mcp-catalogs/SUBMISSION_CHECKLIST.md`](packaging/mcp-catalogs/SUBMISSION_CHECKLIST.md).\n\n---\n\n## 📖 Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Docs site](https://edithatogo.github.io/fyi-cli/) | Full documentation (Astro + Starlight) |\n| [docs/cli-entrypoints-audit.md](docs/cli-entrypoints-audit.md) | Canonical cross-reference for Python CLI, Rust CLI, and Rust MCP surfaces |\n| [docs/upstream-relations.md](docs/upstream-relations.md) | Alaveteli/instance operator etiquette and outreach log |\n| [docs/registry-distribution-matrix.md](docs/registry-distribution-matrix.md) | MCP catalogs, package managers, containers status |\n| [docs/external-registry-followups.md](docs/external-registry-followups.md) | Smithery score + GitHub MCP onboarding playbook |\n| [docs/installation-package-managers.md](docs/installation-package-managers.md) | Draft package-manager install notes (Scoop, WinGet, brew, …) |\n| [docs/containers.md](docs/containers.md) | `fyi-mcp` container / GHCR |\n| [QUICKSTART.md](QUICKSTART.md) | 5-minute getting started guide |\n| [USER_GUIDE.md](USER_GUIDE.md) | Comprehensive user documentation |\n| [INSTALL.md](INSTALL.md) | Installation guide (Rust-first; all channels) |\n| [API_KEY_SETUP.md](API_KEY_SETUP.md) | How to get and configure API key |\n| [CONFIGURATION.md](CONFIGURATION.md) | Configuration reference |\n| [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | Troubleshooting guide |\n| [FAQ.md](FAQ.md) | Frequently asked questions |\n| [CHANGELOG.md](CHANGELOG.md) | Version history |\n| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute |\n| [CITATION.cff](CITATION.cff) | Citation metadata for releases |\n| [.zenodo.json](.zenodo.json) | Zenodo release metadata source |\n\n---\n\n## 📚 Citation and Zenodo\n\nRelease metadata is versioned in `CITATION.cff`, `.zenodo.json`, and\n`artifacts/release/zenodo-mirror-manifest.json`. DOI fields remain unset until the live Zenodo\nrecord is verified for the tagged release.\n\n---\n\n## 🛡️ Security\n\n### Reporting a Vulnerability\n\n**Please do NOT report security vulnerabilities through public GitHub issues.**\n\nUse GitHub's private vulnerability reporting:\nhttps://github.com/edithatogo/fyi-cli/security/advisories/new\n\n**Security Policy:** [SECURITY.md](.github/SECURITY.md)\n\n### Security Features\n\n- ✅ AES-256-GCM encryption for sensitive data\n- ✅ PBKDF2-HMAC-SHA256 key derivation\n- ✅ OS keyring integration for credential storage\n- ✅ Tamper-evident audit logging\n- ✅ Secure session management\n- ✅ Input validation and sanitization\n- ✅ Security headers (CSP, HSTS, X-Frame-Options)\n- ✅ Automated security scanning (CodeQL, pip-audit, bandit)\n\n---\n\n## 🧪 Testing\n\n```bash\n# Rust release checks used by this repository\ncargo +stable-x86_64-pc-windows-gnu fmt --all -- --check\ncargo +stable-x86_64-pc-windows-gnu clippy --workspace --all-targets --all-features -- -D warnings\ncargo +stable-x86_64-pc-windows-gnu test --workspace --all-features\n\n# Python legacy/support checks\n.\\.venv\\Scripts\\python.exe -m pytest tests/test_release_readiness.py\n\n# Opt-in live smoke test\nFYI_LIVE_SMOKE=1 .\\.venv\\Scripts\\python.exe -m pytest -m smoke tests/test_discovery_smoke.py\n```\n\n**Test Coverage:** Rust workspace checks are the release gate. Python support tests remain available for legacy docs and archive tooling.\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Quick Start for Contributors\n\n```bash\n# Fork and clone\ngit clone https://github.com/YOUR_USERNAME/fyi-cli.git\ncd fyi-cli\n\n# Build & test the Rust workspace\ncargo build --workspace --all-features\ncargo test --workspace --all-features\n\n# Make your changes, then submit a PR\ngit commit -m \"feat: Add awesome feature\"\ngit push origin feature/awesome-feature\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full development setup, including the legacy\nPython `fyi_system` package.\n\n### Code of Conduct\n\nPlease note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.\n\n---\n\n## 📊 Project Status\n\n### GitHub Projects\n\nThe project board for this repository is\n[fyi-cli Conductor Roadmap](https://github.com/users/edithatogo/projects/6).\nIt mirrors the local `.conductor/tracks.md` registry and tracks completed\nConductor work, release-readiness items, and external MCP registry follow-ups.\n\nThe umbrella\n[Rare Insights on Open Policy from Aotearoa](https://github.com/users/edithatogo/projects/4)\nproject is synchronized at the item level. GitHub Projects does not support\nnested projects, so synchronization is handled by\n[`scripts/sync_github_projects.py`](scripts/sync_github_projects.py) and the\nmanual/scheduled [`project-sync`](.github/workflows/project-sync.yml) workflow.\n\n```bash\n# Preview synchronization without changing either project\n.\\.venv\\Scripts\\python.exe scripts\\sync_github_projects.py --dry-run\n\n# Apply synchronization from fyi-cli project 6 into RIOPA project 4\n.\\.venv\\Scripts\\python.exe scripts\\sync_github_projects.py\n```\n\nThe workflow requires a repository secret named `PROJECT_SYNC_TOKEN` with\nGitHub Projects access for user-level ProjectsV2 writes. The sync is\nconservative: it adds missing `fyi-cli` issue/PR items to RIOPA, copies shared\nstatus values, sets the RIOPA mirror source to `other` unless a `fyi-cli` option\nexists, and never deletes umbrella-board items.\n\n### Project Status\n\nThis project is actively evolving from an NZ-only tool into a multi-jurisdiction FOI/Alaveteli\nplatform built on the Rust workspace. Current work is tracked as\n[Conductor](https://conductor.build) tracks under `.conductor/tracks.md`, mirrored to GitHub epic\nissues (#37-#46) and their sub-issues. See the project board below for live status, and\n[CHANGELOG.md](CHANGELOG.md) for released versions.\n\n---\n\n## 🔗 Compatible Platforms\n\nFYI CLI works with any Alaveteli-based platform. The embedded jurisdiction catalog currently\nincludes:\n\n| Platform | Region | URL |\n|----------|--------|-----|\n| **foi-repository** | New Zealand | foi-repository |\n| **RightToKnow** | Australia | https://www.righttoknow.org.au |\n| **WhatDoTheyKnow** | United Kingdom | https://www.whatdotheyknow.com |\n| **MyRightToKnow** | Ireland | https://www.myrighttoknow.org |\n| **Ma Da Da (CADA)** | France | https://www.madada.fr |\n| **Tu Derecho a Saber** | Spain | https://www.tuderechoasaber.es |\n| **FragDenStaat** | Germany | https://fragdenstaat.de |\n| **Alaveteli** | Any | Self-hosted instances |\n\nSee `.conductor/tracks/jurisdiction-*` for the rollout plan covering additional instances and\nnon-English localization.\n\n---\n\n## 📋 CLI Commands\n\n### Archive Discovery\n\nThe archive commands are read-only and do not require an API key.\n\n```bash\n# Import the official FYI authority list into the local SQLite database\nfyi import-authorities\n\n# Walk the public search feed for a date window and save discovered requests\nfyi discover --date-from 2024-01-01 --date-to 2024-02-01 \\\n  --checkpoint data/_state/discovery-2024-01.json \\\n  --output data/_state/discovered-2024-01.jsonl\n\n# Probe a numeric request ID range for gaps\nfyi discover --backfill-ids --id-from 1 --id-to 5000 \\\n  --output data/_state/backfill-1-5000.jsonl\n\n# Compare feed discovery against the ID backfill\nfyi discover-reconcile \\\n  --feed data/_state/discovered-2024-01.jsonl \\\n  --backfill data/_state/backfill-1-5000.jsonl \\\n  --output data/_state/discovery-reconciliation.json\n```\n\n## Read-only authority discovery\n\n`discover-bodies` keeps `--base-url` as the instance/capture URL. Use the\nseparate `--catalog-url` option only when the authority CSV is hosted at an\nexplicit alternate URL:\n\n```bash\nfyi discover-bodies --base-url https://www.righttoknow.org.au \\\n  --catalog-url https://catalog.example/au-authorities.csv \\\n  --rate-limit-name archive-discovery-au-rtk --format jsonl --output bodies.jsonl\n```\n\nWith `--format jsonl`, each output line contains only the stable downstream\ncontract fields `url_name`, `name`, and `tags[]`. The default JSON format also\nincludes retrieval provenance for audit records. Both modes are read-only,\nrobots-aware, and use the configured shared limiter.\n\nThe JSON output includes the effective catalog URL, whether the default or an\noverride was used, retrieval time, HTTP status, row count, and a SHA-256 of the\nraw CSV payload. The override is read-only and still uses the catalog host's\nrobots policy, contactable User-Agent, retry backoff, and shared rate limiter.\nTreat an override URL as trusted configuration: it can redirect discovery to a\ndifferent authority set and should be reviewed and recorded alongside archive\nprovenance.\n\nDiscovery uses a contactable User-Agent, checks `robots.txt`, and backs off on\ntransient `429`/`5xx` responses. Keep live runs polite: use small date windows,\nresume with checkpoints, and coordinate archive work with the ethics guidance in\nthe sibling `fyi-archive` repo at `docs/ethics-and-compliance.md`.\n\nThe Rust `fyi-core` network path is the primary resource-aware implementation:\nit parses `RateLimit-*`/`Retry-After`, adapts pacing, enforces request/bytes/time\nguardrails, persists load memory, caches safe GETs, and can emit secret-redacted\nJSONL traces. Python remains a deliberately compatible discovery/capture path\nand follows the same identity and retry etiquette.\n\nFor concurrent workers, point `discover` and `backfill` at the same SQLite\ndatabase with `--db`. That enables the shared cross-worker limiter, which\nreserves one aggregate request slot across processes and records both normal\nreservations and transient-failure backoff events. Inspect the current state\nwith `fyi rate-limit-status --db fyi_system.db`.\n\n### CLI and MCP surfaces\n\nThe full command and server cross-reference is maintained in [docs/cli-entrypoints-audit.md](docs/cli-entrypoints-audit.md). It covers the Python CLI entrypoints (`fyi`, `fyi-cli`, `fyi-system`), the Rust CLI binary (`fyi-cli`), and the Rust MCP server (`fyi-mcp`) with its published registry pages.\n\nOpt-in live smoke test:\n\n```bash\nFYI_LIVE_SMOKE=1 pytest -m smoke tests/test_discovery_smoke.py\n```\n\nThe AU RightToKnow smoke is bounded to one discovery page and at most five\nrequest captures. It writes only to temporary test directories and remains\ndisabled unless `FYI_LIVE_SMOKE=1` is explicitly set.\n\nIn the current live verification, RightToKnow returned HTTP 403 for the\nbounded JSON search request, so the smoke records an explicit external\navailability skip and does not attempt capture. This does not change default\noffline CI behavior or retry the denied request aggressively.\n\n### Faithful Archive Capture\n\n`fyi capture` stores the public request JSON, rendered HTML, and attachments as\nWARC records, deduplicates attachment bytes by SHA-256, and maintains a derived\nrequest view for downstream dataset tooling.\n\n```bash\nfyi capture 12345 \\\n  --data-dir data \\\n  --dist-dir dist \\\n  --max-bytes 500000000 \\\n  --max-runtime-minutes 30\n```\n\nCapture layout:\n\n```text\ndata/\n  warc/<runid>-<request>.warc.gz\n  attachments/<sha-prefix>/<sha256>\n  raw/requests/<authority>/<request_id>/\n    request.json\n    page.html\n    attachments.json\n    snapshot_meta.json\ndist/\n  site_snapshots/<YYYYMMDD>.wacz\n```\n\nEach daily WACZ is appendable: subsequent captures add another WARC segment under\n`archive/` and merge the resource metadata in `datapackage.json`. Replay tooling\nthat supports WACZ/WARC can open the package from `dist/site_snapshots/`; for\nlow-level inspection, unzip it and read the WARC segments with `warcio`.\n\n```bash\n# Database\nfyi init-db                    # Initialize database\nfyi config show                # Show configuration\n\n# Requests\nfyi register-request ...       # Create new request\nfyi list-requests              # List all requests\nfyi request-detail <id>        # View request details\nfyi set-status <id> <status>   # Update status\n\n# Submission\nfyi build-prefilled-url <id>   # Generate submission URL\n\n# Monitoring\nfyi ingest-feed <url>          # Ingest RSS/Atom feed\nfyi scheduler <url>            # Run continuous monitoring\nfyi discover                   # Discover public FYI requests\nfyi discover-reconcile         # Compare discovery JSONL outputs\n\n# Reports\nfyi dashboard --output ...     # Generate dashboard\nfyi attention-report           # Generate attention report\nfyi handover --output ...      # Generate handover document\n\n# Export\nfyi export-requests            # Export all requests\nfyi export-bundle <id>         # Export request bundle\n\n# Security\nfyi privacy-audit              # Privacy compliance check\nfyi health-check               # System health verification\n```\n\n**Full CLI reference:** See `fyi --help` or [USER_GUIDE.md](USER_GUIDE.md)\n\n---\n\n## 🏗️ Architecture\n\n```\n┌───────────────────────────────────────────────────────────────┐\n│                         fyi-cli workspace                      │\n├───────────────────┬───────────────────────┬───────────────────┤\n│   fyi-cli (bin)   │   fyi-mcp (MCP server) │  legacy fyi_system │\n│  CLI commands,     │  JSON-RPC over stdio,   │  (Python, reference │\n│  TUI dashboard      │  tools for AI assistants│  implementation)   │\n├───────────────────┴───────────────────────┴───────────────────┤\n│                          fyi-core (lib)                         │\n│   Alaveteli API client · Tor client · encryption/keyring ·       │\n│   sync engine · jurisdiction/instance registry (in progress)     │\n├─────────────────────────────────────────────────────────────────┤\n│                        SQLite database                          │\n│      (requests, correspondence, authorities, sync_metadata)     │\n├─────────────────────────────────────────────────────────────────┤\n│      Alaveteli instances: foi-repository · WhatDoTheyKnow ·      │\n│      FragDenStaat · righttoknow.org.au · any self-hosted deploy  │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## 📜 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🙏 Acknowledgments\n\n- Built on the [Alaveteli](https://alaveteli.org/) platform by mySociety\n- Inspired by the transparency work of foi-repository\n- Uses [cryptography](https://cryptography.io/) for encryption\n\n---\n\n## 📞 Support\n\n- **Documentation:** https://edithatogo.github.io/fyi-cli/\n- **Issues:** https://github.com/edithatogo/fyi-cli/issues\n- **Discussions:** https://github.com/edithatogo/fyi-cli/discussions\n\n---\n\n**Made with ❤️ for transparency and privacy**\n",
  "bytes": 21320,
  "sha": "94b64fba2da1c150da91721a486a461c78cc08722f768dd931972c31e22644ac",
  "repo_slug": "edithatogo/fyi-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_edithatogo_fyi_mcp_6407609c/readme"
}