spellbook 0.3.0-alpha

spellbook is a lightweight CLI command manager written in Go. It allows you to save complex shell commands as parameterized templates ("spells") and execute them instantly with custom arguments.

---

Table of contents

• Features
• Building from Source
• Configuration
• Usage
• Upcoming Features
• Known issues

---

Features

• Pure Go & CGO-Free: Built with SQLite (modernc.org/sqlite), resulting in a single portable binary without external dependencies.
• Templating: Define dynamic parameters inside commands using {{ .variable }} syntax.
• Tags & Descriptions: Organize and document your command collection.

---

Building from Source

Prerequisites

• Go 1.22 or higher

Build Steps

# Clone the repository
git clone https://github.com/abelith/spellbook.git
cd spellbook

# Build static binary
CGO_ENABLED=0 go build -ldflags="-X main.Version=0.3.0-alpha" -o spellbook .

# Move to bin directory (for Linux/macOS)
mv spellbook $(go env GOPATH)/bin/

---

Configuration

Env

• SPELLBOOK_DB_PATH: database file path (example: /spellbook/spellbook.db)

---

Usage

• Use spellbook help to list commands
• Use spellbook [command] --help to get info on specific command

List spells

Use spellbook to list prepared spells

Searching through your spellbook

Use spellbook search -n name -c cmd -d desc -t tags [query] to find spells matching the query

Name	Shorthand	Description
--name	-n	Part of a spell name to search for
--cmd	-c	Part of a spell command template to search for
--desc	-d	Part of a spell description to search for
--tags	-t	Comma-separated list of tags to search for
query		General pattern to search for through spell names, descriptions and commands

At least one of the parameters above is required

Add new spell

Use spellbook add -n name -t tags -d desc -- [command] to add a new spell

Name	Shorthand	Description	Required
--name	-n	Spell name	Yes
--tags	-t	Comma-separated list of spell tags	No
--desc	-d	Spell description	No
command		Spell command template	Yes

It is advised to escape the command with single or double quotes

Remove a spell

Use spellbook rm [spell_name] to remove a spell

• spell_name is a name of a spell required

Name	Description	Required
spell_name	Spell name	Yes

Casting a spell

Use spellbook [spell_name] key=val key=val to cast a spell

Name	Description	Required
spell_name	Spell name	Yes
key=val	key=val formatted parameters	No

Examples

For example, if you add a spell like this

spellbook add -n my-spell -t net,http -d my-desc -- curl 127.0.0.1

To use it, run this command

spellbook my-spell

Or you may want to use dynamic parameters like this

spellbook add -n my-spell -t net,http -d my-desc -- curl {{.target}}

And cast the spell like this

spellbook my-spell target=127.0.0.1

---

Upcoming Features

• Export/import spellbooks
• Namespaces

Known issues

• KEY=VAL my-cmd inline environment variable syntax is currently not supported (will fail with executable file not found in $PATH)
• Shell operators (such as |, >>, etc.) are not yet supported