docsrs-cli
Fetch crates.io and docs.rs docs in one shot for agents.
What is it
- One-shot stdin/stdout CLI for crates.io search and docs.rs item pages
- Lifecycle is always BORN, EXECUTE, FINALIZE, DIE
- No daemon, no sticky session, no product telemetry
- JSON auto-selects when stdout is not a TTY
- Public HTTP only against an allowlist of docs hosts
The Pain
- Agents scrape HTML by hand and burn tokens on noise
- Browser tabs and curl pipelines do not form a stable contract
- Sticky MCP servers keep sockets open between turns
Why
- Stable JSON envelopes on stdout for every command
- Markdown human path when you force
--format markdown - XDG disk cache with TTL and soft budget
- Polite rate limits, full-jitter HTTP retry, cancel-safe shutdown
- Exit codes agents can branch on without parsing prose
Superpowers
search-cratesagainst crates.io with pagination and sortreadmefor the docs.rs crate overview docblockget-itemfor typed rustdoc pages by kind and pathsearch-in-crateover the crateall.htmlindex- stdlib fetch for
std,core, andallocvia doc.rust-lang.org commands,schema,doctor,versionfor agent discoverycacheandconfigfor XDG maintenance without secrets
Quick Start
Installation
- From crates.io:
cargo install docsrs-cli --locked - From a local checkout:
cargo install --path . --locked - MSRV is Rust 1.88
- No Cargo feature flags exist in this package
Usage
- Pass
--jsonor pipe stdout for the agent envelope - Force human output with
--format markdownor--format text - Plan URLs without network using
--dry-run - Raise wall-clock budget with
--timeout <seconds> - Disable disk cache with
--no-cache
Commands
- Full surface has 11 top-level commands
search-crates <query> [--page N] [--per-page N] [--sort KIND]— crates.io search--sortacceptsrelevance,downloads,recent-downloads,recent-updates,new,alphabeticalreadme <crate> [--crate-version V]— docs.rs crate overview docblockget-item <crate> <item_type> <item_path> [--crate-version V]— typed rustdoc itemitem_typeacceptsmodule,struct,trait,enum,union,fn/function,type,const/constant,static,macro,attr/attribute,deriveitem_pathaccepts::or/separators and optional crate prefixsearch-in-crate <crate> [query] [--crate-version V] [--item-type K] [--limit N]—all.htmlsymbol search- Empty
querylists classified items up to--limit version— binary versiondoctor— local TLS, paths, concurrency, and retry readinesscommands— full command tree for agentsschema --cmd <name>— JSON Schema for a command payload- Schema targets:
search-crates,readme,get-item,search-in-crate,version,doctor,commands,cache,config completions <shell>—bash,zsh,fish,elvish,power-shell(powershellalias)- Examples:
docsrs-cli completions bash,completions zsh,completions fish,completions elvish,completions power-shell,completions powershell cache stats— report entry count, bytes, and budgetcache clear— delete cached HTTP bodiesconfig path— print resolved config/cache dirs and winning layerconfig show— print effective runtime configurationconfig init [--force]— create defaultconfig.toml- Example overwrite:
docsrs-cli config init --force --json
Environment Variables
DOCSRS_CLI_HOME— sandbox root for config and cacheDOCSRS_CLI_CONFIG_DIR/DOCSRS_CLI_CACHE_DIR— path overridesDOCSRS_CLI_TIMEOUT_SECS— wall-clock timeoutDOCSRS_CLI_USER_AGENT/DOCSRS_CLI_CONTACT— identity headersDOCSRS_CLI_CACHE_TTL_SECS/DOCSRS_CLI_MAX_CACHE_BYTES/DOCSRS_CLI_NO_CACHEDOCSRS_CLI_MAX_BODY_BYTES/DOCSRS_CLI_MAX_OUTPUT_BYTES— hard capsDOCSRS_CLI_MAX_CONCURRENCY— CPU parse worker budget (0= auto)DOCSRS_CLI_MAX_RETRIES/DOCSRS_CLI_RETRY_BASE_MS/DOCSRS_CLI_RETRY_MAX_DELAY_MSDOCSRS_CLI_DISABLE_RETRY— kill switch for HTTP retriesDOCSRS_CLI_LANG— human stderr locale (enorpt-BR)RUST_LOG/NO_COLOR/CLICOLOR_FORCE— diagnostics only
Integration Patterns
- Agent subprocess:
docsrs-cli get-item serde trait Serialize --json - Discovery first:
docsrs-cli commands --jsonthenschema --cmd get-item --json - Offline plan:
docsrs-cli --dry-run readme tokio --json - See INTEGRATIONS.md and docs/AGENTS.md
Performance
- One primary GET per command in the happy path
- Multi-thread Tokio runtime with Semaphore concurrency budget
spawn_blockingfor large HTML parse work- Disk cache avoids repeat downloads within TTL
Memory Requirements
- Default body cap is 10 MiB per response
- Default output cap is 2 MiB per emission
- Default disk cache budget is 256 MiB soft
- Raise caps only with explicit flags or env, never above hard ceilings
Troubleshooting FAQ
- Exit
66means the crate or item was not found - Exit
69means rate limit or temporary upstream outage - Exit
74means transport failure; retry with backoff - Exit
78means local config or path readiness failed - Exit
124means wall-clock timeout - Run
docsrs-cli doctor --jsonbefore blaming the network
Documentation Map
Contributing
- Read CONTRIBUTING.md
- Follow the Code of Conduct
Security
- Read SECURITY.md
- Report issues privately to daniloaguiarbr@proton.me
Changelog
- See CHANGELOG.md for version history
License
- Dual-licensed under MIT or Apache-2.0
- See LICENSE, LICENSE-MIT, and LICENSE-APACHE