reposcope.txt

*reposcope.txt* Plugin documentation for reposcope.nvim Last Change: September 2026
                                                              *reposcope.nvim*

---

INTRODUCTION *:Reposcope

reposcope.nvim is a modular Neovim plugin for browsing and managing GitHub
repositories directly from within the editor. It provides a dynamic UI
(prompt, list, preview), README caching, and cloning functionality.

Written in Lua and designed for clean architecture and maximum extensibility.

---

USAGE *reposcope-usage*

All functionality is exposed through a single dispatching command,
:Reposcope <subcommand> [args]. Run :Reposcope with no subcommand to print
the list of available subcommands; <Tab> completion offers subcommand names
first, then per-subcommand arguments.

To launch the plugin UI:

    :Reposcope start

To close it manually:

    :Reposcope close

To reload visible prompt fields:

    :Reposcope prompt prefix topic

---

CONFIGURATION *reposcope-config*

Basic setup:

  require("reposcope").setup({})

Advanced setup:

  require("reposcope").setup({
    provider = "github",           -- "github", "gitlab", or "codeberg"
    request_tool = "curl",         -- "gh", "curl", or "wget" ("gh" only works with provider = "github")
    -- If higher API Limits neeeded set set the token here.
    -- If that doesn't works see reposcope-auth
    github_token = os.getenv("GITHUB_TOKEN"),
    gitlab_token = os.getenv("GITLAB_TOKEN"),     -- used when provider = "gitlab"
    codeberg_token = os.getenv("CODEBERG_TOKEN"), -- used when provider = "codeberg"
    layout = "default",            -- UI layout
    prompt_fields = {
      "prefix", "owner", "keywords", "language", "topic", "stars"
    },
    keymaps = {
      open = "<leader>rs",
      close = "<leader>rc",
    },
    prompt_keymaps = {
      open_viewer = "<C-v>",            -- rebind or set to false/"" to disable
      preview_image = "<C-p>",          -- README image over the preview (images.nvim)
      help = "?",                       -- keymap cheatsheet (normal mode only)
    },
    prompt_prefix_symbol = " " .. "\u{f002}" .. " ", -- needs a Nerd Font; e.g. "> " for plain terminals
    clone = {
      std_dir = "~/projects",          -- directory to clone into
      type = "git",                    -- "git", "gh", "wget", or "curl"
    },
    metrics = true,                    -- enable request logging & metrics
    notify_messages = true,            -- also record popups in :messages (silently)
    readme_precache_count = 5,         -- pre-cache top N search results' READMEs (0 disables)
    results_limit = 25,                -- maximum search results per query
    hover = true,                      -- register the hover.nvim source (no-op without it)
  })

Note: GitLab's and Codeberg's search APIs only support a plain substring
match (no owner:/language:-style qualifiers like GitHub's search) — with
provider = "gitlab" or provider = "codeberg", every non-empty prompt
field is joined into one plain search string instead of being applied as a
scoped filter.

---

AUTHENTICATION *reposcope-auth*

reposcope.nvim works out of the box — no authentication is required for
basic usage.

However, if you use gh as your request tool, you MUST provide a valid
GitHub token:

    export GITHUB_TOKEN=ghp_your_token_here

⚠️  gh auth login is NOT sufficient — child processes spawned via uv.spawn()
   (used internally by Reposcope) do not inherit the GitHub CLI session.

Instead, define GITHUB_TOKEN as an environment variable
before launching Neovim.

---

RECOMMENDED SETUP *reposcope-auth-setup*

In some environments (e.g. GUI-based Neovim, zsh, or plugin managers
like Lazy.nvim), os.getenv("GITHUB_TOKEN") might return nil 
even if the token is set e.g. in system global .env-files.

To ensure the token is always available to Reposcope:

  • Prefer setting it explicitly in your setup block:

  require("reposcope").setup({
    github_token = os.getenv("GITHUB_TOKEN") or "gh_token",-- ✅ Explicit
    ...
  })

• You may still use curl or wget as request tools without authentication,
  but this will apply GitHub's stricter anonymous
  rate limits (typically 60 requests/hour).

---

KEYMAPS *reposcope-keymaps*

Inside the Reposcope UI:

| Key         | Action                                      |
|-------------|---------------------------------------------|
| <Esc>     | Close the entire UI                         |
| <C-v>     | View the README in a floating viewer        |
| <C-b>     | Open README in an editable buffer           |
| <C-c>     | Clone the selected repository               |
| <Tab>     | Next prompt field (in insert mode)          |
| <S-Tab>   | Previous prompt field (in insert mode)      |
| <CR>      | Trigger search                              |
| <C-u>     | Scroll the README preview up (stays in the prompt)   |
| <C-d>     | Scroll the README preview down (stays in the prompt) |
| <C-p>     | Draw the README's image over the preview (images.nvim) |
| <C-f>     | Toggle favorite for the selected repository          |
| ?         | Show the keymap cheatsheet (normal mode only)        |

All prompt keymaps are configurable/disableable via prompt_keymaps in
|reposcope-config|, and carry a desc so which-key picks them up
automatically if installed. See docs/BINDINGS.md in the repository for
the full, authoritative table.

<C-p> needs images.nvim with display.remote.enabled = true. Without it
every other key behaves the same and <C-p> says what is missing. It is a
key rather than something the preview does on its own because only 8 of 25
measured repositories carry a real README image, and the ones that do cost
roughly 900ms and 230kB. Finding out that a repository has none costs
nothing: the check runs against the README already in Reposcope's cache.
See docs/configuration.md for the measurement and the images.nvim
settings it argues for.

---

COMMANDS *reposcope-commands*

All functionality lives under one command: :Reposcope <subcommand> [args].
The following subcommands are available:

| Command                       | Description                                  |
|-------------------------------|----------------------------------------------|
| :Reposcope start            | Opens the Reposcope UI                       |
| :Reposcope close            | Closes the UI                                |
| :Reposcope prompt ...       | Dynamically reloads prompt fields in the UI  |
| :Reposcope sort             | Opens interactive menu to choose sort mode   |
| :Reposcope filter {text}    | Filters list by substring                    |
| :Reposcope filter-prompt    | Prompt input for interactive filtering       |
| :Reposcope filter-clear     | Resets the filter and restores full list     |
| :Reposcope providers        | Lists providers and marks the active one     |
| :Reposcope session ...      | Save, restore, or clear the search session   |
| :Reposcope favorites ...    | Lists favorited repositories, or clears them |
| :Reposcope queries ...      | Prints top-10 frequent queries, or clears stats |
| :Reposcope skipped-readmes  | Prints number of debounced README fetches    |
| :Reposcope stats            | Displays request statistics (metrics)        |
| :Reposcope messages [clear] | Message history in a buffer / forget it      |
| :Reposcope toggle-dev       | Toggles developer mode (logging, mocking)    |
| :Reposcope print-dev        | Prints current developer mode status         |

Running :Reposcope with no subcommand prints this list inside Neovim.

---

:Reposcope prompt {fields} *:Reposcope-prompt*

Sets the prompt fields shown in the Reposcope UI.
Automatically restarts the UI to apply changes.

- If no fields are given, defaults to: keywords, owner, language.
- Autocompletion lists all available prompt fields.
- Example:

    :Reposcope prompt prefix topic stars

You can also simply run:

    :Reposcope prompt

To reset to the default prompt layout.

---

:Reposcope sort *:Reposcope-sort*

Opens an interactive menu (via vim.ui.select) to choose a sort mode
(e.g. "name", "owner", "stars", or "relevance").

---

:Reposcope filter {text} *:Reposcope-filter*

Filters the current list of repositories by a case-insensitive substring
that matches owner/name: description.

If called without any arguments, the filter will be cleared and the original
API result (sorted by relevance) will be restored.

- Example:
    :Reposcope filter bun typescript
    :Reposcope filter

---

:Reposcope filter-prompt *:Reposcope-filter-prompt*

Opens a prompt input field to interactively enter
a filter term for the repository list.

---

:Reposcope filter-clear *:Reposcope-filter-clear*

Clears any active filter and restores the original list of repositories,
as returned by the last successful API search (sorted by relevance).

This command is functionally equivalent to calling:

    :Reposcope filter

Use this as a shortcut when you want to reset filtering explicitly.

---

:Reposcope providers *:Reposcope-providers*

Lists every registered provider (github, gitlab, codeberg) and marks
the currently active one (the provider config option) with *.

- Example output:

    codeberg
    github
  * gitlab

---

:Reposcope session save|restore|clear *:Reposcope-session*

Saves, restores, or clears the last search session: the active provider,
the visible prompt fields and their typed-in text, the last built search
query, the active filter text, and the current sort mode. Stored as a single
JSON file under the plugin's cache directory; survives Neovim restarts.
Nothing is saved automatically.

- save    — writes the current session, overwriting any previous one.
- restore — restores provider/prompt/input, re-runs the last search, then
  re-applies the saved filter and sort mode once results arrive.
- clear   — deletes the saved session file, if one exists.

- Example:

    :Reposcope session save
    :Reposcope session restore
    :Reposcope session clear

---

:Reposcope favorites list|clear *:Reposcope-favorites*

Lists favorited repositories in a scrollable popup, or clears all of them.
A favorite is toggled while browsing with the toggle_favorite prompt
keymap (default <C-f>, see |reposcope-keymaps|) — there is no separate
"add favorite" command. Toggling snapshots the repository's metadata
(owner, name, description, URL, stars) and its README content if already
cached, so the favorite is self-contained: viewing it later needs no live
re-fetch. Stored as a single JSON file under the plugin's cache directory;
survives Neovim restarts.

- favorites / favorites list — opens the popup (q/<Esc> to close).
- favorites clear              — removes all favorites.

If you have any favorites saved, :Reposcope start shows them immediately
(list populated, first entry's preview pre-warmed from its README
snapshot) instead of starting from an empty prompt.

- Example:

    :Reposcope favorites
    :Reposcope favorites clear

---

:Reposcope queries list|clear *:Reposcope-queries*

Every real search (pressing <CR> in the prompt) increments a persisted
run-count for the exact query that was built. queries list prints the
top 10, most-frequent first; queries clear resets the counts. Recorded
automatically — no opt-in needed, since it never leaves the plugin's cache
directory.

- Example:

    :Reposcope queries
    :Reposcope queries clear

---

CACHE *reposcope-cache*

README caching is handled on two levels:

- RAM cache (fast)
- File cache (stdpath("cache")/reposcope/data/readme/)

Caches are automatically used and updated. File cache survives restarts.
On setup(), every file-cached README is preloaded into the RAM cache, so a
fresh session doesn't pay a disk read on the first visit to an
already-cached repository.

Each cached README also records the repository's updated_at
(GitHub/Codeberg) or last_activity_at (GitLab) at cache time. If that
value changes on a later visit, the cache is treated as a miss and the
README is re-fetched — otherwise a repository that hasn't changed is never
re-fetched, no matter how old the cache entry is.

readme_precache_count (default 5, see |reposcope-config|) pre-caches the
top N search results' READMEs in the background right after a search, so
scrolling through them feels instant instead of triggering a fetch per row.
Set to 0 to disable.

---

CLONING *reposcope-clone*

Repositories can be cloned using:

- git (default)
- gh
- wget
- curl

Cloning requires a valid clone.std_dir and tool configuration.

Already cloned repositories can be maintained (a multi-repo git-status
dashboard, bulk fetch/pull) with gitsuite.nvim's :Git dashboard — see
https://github.com/StefanBartl/gitsuite.nvim.

---

TROUBLESHOOTING *reposcope-troubleshooting*

- If nothing shows in preview: check for missing README or invalid API token
- If gh requests silently fail: ensure GITHUB_TOKEN is set
- For logs/metrics: enable metrics = true and inspect
  stdpath("cache")/reposcope/logs/request_log.json — one entry per
  uuid:type, each carrying query, source, context, and (where
  available) the actual request/repository url
- Session, favorites and query-stat files live beside it under
  stdpath("cache")/reposcope/data/

See docs/troubleshooting.md in the repository for the full symptom table
and for forcing a fresh README.

---

HEALTHCHECK *reposcope-health*

Reposcope provides a built-in health module to verify installation, tool
availability, environment variables, and configuration.

To run the health check:

  :checkhealth reposcope

This will perform the following diagnostics:

• Check if all core modules are loadable
• Verify configured request tool (gh, curl, wget)
• Test if the selected request binary is available in $PATH
• Detect presence of the GitHub token (GITHUB_TOKEN)
• Report whether images.nvim is installed, whether its remote images are
  enabled, and the effective download cap (the <C-p> image preview)

Example output:

> 
  ## Reposcope: plugin healthcheck
  OK   Core modules loaded
  OK   curl is installed
  WARN No GitHub token set (you may hit rate limits)

If you see any errors, consult |reposcope-auth| or |reposcope.setup|
for correction.

---

SEE ALSO *reposcope-links*

- GitHub:      https://github.com/StefanBartl/reposcope.nvim
- Doc index:   docs/README.md in the repository
- lib.nvim:    https://github.com/StefanBartl/lib.nvim (required)
- hover.nvim:  https://github.com/StefanBartl/hover.nvim (optional, see
               docs/hover.md)
- images.nvim: https://github.com/StefanBartl/images.nvim (optional, the
               <C-p> README image preview)

---