If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/tealdeer-rs/tealdeer shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 21+ active contributors
• Distributed ownership (top contributor 45% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live tealdeer-rs/tealdeer repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/tealdeer-rs/tealdeer.

What it runs against: a local clone of tealdeer-rs/tealdeer — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in tealdeer-rs/tealdeer | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of tealdeer-rs/tealdeer. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/tealdeer-rs/tealdeer.git
#   cd tealdeer
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of tealdeer-rs/tealdeer and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "tealdeer-rs/tealdeer(\\.git)?\\b" \\
  && ok "origin remote is tealdeer-rs/tealdeer" \\
  || miss "origin remote is not tealdeer-rs/tealdeer (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/tealdeer-rs/tealdeer"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

tealdeer is a blazingly-fast Rust implementation of tldr, a command-line tool that fetches and displays simplified, practical examples for CLI commands. It replaces verbose man pages with concise, community-curated examples from the tldr-pages repository, with offline caching and zero dependencies on system man pages or network (after initial cache population). Single binary structure ([[bin]] name = "tldr" → src/main.rs). Core modules: cli.rs (clap argument parsing), cache.rs (offline storage via app_dirs2), config.rs (TOML config from docs/src/config.md), formatter.rs (output styling with yansi), output.rs (display logic), line_iterator.rs (tldr page parsing). No monorepo—flat src/ layout. Completion scripts in completion/ for bash/fish/zsh. Documentation as mdbook in docs/src/.

DevOps engineers, sysadmins, and developers who frequently use the CLI but don't want to dig through man pages; users on slow networks or offline who need quick command syntax reminders; teams deploying lightweight CLI tooling via musl binaries (Docker containers, Alpine Linux) where traditional dependencies are costly.

Production-ready and actively maintained. Version 1.8.1 with Rust MSRV 1.85, MIT/Apache-2.0 dual-licensed. Robust CI in .github/workflows/ covering release automation and deployments. Last version bump indicates active development with release tooling documented in RELEASING.md. Integration tests present in test suite and dev-dependencies (assert_cmd, predicates). Not experimental—widely used as a tldr client replacement.

Low risk: minimal core dependencies (anyhow, clap, serde, ureq, yansi, zip for parsing tldr archives). Multiple TLS backends (rustls-with-webpki-roots + rustls-with-native-roots default features) reduce single-point failure. Dual maintainers listed (Danilo Bargen, Niklas Mohrin) reduce bus-factor risk. No indication of major breaking changes in recent history (CHANGELOG.md present). Single risk: HTTP client (ureq 3.0.8) and zip parsing are external, but both are stable crates.

Active maintenance with CI/CD pipeline in place (.github/workflows/ci.yml, gh-pages.yml, release.yml). No breaking API changes visible; focus on stability and performance. Benchmarking infrastructure present (benchmarks/Dockerfile). Dependabot configured (.github/dependabot.yml) for automated dependency updates. Changelog and release process documented, indicating structured versioning.

git clone https://github.com/tealdeer-rs/tealdeer.git
cd tealdeer
cargo build --release
./target/release/tldr <command>

Or install directly: cargo install tealdeer (published to crates.io).

Daily commands: Development: cargo build (debug) or cargo build --release (optimized with LTO, strip, codegen-units=1). Run: cargo run -- <command> (e.g., cargo run -- ls). Tests: cargo test or cargo test --test '*' (uses tempfile for sandboxing). Benchmarks: docker build -f benchmarks/Dockerfile . for containerized comparison.

• src/main.rs: Entry point; wires up CLI, config loading, cache, and formatter—understand the request flow here first
• src/cli.rs: Clap struct definitions for all CLI arguments; modify here to add new flags or subcommands
• src/cache.rs: Core offline functionality: downloads tldr-pages ZIP, extracts to app_dirs, searches/parses local files
• src/config.rs: TOML config parsing (colors, themes, update behavior); must understand for user customization features
• src/formatter.rs: Output styling engine using yansi; where visual changes (colors, bold, layout) happen
• Cargo.toml: Feature flags (native-tls vs rustls, logging, ignore-online-tests) and dependency pins; controls build variants
• docs/src/: User-facing documentation (mdbook); source of truth for config options and usage patterns
• .github/workflows/release.yml: Automation for publishing binaries to GitHub releases and crates.io; understand before releasing

New CLI features: edit src/cli.rs (clap struct definitions). Cache behavior: src/cache.rs (app_dirs2 integration, zip extraction). Config options: src/config.rs (TOML parsing, validation) + docs/src/config*.md (documentation). Output/styling: src/formatter.rs (text rendering) and src/output.rs (page layout). Parsing tldr pages: src/line_iterator.rs (markdown line handling). Add tests: create .rs files in tests/ directory (uses assert_cmd for CLI testing). Update docs: docs/src/ (mdbook chapters).

TLS feature trap: default build requires rustls-with-webpki-roots OR rustls-with-native-roots enabled; cargo build --no-default-features will fail without explicitly selecting one. Platform-specific paging: pager crate only available on non-Windows (cfg(not(windows))); Windows builds use fallback output. Cache directory: uses app_dirs2 crate, which respects XDG_CACHE_HOME on Linux—tests may fail if env var pollutes state. ZIP extraction: deflate-only (not other compressions); if tldr-pages changes archive format, extraction breaks. MSRV 1.85: some dependencies may require toolchain bump; check rustup update before contributing. Feature ignore-online-tests: exists for CI to skip network tests; not enabled by default but relevant for offline development.

• dbrgn/tealdeer — Original author's personal fork; reference for architectural decisions and early feature evolution
• tldr-pages/tldr — Upstream source of all command pages (the community-curated examples this tool fetches and displays)
• ishuah/tldr — Alternative tldr client in Python; compare philosophy and feature parity (e.g., handling of platform-specific pages)
• cheat/cheat — Similar CLI cheat-sheet tool with community pages; overlapping use case and audience (DevOps quick-reference)
• man-pages/man-pages — Traditional Linux man pages source; tealdeer provides lightweight alternative to traditional man page workflow

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for cache invalidation and update workflows

The repo has test fixtures in tests/cache/ with versioned inkscape pages (v1, v2) but no explicit tests for cache update scenarios. The src/cache.rs module handles critical caching logic, yet tests/lib.rs appears minimal. Adding tests for: cache expiration, partial updates, corrupt cache recovery, and version migrations would catch regressions in a core feature and improve confidence in offline functionality.

• [ ] Review current test coverage in tests/lib.rs and tests/cache/ fixtures
• [ ] Add integration tests in tests/lib.rs for cache expiration logic from src/cache.rs
• [ ] Add test cases for handling corrupt or outdated cache files with version mismatches
• [ ] Add test fixture for cache update scenarios (e.g., new pages added, old pages removed)
• [ ] Verify tests run in CI via tests/ execution in .github/workflows/ci.yml

Add shell completion installation helper and CI verification

Completion files exist in completion/ (bash, fish, zsh) but there's no documented installation mechanism or CI validation that they're syntactically correct. The release workflow in .github/workflows/release.yml doesn't validate or package completions. Adding a build script to verify shell syntax and a section in docs/src/installing.md for completion setup would improve discoverability and catch breakage early.

• [ ] Create a build/test script (scripts/verify-completions.sh) to validate syntax of completion/bash_tealdeer, completion/fish_tealdeer, completion/zsh_tealdeer using respective shell linters
• [ ] Add completion verification step to .github/workflows/ci.yml to run the validation script
• [ ] Add installation instructions to docs/src/installing.md with platform-specific guidance (e.g., ~/.local/share/bash-completion/completions for bash)
• [ ] Test locally on bash, fish, and zsh shells before submitting PR

Refactor and test config parsing with structured error reporting in src/config.rs

The src/config.rs module parses TOML config files and handles multiple sections ([display], [style], [search], [updates]) documented in docs/src/config.md, but error messages for malformed configs are likely generic TOML errors. Adding unit tests for each config section, custom error types, and validation would improve user experience and maintainability. This also aligns with the detailed config docs that hint at complex validation logic.

• [ ] Review current error handling in src/config.rs and src/types.rs
• [ ] Create unit tests in src/config.rs for valid and invalid configs (e.g., invalid style values, missing required fields)
• [ ] Add test cases matching config examples from docs/src/config_display.md, docs/src/config_style.md, docs/src/config_search.md, docs/src/config_updates.md
• [ ] Implement custom error types (e.g., ConfigError) with context-aware messages for each config section
• [ ] Ensure tests pass locally and in CI via cargo test

• Add integration tests for the --list flag in src/cli.rs (search path listing). Currently src/cache.rs has list logic but tests/ directory lacks dedicated test files for this feature—add tests/list_pages.rs using assert_cmd to validate output format.
• Expand shell completion scripts: completion/bash_tealdeer exists but is minimal. Add subcommand completions (--update, --clear-cache, --list) and command name completions by parsing cache; good starter for understanding cache structure and clap introspection.
• Document the [display] config section in docs/src/config_display.md with concrete examples (tested against real config.toml parsing in src/config.rs). Current docs exist but lack before/after terminal screenshots showing color and style variations.

The tealdeer project demonstrates generally good security practices. It's a Rust application with memory safety guarantees, uses well-maintained dependencies, and includes dual licensing. Key concerns are primarily around external resource handling (HTTP, zip extraction, proxy support) rather than code-level vulnerabilities. The most significant risk is improper handling of downloaded archives which could be exploited via zip bombs or path traversal. The application would benefit from formal security documentation, explicit validation of external inputs, and more conservative TLS configuration defaults. No hardcoded credentials, SQL injection risks, or obvious cryptographic weaknesses were identified.

• Medium · Multiple TLS/TLS Certificate Validation Implementations — Cargo.toml (features section), ureq dependency configuration. The codebase allows selection between multiple TLS implementations (native-tls, rustls-with-webpki-roots, rustls-with-native-roots) via feature flags. While flexibility is beneficial, this increases the attack surface and requires careful maintenance of all paths. The default configuration enables both rustls variants, which could lead to unexpected behavior or misconfiguration. Fix: Document TLS implementation selection clearly. Consider restricting to a single well-maintained TLS backend in default features. Ensure all TLS variants receive equivalent security updates and testing. Add CI tests for all enabled TLS configurations.
• Medium · Dependency on External HTTP Client with Proxy Support — Cargo.toml (ureq dependency with socks-proxy feature). The application uses ureq with SOCKS proxy support enabled. While this enables legitimate use cases, SOCKS proxy support can be exploited if the proxy configuration is compromised or maliciously controlled by an attacker on the network. Fix: Validate and document proxy configuration handling. Implement strict proxy URL validation. Consider making SOCKS proxy support optional via feature flag. Add security audit logging for proxy connections in sensitive environments.
• Low · Zip Archive Extraction Without Explicit Validation — Cargo.toml (zip dependency), src/cache.rs (likely extraction logic). The application uses the 'zip' crate for extracting downloaded tldr page archives. While zip functionality itself is not inherently dangerous, zip bombs and path traversal attacks are potential risks if extraction is not carefully controlled. Fix: Implement validation before extraction: (1) Verify archive size limits, (2) Check for path traversal attempts (e.g., '../' in paths), (3) Validate extracted file paths are within expected directory, (4) Set reasonable extraction timeouts, (5) Consider using a dedicated library with built-in safety checks.
• Low · Weak Rust Version Requirement — Cargo.toml (rust-version = "1.85"). The MSRV (Minimum Supported Rust Version) is set to 1.85, which is very recent. While newer versions generally have better security, this tight coupling may prevent users on stable/LTS distributions from using the tool, potentially leading to use of older insecure versions. Fix: Consider extending MSRV support to at least 2-3 versions back (e.g., 1.70+) to allow broader deployment in constrained environments. Document any specific security features that require newer Rust versions.
• Low · No Explicit Security Audit Trail — Repository root (absence of SECURITY.md). The codebase shows no evidence of security.md file, security contact information, or published security audit reports for a project that handles network requests and file operations. Fix: Create a SECURITY.md file with: (1) Security contact email, (2) Vulnerability disclosure process, (3) PGP key for encrypted reports, (4) Link to security audit reports if available, (5) Security update policy.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.