Skip to content

LLM CLI in 30 mins

  • TL;DR: llm_cli is a lightweight CLI tool that applies LLM transformations to text and code files. Use it to refactor code, improve docs, apply linting rules, or run custom prompts on file chunks — all from shell without leaving editor

Introduction#

  • Text transformation is a common dev task: refactoring code, improving docs, fixing style issues, applying rules to slide decks, generating summaries

  • llm_cli automates this: pipe text through LLM directly from shell

  • llm_cli solves several problems:

  • Apply LLM transformations without leaving terminal
  • Use system prompts, rules, or skills to guide LLM behavior
  • Process specific file chunks without touching the rest
  • Chain transformations in shell pipelines

  • Auto-lint output with Prettier

  • Unlike generic LLM wrappers, llm_cli integrates with Claude Code skills and rules: apply same transformations from command line as from IDE

When to Use It#

  • Use llm_cli when you need to:
  • Refactor multiple files with same rules
  • Apply a skill (e.g., "fix documentation" or "improve code style") to a file
  • Extract a file section, transform with LLM, and reassemble original
  • Integrate LLM transformations into shell scripts or Makefiles

  • Test a prompt or rule before applying via Claude Code

  • Similar tools are

  • llm CLI (Simon Willison)
  • ChatGPT
  • one-off Python scripts but none combine LLM + file handling + rule integration as cleanly

Prerequisites#

  • Python 3.11 or later
  • Access to LLM API (OpenAI, Anthropic, or OpenRouter)
  • llm Python library installed (auto-included in helpers)
  • .claude/skills/ dir with skill definitions (optional, but useful)

Installation and Setup#

  • llm_cli comes with helpers library. Verify it's available:

    > llm_cli.py --help
usage: llm_cli.py [-h] [--input INPUT] [--input_text INPUT_TEXT] ...

  • Configure LLM API key:

    > export OPENAI_API_KEY="your-key-here"

  • Or for Claude via Anthropic:

    > export ANTHROPIC_API_KEY="your-key-here"

  • Check that LLM is working:

    > llm_cli.py --input_text "Say hello" --output -
Hello! How can I help you today?

Core Concepts#

  • llm_cli operates in these stages:
  • Read input: From file, stdin, or directly as text
  • Extract chunk (optional): Use --select to process only part of file
  • Choose a prompt: Inline prompt, file, rule from .claude/skills/, or full skill
  • Transform: Send text through LLM
  • Optionally lint: Auto-format output (e.g., with Prettier)

  • Write output: To file, stdout, or back to input file

  • Each stage optional depending on use case. Simplest usage: input and output

Key Options#

  • --input FILE / -i FILE: Input file path. Use - for stdin
  • --input_text TEXT: Input text from command line
  • --output FILE / -o FILE: Output file path. Use - for stdout
  • --system_prompt TEXT / -p TEXT: Prompt text to guide the LLM
  • --system_prompt_file FILE / -pf FILE: Read prompt from file
  • --rule SPEC: Extract a rule from .claude/skills/topic.rules.md
  • --skill NAME: Use a skill's full SKILL.md file as prompt
  • --select SPEC: Process only lines matching a selection spec
  • --lint: Auto-format output with Prettier
  • --model MODEL: Which LLM to use (default: gpt-4)
  • --modify_in_place / -m: Edit file in place instead of creating new one

Hands-On Examples#

Example 1: Basic Text Transformation#

  • Start with simplest case: transform input text and print result

  • Create a sample file:

> cat > input.txt << 'EOF'
The quick brown fox jumps over the lazy dog.
It was a dark and stormy night.
The hero entered the room with caution.
EOF
  • Transform with a simple prompt:
> llm_cli.py -i input.txt -o - --system_prompt "Rewrite this in one sentence"
The quick brown fox leaped over a lazy dog during a dark, stormy night as the cautious hero entered the room.
  • -o - prints to stdout instead of writing to file

Example 2: Edit a File in Place#

  • Process a file and save result back to itself:
> llm_cli.py -i input.txt --system_prompt "Make this more formal" -m
  • Check result:
> cat input.txt
A swift, auburn canine traversed an obstacle formed by a sluggish animal.
It was an exceptionally dark evening accompanied by severe meteorological conditions.
The protagonist proceeded cautiously into the chamber.
  • -m flag modifies file in place without separate output file

Example 3: Apply a Skill From Claude Code#

  • If you have a skill in .claude/skills/, apply it directly:
> llm_cli.py -i code.py --skill coding.fix_docstring -m
  • This applies entire coding.fix_docstring skill to your file
  • Skills more powerful than inline prompts: contain detailed instructions and examples

Example 4: Transform Only Part of a File#

  • Extract a chunk, transform it, reassemble. Useful when only specific lines need changes

  • Create a sample file with markers:

> cat > slides.txt << 'EOF'
## Slide 1: Introduction

This is a basic intro slide.
It needs better content.

## Slide 2: Main Topic

The main point is important.
But unclear.

## Slide 3: Conclusion

Wrap up the presentation.
Make it memorable.
EOF
  • Transform only Slide 2 using line numbers:
> llm_cli.py -i slides.txt --select 6:8 --system_prompt "Improve clarity" -m
  • --select 6:8 processes only lines 6-8, leaving rest untouched

Example 5: Apply a Rule with Auto-Linting#

  • Rules are snippets from a skill file. Extract one and apply with auto-formatting:
> llm_cli.py -i README.md --rule '.claude/skills/markdown.rules.md:42:# Fix Bold Labels' --lint -m
  • Rule specified as file:line_number:rule_name. --lint runs Prettier on output for consistent formatting

Tips and Gotchas#

Tip 1: Use Pipes for Chaining#

  • llm_cli integrates with Unix pipes: transform output from one tool into input for another
> cat raw_notes.txt | llm_cli.py -i - -o - --system_prompt "Summarize in 3 bullet points"

Tip 2: Estimate Output Size for Large Files#

  • By default, llm_cli shows a progress bar but doesn't know output size
  • Help it:
> llm_cli.py -i large_file.py --system_prompt "Add type hints" --expected_num_chars 50000
  • Or let it auto-estimate:
> llm_cli.py -i large_file.py --system_prompt "Add type hints" --progress_bar

Tip 3: Use Dry-Run to Preview#

  • Before modifying files, dry-run to see what would happen:
> llm_cli.py -i important_file.py --system_prompt "Refactor" --dry_run
  • Shows LLM params without calling API or modifying files

Gotcha 1: Stdin Requires Output Specification#

  • When reading from stdin with -i -, must specify an output:
> echo "text" | llm_cli.py -i - -o output.txt  # OK
> echo "text" | llm_cli.py -i -                 # ERROR
  • Use -o - to print to stdout:
> echo "text" | llm_cli.py -i - -o -

Gotcha 2: Only One Prompt Option at a Time#

  • Use -p (inline), -pf (from file), --rule (from rules), or --skill (full skill), not multiple:
> llm_cli.py -i file.txt -p "Fix it" --rule '.claude/skills/my.rules.md:10:Rule'  # ERROR

Gotcha 3: Linting Only Works with Markdown#

  • --lint flag currently formats output as Markdown with Prettier. If working with code files, linting won't apply:
> llm_cli.py -i code.py --system_prompt "Add comments" --lint  # Linting won't affect Python

Next Steps#

  • Read full docs in dev_scripts_helpers/llms/README.md
  • Explore existing skills in .claude/skills/ to see available transformations
  • Create custom rule for repetitive tasks (e.g., "Fix grammar in slide decks")
  • Integrate llm_cli into Makefile or shell script for batch processing
  • Experiment with different models using --model openrouter/anthropic/claude-opus-4.6

Advanced: Combining with Other Tools#

  • Use llm_cli alongside other helpers:

  • Refactor code and run tests:

    > llm_cli.py -i module.py --system_prompt "Refactor for readability" -m && python -m pytest module_test.py

  • Fix a specific function in a file:

    > llm_cli.py -i file.py --select "def my_func" --skill coding.fix_docstring -m

  • Process multiple files in a loop:

    > for file in *.md; do llm_cli.py -i "$file" --skill markdown.fix_bullet_points -m; done

  • llm_cli bridges terminal and LLM capabilities. Use it whenever you write manual prompts to fix or improve text: that's a sign the transformation should be automated