feat: add btw CLI via Rapp for command-line access to R tools

[gadenbuie]

Summary

Adds a btw CLI that wraps the package's tool groups — docs, pkg, info, and cran — so that both humans and LLMs can invoke them from the command line via Rapp.

Key pieces:

• exec/btw.R — The Rapp CLI script with two-level command dispatch (btw <group> <command> [args] [flags]). Supports TTY-aware output (colored for terminals, plain markdown when piped).
• R/cli.R — install_btw_cli() installer function that verifies all CLI dependencies are present before installing, plus an interactive prompt to install the r-btw-cli skill.
• inst/cli-skill/r-btw-cli/SKILL.md — Claude Code skill file documenting CLI usage for AI agents.
• Tests and snapshots — Comprehensive test suite in tests/testthat/test-cli.R covering argument parsing, help text, topic/package lookup semantics, JSON output, and error cases.

CLI commands implemented:

• btw docs help, btw docs vignette, btw docs news
• btw pkg document|check|test|load|coverage
• btw info platform|packages
• btw cran search|info

Notable behaviors

Topic-first help lookup — btw docs help <name> tries to resolve as a help topic first, falling back to a package listing. Use btw docs help {<pkg>} to explicitly request a package listing, or btw docs help <pkg>::<topic> for scoped lookup.

--json flag — Structured JSON output for commands with tabular/list data, suitable for piping to jq:

btw info platform --json | jq -r '."r_version:"'
btw info packages dplyr ggplot2 --check --json | jq '.[].version'
btw cran search "geospatial" --json | jq '.[].package'
btw cran info ggplot2 --json | jq '.Imports'
btw pkg coverage --json | jq '.[] | select(.coverage < 80)'

Verification

# Install the CLI (requires Rapp v0.3.0+)
btw::install_btw_cli()

# Try it out
btw docs help dplyr::mutate
btw docs help {dplyr}
btw cran search "machine learning" --json | jq '.[0].package'
btw info platform --json
btw pkg test --filter cli

[vladimirobucina]

this is great, I just saw couple of days ago that new Rapp was published and now I see that you've added this to btw. Have you done some benchmarking to compare token consumption between CLI version and MCP version of these tools?

[gadenbuie]

Have you done some benchmarking to compare token consumption between CLI version and MCP version of these tools?

Thanks! I don't have any benchmarking, but I the CLI version will definitely use less tokens. The skill that comes with the CLI teaches the model how to use btw from the CLI in roughly the same number of tokens as a single tool description. In my experience so far, that skill is enough for the model to use btw effectively and it rarely needs to read the btw --help text. So that's one way the CLI reduces token usage.

The other is that if you're using btw tools via MCP you're likely including all of the tool definitions in your system prompt, which is also included even if you aren't doing anything with R in your session. With the CLI, however, less than 100 tokens are used for the skill description, so your system prompt overhead is much lower.