ask CLI

Simple command-line router for large language model prompts. ask lets you:

• Pipe shell output or inline prompts into one or more configured models.
• Share model definitions, aliases, and grouped fan-out calls through a single YAML config.
• Layer pre-prompts, temperature/token overrides, and metadata that cascade across aliases and groups.
• Log every run to structured JSONL files for later inspection.

The first release targets OpenRouter via the OpenAI SDK.

Prerequisites: Python 3.10+, an OpenRouter account, and an API key.

1. Clone & install

   uv pip install -e '.[dev]'

2. Configure environment (uses rasengans)

   cp config/.env.example .env
   # edit .env and add your OPENROUTER_API_KEY

   The CLI automatically loads .env on startup (via python-dotenv), so you normally do not need to source it.

3. Review configuration – config/ask.yaml defines tools, aliases, and groups. Example bundle:

   version: 1
   tools:
     default:
       prov: openrouter
       endpoint: openrouter
       model: openai/gpt-4.1-mini
       pp: file:preprompts/default.txt
       temp: 0.2
       tok: 400
     critique:
       tool: default
       pp: "Provide a concise critique focusing on weak points."
     review:
       pp: file:preprompts/review-group.txt
       members:
         - tool: default
         - tool: critique
           id: critique
           pp: "Highlight risks and follow-up questions."
   defaults:
     default_tool: default
     separator: "\n\n"
     verbose: false

4. Run the CLI

   ask "Summarize today’s meeting notes."                 # uses the configured default tool
   cat docs/ask.md | ask "Assess this document."          # default tool with piped input
   ask default "Summarize today’s meeting notes."         # explicit alias still supported
   cat docs/ask.md | ask review "Assess this document."   # group alias example
   ask review -v "Give me a project status snapshot."     # verbose flag shows log path

Tip: On first run outside the repo, the CLI seeds ~/.config/ask/config.yaml from its bundled template; adjust that file to match your models.

$ ask -v "Summarize the release notes for me."
[default] tool=default provider=openrouter model=openai/gpt-4.1-mini
Here’s a concise summary of the release notes, covering the major features and bug fixes in plain language.

$ printf "Fix auth bug\nAudit logging incomplete" | ask -v "Draft a status update"
[default] tool=default provider=openrouter model=openai/gpt-4.1-mini
Status update:
- Fixed the lingering authentication bug affecting SSO.
- Logging gaps remain; plan remediation this week.

$ cat docs/ask.md | ask -v review "Provide a critique and risks."
[default] tool=default provider=openrouter model=openai/gpt-4.1-mini
Initial analysis of the document, highlighting structure and themes.

[critique] tool=critique provider=openrouter model=openai/gpt-4.1-mini
Key risks include missing rate-limit mitigation and sparse validation coverage.

[log] wrote metadata to logs/run-20251004T120000Z.jsonl

5. Inspect logs – each invocation writes metadata to logs/run-YYYYMMDDTHHMMSSZ.jsonl. Use tail or jq to audit model usage and latency.

• All entries live under tools: and can represent:
  • Model – define prov, model, optional endpoint, and prompt/parameter defaults.
  • Alias – point tool: at another tool, optionally overriding pp, temp, tok, or params.
  • Group – declare members: to fan out to multiple tools. Reused members auto-number (default, default-1, …) unless you supply an id.
• Parameters cascade: group → alias/member → base model.
• Shorthand keys: prov, pp, temp, tok; long-form names also work.
• defaults.default_tool selects the model/alias/group that runs when no target is supplied (falls back to a tool named default).
• version pins the config format. The CLI currently supports version: 1.
• Run with -v/--verbose (or set defaults.verbose: true) to surface the invoked tool, provider, and actual model slug above each response.
• See docs/ask.md for the complete schema and additional examples.

Full guidance lives in docs/configuration/env.md.

• Install in editable mode with uv pip install -e '.[dev]' (the dev extra pulls in pytest).
• Source code lives under src/ask/; key modules:
  • config.py – YAML parsing and tool resolution.
  • runtime.py – async execution, request assembly, logging.
  • providers/openrouter.py – async OpenRouter wrapper using the OpenAI SDK.
  • cli.py – argument parsing, stdin handling, verbosity control.
• Cached vendor docs live in sdk-docs/; project history and design notes live in history.md and docs/.
• Respect the repository guideline prohibiting edits to .env (or other secret files) without explicit user approval (see AGENTS.md).

• docs/ask.md – CLI overview, configuration schema, execution scenarios.
• docs/configuration/env.md – Environment variable reference and .env usage.
• sdk-docs/openrouter.md – Cached OpenRouter API summary.
• docs/index.md – Rolling index + change log for project documentation.

• 400 Invalid model ID – verify the model: slug against curl https://openrouter.ai/api/v1/models and confirm your API key has access.
• OPENROUTER_API_KEY missing – check .env, ensure it is loaded (auto via python-dotenv).
• Rate limits / 429 – review the log JSONL for error details; OpenRouter may require backoff.
• Run with --verbose or set defaults.verbose: true to surface log-file paths and additional diagnostics.

No license has been defined yet. Confirm project ownership before redistribution.