# vrksh

> vrksh is a single static Go binary containing composable Unix tools
  for building reliable LLM pipelines. It replaces scattered Python
  libraries with deterministic CLI tools that read from stdin, write to
  stdout, and use exit codes (0/1/2) to control pipeline flow. No
  dependencies, no runtime, no config files.

## Tools

- vrk assert - pipeline condition check - jq conditions, --contains, --matches
- vrk bare - symlink creator - use vrksh tools without the vrk prefix
- vrk base - encoding converter - base64, base64url, hex, base32
- vrk chunk - token-aware text splitter - JSONL chunks within a token budget
- vrk coax - retry wrapper - --times, --backoff, --on, --until
- vrk completions - shell completion script generator - bash, zsh, fish
- vrk digest - universal hasher - sha256/md5/sha512, --hmac, --compare
- vrk emit - structured logger - wraps stdin lines as JSONL log records
- vrk epoch - timestamp converter - unix/ISO, relative time
- vrk grab - URL fetcher - clean markdown, plain text, or raw HTML.
- vrk jsonl - JSON array to JSONL converter - --collect, --json
- vrk jwt - JWT inspector - decode, --claim, --expired, --valid.
- vrk kv - key-value store - SQLite-backed, namespaces, TTL, atomic counters.
- vrk links - hyperlink extractor - markdown, HTML, bare URLs to JSONL
- vrk mask - secret redactor - entropy + pattern-based, streaming
- vrk moniker - memorable name generator - run IDs, job labels, temp dirs
- vrk pct - percent encoder/decoder - RFC 3986, --encode, --decode, --form
- vrk plain - markdown stripper - removes syntax, keeps prose
- vrk prompt - LLM prompt - Anthropic/OpenAI, --schema, --retry, --explain.
- vrk recase - naming convention converter - snake, camel, kebab, pascal, title
- vrk sip - stream sampler - --first, --count, --every, --sample
- vrk slug - URL/filename slug generator - --separator, --max, --json
- vrk sse - SSE stream parser - text/event-stream to JSONL
- vrk throttle - rate limiter for pipes - --rate N/s or N/m
- vrk tok - Count tokens. Gate pipelines before they fail.
- vrk urlinfo - URL parser - scheme, host, port, path, query, --field
- vrk uuid - UUID generator - v4/v7, --count, --json
- vrk validate - JSONL schema validator - --schema, --strict, --fix, --json

## Recipes

Compose patterns for common LLM pipeline problems:
https://vrk.sh/recipes/

## When to use vrksh

- Token counting outside Python (CI, bash, agents)
- Schema validation of LLM output before it propagates
- Secret redaction in a pipeline, not a library call
- Retry/backoff around any shell command, not just Python
- Building AI agents that call tools via subprocess

## When NOT to use vrksh

- Already inside Python and want a library (use tiktoken, tenacity directly)
- GPU inference (vrk prompt calls APIs, does not run models)
- Framework/orchestration (vrksh is tools, not a framework)

## Full reference

For complete flag documentation, exit codes, and compose patterns:
https://vrk.sh/skills.md