Seira shell script framework context. Use when working with seira projects (.seirarc.json), shell script bundling, source dependency resolution, documentation generation, or seira CLI commands.
Seira is a Go-based shell script framework and bundler. It resolves source dependencies recursively (including ${VAR=default} variable expansion) and bundles scripts into standalone executables or reusable libraries.
Repository: https://github.com/Hayao0819/seira
# Bundle a shell script project into a standalone executable
seira bundle <input.sh> -o output.sh [--mode concat|tarball] [--type executable|library] [--minify] [--shebang /bin/bash]
# Install a bpkg-compatible package from GitHub
seira install <user/package[@version]> [--save]
# Install all dependencies from .seirarc.json
seira deps
# Resolve a package file path in deps/
seira path <owner/repo/path>
# Parse and display the AST of a shell script
seira ast <file.sh>
# Generate documentation from doc comments
seira doc [input.sh] [--format markdown|html] [-o output-file] [--title "Title"]
# Create a new seira project with scaffolding
seira new <project-name> [--library]
Standard shell script project. Entrypoint must declare a main() function. Output is a standalone executable script.
Reusable shell script library. No main() required. Output is a sourceable script containing only function definitions and side effects, without shebang or main "$@".
Set via "type": "library" in .seirarc.json or --type library CLI flag.
main "$@" is appended (executable type only).type is "library". Outputs a sourceable script with function definitions and side effects, plus metadata headers (# seira-library:, # seira-exports:).{
"entrypoint": "main.sh",
"shebang": "/bin/bash",
"mode": "concat",
"type": "executable",
"env": {},
"include": [],
"exclude": [],
"exports": [],
"dependencies": {
"user/package": "version"
},
"deps_dir": "deps"
}
| Field | Description | Default |
|---|---|---|
entrypoint | Main script file | - |
shebang | Shebang line for output | /bin/sh |
mode | Bundle mode (concat or tarball) | tarball |
type | Project type (executable or library) | executable |
env | Variables for source path resolution at build time | {} |
include | Extra files to bundle even if not discovered by resolver | [] |
exclude | Files to exclude from bundling | [] |
exports | Library mode: function names to export (empty = all) | [] |
dependencies | bpkg-style dependencies ("user/name": "version") | {} |
deps_dir | Dependencies directory | deps |
For executable projects, the entrypoint must declare a main() function. For library projects, no main() is needed.
#!/usr/bin/env bash
source lib/helper.sh
main() {
greet "World"
}
Seira resolves source and . commands recursively, building a dependency graph (DAG). It supports:
source ./lib/helper.shsource "${LIB_DIR:=lib}/helper.sh"At bundle time, seira scans the deps/ directory for seira library projects (directories with .seirarc.json containing "type": "library"). Their entrypoints are automatically added to the dependency graph — no source statement needed in consumer scripts. Library functions are inlined directly into the bundle output.
my-project/
.seirarc.json
main.sh # Can use str_upper() without sourcing anything
deps/
strutils/ # Installed via: seira install user/strutils
.seirarc.json # {"type": "library", "entrypoint": "index.sh"}
index.sh
lib/strutils.sh # str_upper(), str_lower()
Seira integrates with the bpkg ecosystem. Install packages from GitHub:
seira install bpkg/term # latest (master branch)
seira install user/[email protected] # specific version (git tag)
seira install user/pkg --save # save to .seirarc.json
seira deps # install all from config
Installed packages go to deps/<name>/ with symlinks in deps/bin/.
When installing a package that is a seira project (has .seirarc.json with dependencies), seira recursively installs those dependencies as well.
Every seira install and seira deps command records all installed dependencies' git commit hashes in .seira-lock.json:
{
"dependencies": {
"user/repo": {
"version": "v1.0",
"commit": "abc123def456..."
}
}
}
When seira deps runs with an existing lockfile, it uses the locked commit hashes to ensure reproducible installs.
Use seira_path in scripts to access files from installed packages:
cat "$(seira_path owner/repo/data.txt)"
source "$(seira_path bpkg/term/term.sh)"
The seira_path function is automatically embedded when bundling projects that have a deps/ directory.
Generate API documentation from shdoc-compatible doc comments in shell scripts.
# Markdown output (default)
seira doc main.sh -o docs/api.md
# HTML output with custom title
seira doc --format html --title "My API" -o docs/index.html
# Use entrypoint from .seirarc.json
seira doc -f html -o docs/api.html
| Tag | Level | Description |
|---|---|---|
@file | File | File name/title |
@brief | File | One-line summary |
@description | Both | Detailed description (multi-line) |
@param / @arg | Function | Parameter: @param $1 Description |
@option | Function | Flag/option: @option -f --force Description |
@stdin | Function | Expected stdin input |
@stdout | Function | What is written to stdout |
@return | Function | Return value description |
@exitcode | Function | Exit code: @exitcode 0 Success |
@example | Function | Code example block (multi-line) |
@set | Both | Global variable set: @set VAR Description |
@see | Function | Cross-reference to another function |
@internal | Function | Hide from generated documentation |
@section | File | Group subsequent functions under a heading |
@noargs | Function | Marker: function takes no arguments |
# @file strutils.sh
# @brief String utility functions
# @section Case Conversion
# @description Convert a string to uppercase
# @param $1 Input string
# @stdout The uppercased string
# @example
# str_upper "hello"
# # Output: HELLO
str_upper() {
echo "${1^^}"
}
The doc command resolves the full dependency graph and generates documentation for all files containing doc comments, ordered topologically.
my-project/
.seirarc.json # {"entrypoint": "main.sh", "mode": "concat"}
main.sh # Entrypoint (must have main() function)
lib/ # Library scripts (sourced by main.sh)
helper.sh
deps/ # Installed packages (via seira install)
bin/
term/
my-library/
.seirarc.json # {"type": "library", "entrypoint": "index.sh"}
index.sh # Sources internal modules
lib/
utils.sh # Exported functions