Plugins

argsh supports plugin libraries that extend its functionality beyond the core. Plugins are installed per-project and imported like any other library. No external dependencies (such as yq) are required — argsh parses YAML configuration files with built-in pure-Bash helpers.

Quick start

# Search for available plugins
argsh search

# Add a plugin
argsh add jaml

# Use it
import jaml

local domain
jaml::get config.yaml domain=.spec.cluster.domain

How it works

Plugins are distributed as OCI artifacts or GitHub release tarballs. They install to your project's .argsh/libs/ directory and are resolved via the standard import system. A lockfile (.argsh.lock) records the exact OCI ref and digest for each installed library, enabling reproducible installs.

myproject/
├── .argsh.yaml          # declares dependencies
├── .argsh.lock          # pinned refs + digests (committed to VCS)
├── .argsh/
│   └── libs/            # installed plugins (gitignored)
│       └── jaml/
│           ├── jaml              # executable argsh script
│           └── argsh-plugin.yml
└── script.sh

Commands

Command	Description
argsh add <name>	Install a plugin
argsh add <name>@<version>	Install a specific version
argsh add --global <name>	Install to the global libs directory with lockfile tracking
argsh search [filter]	Search available plugins (substring match)
argsh list	List installed plugins
argsh list --global	List globally installed plugins
argsh remove <name>	Remove a plugin
argsh remove --global <name>	Remove a globally installed plugin
argsh install	Install all from .argsh.lock (or .argsh.yaml if no lockfile)
argsh update	Update all project libraries to latest versions
argsh update --global	Update all globally installed libraries
argsh publish	Publish the current directory as a plugin to an OCI registry

argsh search

Queries the GitHub API for releases from arg-sh/libs, grouped by library name with the latest version shown. An optional filter argument restricts output to matching names. Uses GITHUB_TOKEN / GH_TOKEN when available to avoid rate limits.

argsh search          # list all available plugins
argsh search jaml     # filter by name substring

argsh add --global

Installs a plugin to the global libs directory (${XDG_DATA_HOME:-$HOME/.local/share}/argsh/libs) instead of the project-local .argsh/libs/. Global installs are tracked in a separate lockfile at ${XDG_DATA_HOME:-$HOME/.local/share}/argsh/libs/.argsh-global.lock.

argsh add --global jaml

argsh install

Installs all libraries from the lockfile (.argsh.lock). When using the OCI pull path (Rust builtin), each entry's digest is verified — mismatches fail the install. The curl fallback path warns but cannot verify digests. If no lockfile exists, falls back to reading .argsh.yaml.

argsh install

argsh update

Re-fetches every library at its latest version and updates the lockfile. With --global, updates all globally installed libraries instead.

argsh update            # update project libraries
argsh update --global   # update global libraries

Project configuration

Declare dependencies in .argsh.yaml:

defaults:
  path_libs: .argsh/libs

registries:
  # argsh registry (ghcr.io/arg-sh/libs) is built-in
  myco:
    endpoint: harbor.mycompany.com/argsh

libs:
  argsh@jaml: ^0.1.0
  myco@k8s-utils: ^0.2.0

Import resolution

When you import jaml, argsh looks for it in this order:

1. Relative to caller — standard import path
2. Plugin libs — .argsh/libs/jaml/jaml
3. Bundled core — libraries/

Available plugins

Plugin	Description	Status
jaml	Structured YAML/JSON access	v0.1.0

Core vs plugins

Core libraries (is::, to::, string::, args, etc.) ship with argsh and are always available. Plugins are optional — install only what you need.

	Core libraries	Plugins
Location	libraries/*.sh	.argsh/libs/
Install	Built-in	argsh add
Docs	Library Reference	This section
Source	arg-sh/argsh	arg-sh/libs