Skip to content

arg-sh/libs

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

38 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

argsh logo
argsh libs

Stargazers Releases

 

Official plugin libraries for argsh — installable via argsh lib add. Each library is both an importable module and a standalone CLI executable.

 

📦 Install

# Add a library to your project
argsh lib add jaml

# Or install globally
argsh lib add --global jaml

Libraries install to .argsh/libs/ (project-local) or ~/.local/share/argsh/libs/ (global). The import system resolves them automatically.

 

📚 Libraries

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

 

🧪 Usage

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

 

⚡ Native Builtins (Rust)

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::each

The 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)

 

🗂️ Structure

<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

 

🔧 Development

# 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

 

🚀 Publishing

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

 

📜 License

MIT — see LICENSE.

 

Copyright © 2026-present Jan Guth

About

Official plugin libraries for argsh — installable via `argsh lib add`

Topics

Resources

Stars

Watchers

Forks

Packages

 
 
 

Contributors