Examples

A grab-bag of one-liners. For a structured walkthrough of a language or framework — including how to get from boks npm install to plain npm install — see the Language Guides, and the runnable projects in boks-examples/ in the repository.

Basic tool usage

# JSON processing
echo '{"name":"boks","ok":true}' | boks jq '.name'
boks jq -r '.[] | .name' data.json

# Python one-liners
boks python -c "import sys; print(sys.version)"
boks python@3.12 -c "print('hello')"

# Search tools
boks rg "TODO" .
boks rg -l "FIXME" src/

Version testing

Test across multiple versions of the same runtime:

for v in 3.11 3.12 3.13 3.14; do
  echo "--- Python $v ---"
  boks python@$v -c "import sys; print(sys.version)"
done

Python with packages

# Inline packages
boks python@3.12:requests,jinja2 -c "import requests; print(requests.__version__)"

# From requirements.txt
boks -e @pip:requirements.txt python script.py

# With uv (faster installs)
boks -e @uv:requirements.txt python script.py

Portable shebang scripts

#!/usr/bin/env -S boks python@3.12:requests

import requests
r = requests.get("https://httpbin.org/get")
print(r.json()["headers"]["User-Agent"])

chmod +x fetch.py
./fetch.py

The script specifies its own Python version and dependencies. Anyone with boks installed can run it without setup.

Node.js

# Inline packages
boks node@18:marked -e "const {marked}=require('marked'); console.log(marked('# hi'))"

# From package.json
boks -e @npm:package.json node app.js

Git operations

boks --cap net git clone https://codeberg.org/marqvi/boks.git
cd boks
boks git log --oneline -5
boks git diff HEAD~1

Network tools

boks --cap net curl -s https://httpbin.org/ip | boks jq '.origin'
boks --cap net wget -qO- https://example.com

CI/CD

# GitHub Actions / Forgejo Actions
- name: Install boks
  run: curl -fsSL https://boks.sh/install | sh && echo "$HOME/.local/bin" >> $GITHUB_PATH

- name: Run tests
  run: boks --non-interactive -e @pip:requirements.txt python -m pytest tests/

- name: Lint
  run: boks python@3.12:ruff ruff check src/

Security examples

# Read-only by default — cannot write
boks python -c "open('x','w')"
# PermissionError: [Errno 30] Read-only file system: 'x'

# Grant write access
boks --cap rw python -c "open('x','w').write('ok')"

# No network by default
boks curl https://example.com
# curl: (6) Could not resolve host: example.com

# Grant network access
boks --cap net curl https://example.com

Platform override

Run Linux ARM64 binaries on an x86 machine (requires emulation):

boks --platform linux/arm64 python --version

Kubernetes

# Run a tool as a temporary pod
boks --k8s python --version
boks --k8s --namespace staging python script.py
boks --k8s --node worker-1 python diagnose.py