RunLLM Lite CLI

Prototype customer-side CLI for RunLLM Lite investigations.

The CLI stores local configuration, uploads a copy of the configured repository to the Lite engine, keeps a WebSocket open for the investigation, and executes engine-requested local tool calls on the customer's laptop.

Local Development

cd src/runllm_lite_cli
uv sync --group dev
RUNLLM_LITE_ENV=dev uv run runllm
RUNLLM_LITE_ENV=dev uv run runllm ask "what is the status of pod pod-12345?"

On first use, runllm or runllm ask "..." starts a short onboarding flow:

1. Uses production defaults for packaged/PyPI installs:
   • Engine URL: https://gateway.runllm.com
   • Auth URL: https://cli.runllm.com
2. Uses local dev defaults when RUNLLM_LITE_ENV=dev:
   • Engine URL: http://127.0.0.1:5099
   • Auth URL: http://localhost:5185
3. Prompts for the API key from the auth UI and validates it with the engine.
4. Prompts for the local repo path, defaulting to the current directory.
5. Starts a non-blocking repo scan for supported integration keywords.
6. Auto-detects installed tools such as kubectl and gcloud, with sensible defaults for kubeconfig and Google Cloud project.
7. Prints repo scan results when ready, and offers matching supported tools such as Grafana if the repo references them.

You can override endpoints explicitly with RUNLLM_LITE_ENGINE_URL and RUNLLM_LITE_AUTH_URL.

If Google Cloud observability is configured during first-run interactive onboarding, RunLLM starts a background proactive discovery task. It does not block setup. If it finishes before you type your first question, RunLLM surfaces the insight and lets you ask follow-up questions in the same session. If you type first, your question wins and the proactive result is discarded.

runllm configure remains the advanced path for overriding values. It validates the engine URL and repo path and writes ~/.runllm-lite/config.json. Running it again preserves tool configuration.

On first use, the CLI checks for ~/.config/runllm/credentials.json. If no API key is cached, it prints the configured auth URL, asks you to sign in through the Lite UI, validates the pasted key with the engine, and saves the key locally with file permissions set to 0600.

To replace the cached API key explicitly:

uv run runllm configure --api-key

You can also pass the key directly with --api-key <key>, though entering it at the prompt avoids putting the key in shell history.

Tool configuration is separate:

• runllm tools configure-kubectl detects kubectl and validates kubeconfig.
• runllm tools configure-gcp-observability detects gcloud and optionally stores a default project. The CLI advertises curated actions for Cloud Logging, Error Reporting, Cloud Monitoring metrics, and alert policies while still executing everything through local gcloud credentials.
• runllm tools configure-grafana stores Grafana MCP settings. If mcp-grafana is not on PATH, the CLI downloads the latest Linux x86_64 GitHub release to ~/.runllm-lite/bin/mcp-grafana unless --no-auto-install is set.
• runllm tools list shows the configured tools that will be advertised to the engine for a session.

runllm ask "..." runs a one-shot question. Running runllm with no subcommand starts an interactive session: the CLI uploads the repo once, keeps the WebSocket open, and lets you type follow-up questions until /exit.

For Git repositories, the CLI uses git archive HEAD so the upload matches the committed files a fresh clone would contain. This excludes untracked files, ignored generated outputs, local virtualenvs, node_modules, and other working tree noise. If git archive is unavailable, the CLI falls back to a filtered filesystem archive that skips common generated or heavy paths.