Official plugin libraries for argsh — installable via argsh lib add. Each library is both an importable module and a standalone CLI executable.
# Add a library to your project
argsh lib add jaml
# Or install globally
argsh lib add --global jamlLibraries install to .argsh/libs/ (project-local) or ~/.local/share/argsh/libs/ (global). The import system resolves them automatically.
| Library | Description | Version | Builtin |
|---|---|---|---|
jaml |
Structured data access for YAML/JSON — batch read/write, array iteration, template rendering | 0.1.1 | libjaml.so |
shell-op |
Declarative shell-operator hooks — typed bindings, event dispatch, config generation | 0.1.0 | — |
Each library works two ways — as an imported module or as a standalone executable:
#!/usr/bin/env argsh
# As a library
import jaml
local domain version
jaml::get config.yaml \
domain=.spec.cluster.domain \
version=.spec.kubernetes.version
# Iterate arrays
while jaml::each config.yaml '.spec.nodes[]' \
name=.hostname role=.role
do
echo "${name} (${role})"
done
# Render templates
jaml::render deployment.tmpl.yaml config.yaml > deployment.yaml# As a CLI executable
argsh run jaml get config.yaml .spec.domain
argsh run jaml set config.yaml .spec.domain=domain
argsh run jaml each config.yaml '.items[]' name=.name
Libraries can ship optional Rust builtins for zero-subprocess performance. When the .so is available, the bash wrappers are bypassed entirely.
# Build the jaml builtin
cd jaml-builtin && cargo build --release
# Output: target/release/libjaml.so
# Load into bash
enable -f target/release/libjaml.so jaml::get jaml::set jaml::eachThe Cargo workspace compiles all builtin crates together, sharing dependencies (serde, serde_yaml, serde_json) across libraries.
| Crate | Output | Size |
|---|---|---|
jaml/builtin |
libjaml.so |
~512K |
shared |
(static lib) | — |
<lib>/
├── README.md # library documentation
├── argsh-plugin.yml # metadata (name, version, requires)
├── <lib> # executable argsh script (import + CLI)
├── <lib>.bats # tests
└── builtin/ # optional Rust builtin
├── Cargo.toml
└── src/lib.rs
# Run tests for a specific lib
argsh test jaml/jaml.bats
# Run all tests
argsh test */*.bats
# Build Rust builtins
cargo build --release
# Run Rust tests
cargo test
Libraries are distributed as OCI artifacts via ghcr.io/arg-sh/libs. Each file becomes a separate OCI layer with a typed media type.
# Publish from library directory
cd jaml && argsh lib publish
# Publish to a custom registry
argsh lib publish --registry harbor.mycompany.com/argsh
MIT — see LICENSE.
Copyright © 2026-present Jan Guth