Examples

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

Basic tool usage

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

# Python one-liners
kapsl python -c "import sys; print(sys.version)"
kapsl [email protected] -c "print('hello')"

# Search tools
kapsl rg "TODO" .
kapsl 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 ---"
  kapsl python@$v -c "import sys; print(sys.version)"
done

Python with packages

# Inline packages
kapsl [email protected]:requests,jinja2 -c "import requests; print(requests.__version__)"

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

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

Portable shebang scripts

#!/usr/bin/env -S kapsl [email protected]: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 kapsl installed can run it without setup.

Node.js

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

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

Git operations

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

Network tools

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

CI/CD

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

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

- name: Lint
  run: kapsl [email protected]:ruff ruff check src/

Security examples

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

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

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

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

Platform override

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

kapsl --platform linux/arm64 python --version

Kubernetes

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