vrksh

LLMs are probabilistic. The tools around them shouldn't be.

One CLI binary. Small composable tools. Zero silent failures.

vrksh (वृक्ष) is the Sanskrit word for tree. The project is vrksh. The command is vrk.

Shell pipelines that call LLMs break in quiet ways. A prompt exceeds the context window and the model silently truncates. A retry loop swallows errors. An API key leaks into logs. jq and awk were not designed for this failure mode.

vrksh is 26 Unix-style CLI tools in a single static binary. Each tool reads stdin, writes stdout, and uses exit codes that pipelines can trust: 0 for success, 1 for runtime errors, 2 for usage errors. JSONL is the native interchange format. Large inputs stream through bufio.Scanner, not io.ReadAll, so a 10GB log file won't OOM your agent.

Homebrew

brew tap vrksh/vrksh
brew install vrk

Binary install

curl -fsSL https://vrk.sh/install.sh | sh

From source

go install github.com/vrksh/vrksh@latest

Every tool accepts input as a positional argument or via stdin:

vrk epoch '+3d'              # positional
echo '+3d' | vrk epoch      # stdin - same result

Gate a prompt by token budget, then send to an LLM:

cat document.txt | vrk tok --check 8000 | vrk prompt --system 'Summarize this'

If the input exceeds 8000 tokens, tok exits 1 and the pipeline stops before the API call.

Redact secrets, validate structure, log the result:

cat debug.log \
  | vrk mask \
  | vrk assert --contains 'ERROR' \
  | vrk emit --level error --tag incidents

Fetch a page, extract links, sample 10, hash the result:

vrk grab 'https://example.com' \
  | vrk links --bare \
  | vrk sip --first 10 \
  | vrk digest

Generate a run ID, store it, use it across pipeline stages:

vrk kv set run_id "$(vrk moniker --seed 42)"
vrk kv get run_id

All tools follow the same contract:

• Data goes to stdout. Errors go to stderr.
• Exit 0 = success. Exit 1 = runtime error. Exit 2 = usage error.
• When --json is active, errors go to stdout as {"error":"...","code":N} and stderr stays empty.

vrk --manifest          # JSON list of all tools
vrk --skills            # full reference: flags, exit codes, gotchas
vrk --skills tok        # reference for a single tool
vrk mcp                 # MCP server for tool discovery (stdio JSON-RPC)
vrk <tool> --help       # per-tool usage

Create direct symlinks so you can run tok instead of vrk tok:

vrk --bare tok jwt epoch     # creates symlinks in /usr/local/bin
vrk --bare --list            # show existing symlinks
vrk --bare --remove tok      # remove a symlink

Bash:

vrk completions bash > ~/.bash_completion.d/vrk
source ~/.bash_completion.d/vrk

Zsh:

vrk completions zsh > "${fpath[1]}/_vrk"

Fish:

vrk completions fish > ~/.config/fish/completions/vrk.fish

• You need signature verification on JWTs. vrk jwt is an inspector, not a validator.
• You want a chat interface. vrk prompt is a pipeline tool with temperature 0 by default.
• You need exact token counts for Claude. tok uses cl100k_base, which is exact for GPT-4 and ~95% accurate for Claude.
• You want a framework. vrksh is CLI filters and pipes, not an SDK.

• Quickstart - zero to working pipeline in five minutes
• Tool reference - flags, exit codes, examples for all 26 tools
• Recipes - multi-tool pipeline patterns
• Environment variables - API keys and runtime config