{
  "markdown": "# 🩸 Ferritin\n\n[![ci][ci-badge]][ci]\n[![codecov](https://codecov.io/gh/jbr/ferritin/graph/badge.svg?token=FDpsPBK9zl)](https://codecov.io/gh/jbr/ferritin)\n[![crates.io version badge][version-badge]][crate]\n\n[ci]: https://github.com/jbr/ferritin/actions?query=workflow%3ACI\n[ci-badge]: https://github.com/jbr/ferritin/workflows/CI/badge.svg\n[version-badge]: https://img.shields.io/crates/v/ferritin.svg?style=flat-square\n[crate]: https://crates.io/crates/ferritin\n\nA terminal-based Rust documentation viewer\n\nFerritin reads rustdoc JSON output to display Rust documentation directly in your terminal. It supports local workspace crates, standard library documentation, and crates from crates.io, with search functionality and modern terminal features including mouse support, syntax highlighting, and clickable links.\n\n## Features\n\n- **Interactive documentation browser** with keyboard and mouse navigation\n- **One-shot CLI** for quick documentation lookups in the terminal\n- **Search across crates** or within specific crates\n- **Works seamlessly across three contexts:**\n  - Local workspace crates (requires nightly toolchain)\n  - Standard library (requires `rust-docs-json` rustup component)\n  - Crates from crates.io (fetched from docs.rs on demand)\n- **Modern terminal UI** with features like italics, unicode box drawing, syntax highlighting, OSC8 hyperlinks, cursor changes in terminals that support it, and mouse hover previews\n- **Fast navigation** with history and breadcrumb trail\n\n## Installation\n\n### Prebuilt binary (recommended)\n\nPrebuilt binaries skip compilation and are available for x86_64/aarch64 macOS, x86_64 Linux,\nand x86_64 Windows.\n\nIf you have [cargo-binstall](https://github.com/cargo-bins/cargo-binstall), it reads the\nrelease metadata and installs the right binary for your platform:\n\n```bash\ncargo binstall ferritin\n```\n\nOtherwise, the installer scripts detect your platform, download the matching binary, and\nplace it in `~/.cargo/bin`:\n\n**macOS and Linux:**\n\n```bash\ncurl --proto '=https' --tlsv1.2 -LsSf https://github.com/jbr/ferritin/releases/download/ferritin-latest/ferritin-installer.sh | sh\n```\n\n**Windows (PowerShell):**\n\n```powershell\npowershell -c \"irm https://github.com/jbr/ferritin/releases/download/ferritin-latest/ferritin-installer.ps1 | iex\"\n```\n\nBoth of the above always install the most recent release. You can also pick a specific\nversion or download archives directly from the [releases page].\n\n[releases page]: https://github.com/jbr/ferritin/releases\n\n### From source\n\nTo build from source (or for a platform without a prebuilt binary):\n\n```bash\ncargo install ferritin\n```\n\n### Optional: Standard library documentation\n\nTo view documentation for `std`, `core`, and `alloc`:\n\n```bash\nrustup component add rust-docs-json\n```\n\n### For local workspace documentation\n\nLocal crate documentation requires a nightly toolchain:\n\n```bash\nrustup toolchain install nightly\n```\n\nNote: There is a relationship between ferritin's version and the nightly toolchain version. Ferritin\nsupports a range of recent rustdoc JSON format versions, and if your nightly generates a newer\nformat, ferritin will make a best effort at parsing it.\n\n## Usage\n\n### Interactive mode\n\nLaunch the interactive browser:\n\n```bash\nferritin -i\n```\n\nOnce running, use `h` or `?` to see available keybindings. Basic navigation:\n- `g` - go to an item by path (e.g., `std::vec::Vec`)\n- `s` - search (Tab to toggle between current crate and all crates)\n- `l` - list available crates\n- Arrow keys, j/k, or mouse to navigate\n- Click on links to follow them\n\n### CLI mode\n\nView documentation for a specific item:\n\n```bash\nferritin get std::vec::Vec\nferritin get serde::Serialize\n```\n\nSearch for items:\n\n```bash\nferritin search \"hash map\"\nferritin search --crate tokio \"spawn\"\n```\n\nList available crates in your workspace:\n\n```bash\nferritin list\n```\n\n### Output format\n\nFerritin auto-detects how to render: ANSI colors on a terminal, plain text when\npiped, and a compact markdown-flavored format under a coding agent. Override it\nwith `--format <tty|plain|agent|json>`. `--format json` emits a structured\nrepresentation — of the resolved item for `get`, or of the results for\n`search`/`list` — for scripting and programmatic consumers:\n\n```bash\nferritin get std::vec::Vec --format json\n```\n\n(The JSON shape is still settling as the library API evolves; a published JSON\nSchema is planned.)\n\n## Caching and Storage\n\nFerritin keeps its caches under a single directory — `$FERRITIN_HOME` if set,\nelse `$XDG_CACHE_HOME/ferritin`, else `~/.cache/ferritin`. Everything in it is\nreconstructible (fetched or derived), so it is always safe to delete:\n\n- **Crates.io documentation**: raw rustdoc JSON at\n  `docs/{crate}/{version}/{format-version}.json`, with derived binary caches\n  beside it (an rkyv archive for fast partial loads, and a `.index` file\n  generated lazily on first search)\n- **crates.io metadata**: the crate-names artifacts (`crate-names/`) used for\n  version resolution and typeahead, and per-crate version lookups\n  (`crates-io-versions/`)\n- **Standard library search indices**: written to\n  `{rustc sysroot}/share/doc/rust/json/` if available\n- **Local workspace documentation**: built into the workspace's own\n  `target/doc/`, not the shared cache\n\nEarlier versions cached under `$CARGO_HOME/rustdoc-json`; a cache found there\nis migrated automatically on first run.\n\n## Environment Variables\n\n| Variable | Meaning |\n| --- | --- |\n| `FERRITIN_HOME` | Cache root override (see above) |\n| `FERRITIN_THEME` | Default color theme (equivalent to `--theme`) |\n| `FERRITIN_CRATE_NAMES_URL`, `FERRITIN_CRATE_DESCRIPTIONS_URL` | Override where the crate-names artifacts are fetched from (e.g. a mirror) |\n\n`ferritin serve` (the opt-in `serve`/`acme` features; not present in\ndistributed binaries) is configured 12-factor style:\n\n| Variable | Meaning |\n| --- | --- |\n| `HOST`, `PORT` | Bind address (`::` binds dual-stack) |\n| `FERRITIN_CACHE_BYTES` | In-memory crate-cache weight cap |\n| `FERRITIN_RSS_HIGH_WATER_BYTES` | RSS guard threshold (Linux only): shed cache weight when anonymous RSS exceeds it |\n| `FERRITIN_RATELIMIT` | Per-client `/api` requests per minute |\n| `FERRITIN_ACME_DOMAIN` | Activates automatic HTTPS via Let's Encrypt for this domain |\n| `FERRITIN_ACME_CACHE_DIR` | Required with ACME: persists the account key and certificates |\n| `FERRITIN_ACME_CONTACT` | Optional ACME contact email |\n| `FERRITIN_ACME_PRODUCTION` | Use the Let's Encrypt production directory (default: staging) |\n\nDevelopment-only knobs (not part of the stable interface): `FERRITIN_TEST_MODE`\n(normalized snapshot-test output), `FERRITIN_REINDEX` (rebuild search indexes\nin memory, bypassing the disk cache), and the search-scoring probes\n`FERRITIN_NAME_WEIGHT`, `FERRITIN_ANCESTOR_WEIGHTS`, and\n`FERRITIN_NAME_PREFIX_COUNT`.\n\n## Current Status\n\nFerritin is at version 0.x and actively used by the author as a primary documentation interface. It's ready for general use, though the output format should be considered unstable and may change between versions.\n\n**If you're scripting against ferritin's output**, be aware that the text format may change. Pin to a specific version or be prepared to update your scripts.\n\n## Platform Support\n\nFerritin is developed primarily on Unix-like systems and is also tested on Windows, where both the CLI and interactive TUI work (prebuilt x86_64 Windows binaries are provided). If you encounter issues on any platform, please open an issue or pull request.\n\n## Related Projects\n\nFerritin was originally developed to support the [rustdoc-mcp MCP server](./rustdoc-mcp/README.md), which provides Rust documentation access for Claude Code and other MCP clients.\n\n\n## License\n\n<sup>\nLicensed under either of <a href=\"LICENSE-APACHE\">Apache License, Version\n2.0</a> or <a href=\"LICENSE-MIT\">MIT license</a> at your option.\n</sup>\n\n---\n\n<sub>\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in this crate by you, as defined in the Apache-2.0 license, shall\nbe dual licensed as above, without any additional terms or conditions.\n</sub>\n",
  "bytes": 8118,
  "sha": "5098497ce3f580506c3085be717dafc03cc9d3eadbe5f50414a4ebbc52469f65",
  "repo_slug": "jbr/ferritin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_rs_ferritin_rustdoc_4a4cf58e/readme"
}