*poor-cli.txt*  AI-powered inline completion and chat for Neovim

Author:  gongahkia
License: MIT

INTRODUCTION                                            *poor-cli*

poor-cli is an AI-powered coding assistant plugin for Neovim that provides
inline ghost text completion (like Copilot/Windsurf) and a chat panel for
conversational AI interactions.

Features:
- Inline ghost text completion with multi-line support
- Completion controls: manual-only mode, filetype/buftype gating, context budgets
- Chat panel with markdown rendering
- Multi-provider support (Gemini, OpenAI, Claude, Ollama)
- Managed log file and diagnostic report commands
- Native blink.cmp source and nvim-cmp source
- AI-powered code commands (explain, refactor, test, docs)

REQUIREMENTS                                            *poor-cli-requirements*

- Neovim 0.9+
- Python 3.9+
- poor-cli installed: `pip install poor-cli`
- API key for at least one provider

SETUP                                                   *poor-cli-setup*

Add to your init.lua:
>lua
    require("poor-cli").setup({
        -- options
    })
<

CONFIGURATION                                           *poor-cli-config*

                                                        *poor-cli-config.server_cmd*
server_cmd ~
    Default: "poor-cli-server --stdio"
    Command to start the server.

                                                        *poor-cli-config.server_log_file*
server_log_file ~
    Default: nil
    Optional log file path. When unset, poor-cli writes logs to
    stdpath("state") .. "/poor-cli/server.log".

                                                        *poor-cli-config.auto_start*
auto_start ~
    Default: true
    Auto-start server when setup() is called.

                                                        *poor-cli-config.auto_restart*
auto_restart ~
    Default: true
    Restart the backend automatically after unexpected exits.

                                                        *poor-cli-config.ghost_text_hl*
ghost_text_hl ~
    Default: "Comment"
    Highlight group for ghost text completions.

                                                        *poor-cli-config.trigger_key*
trigger_key ~
    Default: "<C-Space>"
    Key to trigger inline completion in insert mode.

                                                        *poor-cli-config.accept_key*
accept_key ~
    Default: "<Tab>"
    Key to accept completion. Falls back to normal Tab if no completion.

                                                        *poor-cli-config.dismiss_key*
dismiss_key ~
    Default: "<Esc>"
    Key to dismiss completion. Falls back to normal Esc if no completion.

                                                        *poor-cli-config.chat_key*
chat_key ~
    Default: "<leader>pc"
    Key to toggle chat panel.

                                                        *poor-cli-config.checkpoints_key*
checkpoints_key ~
    Default: nil
    Optional normal-mode keymap for checkpoint picker.

                                                        *poor-cli-config.provider*
provider ~
    Default: nil (auto-detect)
    AI provider: "gemini", "openai", "anthropic", "ollama"

                                                        *poor-cli-config.model*
model ~
    Default: nil (provider default)
    Specific model name to use.

                                                        *poor-cli-config.completion_provider*
completion_provider ~
    Default: nil
    Optional completion-only provider override.

                                                        *poor-cli-config.completion_model*
completion_model ~
    Default: nil
    Optional completion-only model override.

                                                        *poor-cli-config.auto_trigger*
auto_trigger ~
    Default: false
    Automatically trigger completion on CursorHoldI.

                                                        *poor-cli-config.completion_enabled*
completion_enabled ~
    Default: true
    Enable inline completion for supported buffers.

                                                        *poor-cli-config.completion_manual_only*
completion_manual_only ~
    Default: false
    Disable auto-triggered completion and allow manual requests only.

                                                        *poor-cli-config.completion_min_prefix*
completion_min_prefix ~
    Default: 0
    Minimum prefix length required before auto-triggered completion runs.

                                                        *poor-cli-config.completion_stream_partial*
completion_stream_partial ~
    Default: true
    Render partial inline completion chunks while the backend is streaming.

                                                        *poor-cli-config.completion_max_lines_before*
completion_max_lines_before ~
    Default: 80
    Maximum number of lines of prefix context sent to the backend.

                                                        *poor-cli-config.completion_max_lines_after*
completion_max_lines_after ~
    Default: 80
    Maximum number of lines of suffix context sent to the backend.

                                                        *poor-cli-config.completion_max_chars*
completion_max_chars ~
    Default: 16000
    Total character budget for inline completion context.

                                                        *poor-cli-config.completion_lsp_context_max_chars*
completion_lsp_context_max_chars ~
    Default: 4000
    Character cap applied to any LSP-derived context.

                                                        *poor-cli-config.completion_filetype_allowlist*
completion_filetype_allowlist ~
    Default: {}
    If non-empty, completion runs only for filetypes in this list.

                                                        *poor-cli-config.completion_filetype_blocklist*
completion_filetype_blocklist ~
    Default: {}
    Filetypes where completion should never attach.

                                                        *poor-cli-config.completion_buftype_blocklist*
completion_buftype_blocklist ~
    Default: { "nofile", "prompt", "quickfix", "terminal" }
    Buffer types where completion should never attach.

                                                        *poor-cli-config.diagnostics_enabled*
diagnostics_enabled ~
    Default: false
    Enable assistant file:line suggestions as inline diagnostics.

COMMANDS                                                *poor-cli-commands*

:PoorCliStart                                           *:PoorCliStart*
    Start the AI server.

:PoorCliStop                                            *:PoorCliStop*
    Stop the AI server.

:PoorCliRestart                                         *:PoorCliRestart*
    Restart the AI server and re-initialize the session.

:PoorCliCancel                                          *:PoorCliCancel*
    Cancel the active inline or chat request.

:PoorCliStatus                                          *:PoorCliStatus*
    Show the shared session status summary with routing, context, and
    collaboration state.

:PoorCliTrust                                           *:PoorCliTrust*
    Open the trust center for provider, sandbox, rollback, policy, and
    privacy posture.

:PoorCliRuns                                            *:PoorCliRuns*
    Open recent shared run history.

:PoorCliWorkflow [name]                                 *:PoorCliWorkflow*
    List workflow templates or inspect one starter scaffold.

:PoorCliContext                                         *:PoorCliContext*
    Open the backend context explanation for the current editing session.

:PoorCliDoctor                                          *:PoorCliDoctor*
    Open a structured diagnostic report buffer with actionable remediation.

:PoorCliCopyDebugInfo                                   *:PoorCliCopyDebugInfo*
    Copy the diagnostic report to the clipboard/register.

:PoorCliOpenLog                                         *:PoorCliOpenLog*
    Open the poor-cli server log file.

:PoorCliOpenStateDir                                    *:PoorCliOpenStateDir*
    Open the poor-cli state directory.

:PoorCliWriteMinInit [path]                             *:PoorCliWriteMinInit*
    Generate a minimal init.lua for reproducible bug reports.

:PoorCliChat                                            *:PoorCliChat*
    Toggle the chat panel.

:PoorCliSend [message]                                  *:PoorCliSend*
    Send a message to chat. If no message provided, prompts for input.

:PoorCliClear                                           *:PoorCliClear*
    Clear chat history.

:PoorCliDiagnostics                                     *:PoorCliDiagnostics*
    Toggle assistant diagnostics integration.

:PoorCliCheckpoints                                     *:PoorCliCheckpoints*
    Browse and restore checkpoints via telescope.nvim.

:PoorCliComplete                                        *:PoorCliComplete*
    Trigger inline completion at cursor.

:PoorCliAccept                                          *:PoorCliAccept*
    Accept the current inline completion.

:PoorCliDismiss                                         *:PoorCliDismiss*
    Dismiss the current inline completion.

:PoorCliAcceptLine                                      *:PoorCliAcceptLine*
    Accept the current completion line.

:PoorCliAcceptWord                                      *:PoorCliAcceptWord*
    Accept the next completion word.

:PoorCliSwitchProvider [provider] [model]               *:PoorCliSwitchProvider*
    Switch to a different AI provider. If no provider given, shows picker.

:PoorCliExplain                                         *:PoorCliExplain*
    Explain the current line or visual selection.

:PoorCliRefactor                                        *:PoorCliRefactor*
    Refactor the visual selection. Prompts for instruction.

:PoorCliTest                                            *:PoorCliTest*
    Generate unit tests for the current function.

:PoorCliDoc                                             *:PoorCliDoc*
    Generate documentation for the current function.

KEYMAPS                                                 *poor-cli-keymaps*

Insert mode:
    <C-Space>       Trigger inline completion
    <Tab>           Accept completion (or normal Tab)
    <Esc>           Dismiss completion (or normal Esc)
    <M-CR>          Trigger completion with instruction

Normal mode:
    <leader>pc      Toggle chat panel
    gc              Start insert and trigger completion

Visual mode:
    <leader>pc      Send selection to chat
    <leader>pr      Refactor selection
    <leader>pe      Explain selection

API                                                     *poor-cli-api*

Lua API for custom integrations:
>lua
    local poor_cli = require("poor-cli")
    
    poor_cli.start()           -- Start server
    poor_cli.stop()            -- Stop server
    poor_cli.is_running()      -- Check if server running
    poor_cli.complete()        -- Trigger completion
    poor_cli.accept()          -- Accept completion
    poor_cli.dismiss()         -- Dismiss completion
    poor_cli.toggle_chat()     -- Toggle chat panel
    poor_cli.send("message")   -- Send message to chat
<

BLINK.CMP                                               *poor-cli-blink*

PoorCLI exposes a blink.cmp provider helper:
>lua
    require("blink.cmp").setup({
        sources = {
            default = { "lsp", "path", "snippets", "buffer", "poor_cli" },
            providers = {
                poor_cli = require("poor-cli.blink").provider(),
            },
        },
    })
<

The blink source reuses poor-cli inline completion request shaping and
buffer/filetype gating rules.

HEALTH CHECK                                            *poor-cli-health*

Run `:checkhealth poor-cli` to verify your configured server command, log path,
Python availability, detected API keys, active provider state, and optional
nvim-cmp/blink.cmp integration.

TROUBLESHOOTING                                         *poor-cli-troubleshooting*

Server won't start:
1. Check `poor-cli-server` is in PATH: `which poor-cli-server`
2. Install if missing: `pip install poor-cli`
3. Check Python version: `python3 --version` (needs 3.9+)
4. Open the log with `:PoorCliOpenLog`
5. Capture a report with `:PoorCliDoctor` or `:PoorCliTrust`

No completions:
1. Verify API key: `echo $GEMINI_API_KEY`
2. Check status: `:PoorCliStatus`
3. Confirm the current buffer is not blocked by filetype/buftype/manual-only
   completion settings
4. Inspect provider, sandbox, and rollback posture in `:PoorCliTrust`
5. If you use nvim-cmp, run `:checkhealth poor-cli`
6. Open the server log with `:PoorCliOpenLog`

blink.cmp source missing:
1. Confirm blink.cmp is installed
2. Add `poor_cli = require("poor-cli.blink").provider()` to blink providers
3. Include `poor_cli` in blink default sources
4. Run `:checkhealth poor-cli`

Bug reports:
1. Run `:PoorCliCopyDebugInfo`
2. Include the log from `:PoorCliOpenLog`
3. Generate a minimal repro config with `:PoorCliWriteMinInit`

vim:tw=78:ts=8:ft=help:norl:
