feat: search cmd

chore: raw sql replaced with squirrel
fix: -n is now required for add cmd

CHANGELOG.md

@@ -1,22 +1,33 @@
 # Changelog
 
-## [Latest]
+All notable changes to this project will be documented in this file.
 
-## [0.2.1-alpha]- 2026-8-14
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0-alpha] - 2026-08-15
+
+### Added
+- `search` command
+- `-v` and `--version` flags for root command
+
+### Changed
+- Switched from raw sql to sql builder for easier dynamic query construction and easier maintenance 
+
+### Fixed
+- Now `--name` parameter for `add` command is required
+
+## [0.2.1-alpha] - 2026-08-14
 
 ### Fixed
 - Prevented creating spells with reserved names
 - Improved error messages
 
-## [Unreleased]
-
 ## [0.2.0-alpha] - 2026-08-08
 
 ### Added
 - Configuration options
 
-## [Unreleased]
-
 ## [0.1.0-alpha] - 2026-08-04
 
 ### Added

README.md

@@ -1,4 +1,4 @@
-# spellbook 0.2.1-alpha
+# 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.
 
@@ -10,6 +10,7 @@
 - [Configuration](#configuration)
 - [Usage](#usage)
 - [Upcoming Features](#upcoming-features)
+- [Known issues](#known-issues)
 
 ---
 
@@ -34,7 +35,7 @@ git clone https://github.com/abelith/spellbook.git
 cd spellbook
 
 # Build static binary
-CGO_ENABLED=0 go build -o spellbook .
+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/
@@ -45,7 +46,7 @@ mv spellbook $(go env GOPATH)/bin/
 ## Configuration
 
 ### Env
-- `SPELLBOOK_DB_PATH`: db location (example: `/spellbook/spellbook.db`) 
+- `SPELLBOOK_DB_PATH`: database file path (example: `/spellbook/spellbook.db`) 
 
 ---
 
@@ -58,28 +59,56 @@ mv spellbook $(go env GOPATH)/bin/
 
 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
+Use `spellbook add -n name -t tags -d desc -- [command]` to add a new spell
-- `-n` or `--name` is a name of a spell
+
-- `-t` or `--tags` is a comma-separated list of spell tags
+| Name      | Shorthand | Description                        | Required |
-- `-d` or `--desc` is a short description of spell
+|-----------|-----------|------------------------------------|----------|
-- `command` is an actual spell template
+| `--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
+- `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` to cast a spell
+Use `spellbook [spell_name] key=val key=val` to cast a spell
-- `spell_name` is a name of a spell
+
-- `key=val` are key/value arguments
+| Name         | Description                  | Required |
+|--------------|------------------------------|----------|
+| `spell_name` | Spell name                   | `Yes`    |
+| `key=val`    | key=val formatted parameters | `No`     |
 
 ### Examples
 
-Said, you have added a spell like this
+For example, if you add a spell like this
 
 ```shell
 spellbook add -n my-spell -t net,http -d my-desc -- curl 127.0.0.1
@@ -106,5 +135,8 @@ spellbook my-spell target=127.0.0.1
 ---
 
 ## Upcoming Features
-- Search to navigate your spell book
 - 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`)

cmd/main.go

@@ -16,6 +16,9 @@ import (
 	"syscall"
 )
 
+// Version is set on build via -ldflags
+var Version = "dev"
+
 func handleErr(err error) {
 	if err != nil {
 		_, _ = fmt.Fprintln(os.Stderr, err)
@@ -41,7 +44,7 @@ func main() {
 
 	app := application.NewApplication(&caster.SpellCaster{}, repo, repo)
 
-	c := cli.NewCLI(app)
+	c := cli.NewCLI(Version, app)
 
 	if err := c.Run(ctx); err != nil {
 		os.Exit(1)

internal/controllers/cli/add.go

@@ -13,6 +13,7 @@ var reservedCommands = map[string]struct{}{
 	"rm":         {},
 	"help":       {},
 	"completion": {},
+	"search":     {},
 }
 
 func NewAddCommand(app Application) *cobra.Command {
@@ -34,6 +35,11 @@ func NewAddCommand(app Application) *cobra.Command {
 			}
 
 			spell.Spell = strings.Join(args, " ")
+
+			if spell.Name == "" {
+				return fmt.Errorf("%w: --name is missing", errors.ErrInsufficientArgs)
+			}
+
 			return app.AddSpell(ctx, spell)
 		},
 	}

internal/controllers/cli/cli.go

@@ -18,11 +18,12 @@ type CLI struct {
 	root *cobra.Command
 }
 
-func NewCLI(app Application) *CLI {
+func NewCLI(ver string, app Application) *CLI {
-	root := NewRootCmd(app)
+	root := NewRootCmd(ver, app)
 	root.AddCommand(
 		NewAddCommand(app),
 		NewRmCommand(app),
+		NewSearchCmd(app),
 	)
 
 	return &CLI{

internal/controllers/cli/root.go

@@ -81,7 +81,7 @@ func printTable(cmd *cobra.Command, spells []models.Spell) error {
 	return nil
 }
 
-func NewRootCmd(app Application) *cobra.Command {
+func NewRootCmd(ver string, app Application) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "spellbook",
 		Short: "CLI tool to store, manage and execute command templates",
@@ -90,6 +90,7 @@ It allows you to save complex shell commands as parametrized templates (spells)
 and execute them instantly with custom arguments from anywhere in your terminal`,
 		RunE:    rootCmd(app),
 		Args:    cobra.ArbitraryArgs,
+		Version: ver,
 	}
 
 	return cmd

internal/controllers/cli/search.go

@@ -0,0 +1,47 @@
+package cli
+
+import (
+	"fmt"
+	"github.com/abelith/spellbook/internal/errors"
+	"github.com/abelith/spellbook/internal/models"
+	"github.com/spf13/cobra"
+)
+
+func NewSearchCmd(app Application) *cobra.Command {
+	query := models.SearchQuery{}
+
+	cmd := &cobra.Command{
+		Use:   "search [query]",
+		Short: "Search for spells",
+		Long:  "WIP",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			ctx := cmd.Context()
+
+			if query.IsEmpty() {
+				return errors.ErrEmptyQuery
+			}
+
+			if len(args) > 0 {
+				query.Text = args[0]
+			}
+
+			spells, err := app.GetSpells(ctx, query)
+			if err != nil {
+				return err
+			}
+
+			if len(spells) < 1 {
+				return fmt.Errorf("%w: spells", errors.ErrNotFound)
+			}
+
+			return printTable(cmd, spells)
+		},
+	}
+
+	cmd.Flags().StringVarP(&query.Name, "name", "n", "", "Spell name")
+	cmd.Flags().StringVarP(&query.Command, "cmd", "c", "", "Spell command template")
+	cmd.Flags().StringVarP(&query.Description, "desc", "d", "", "Spell description")
+	cmd.Flags().StringSliceVarP(&query.Tags, "tags", "t", nil, "Spell tags")
+
+	return cmd
+}

internal/errors/errors.go

@@ -7,4 +7,6 @@ var (
 	ErrInsufficientArgs = fmt.Errorf("mandatory args are missing")
 	ErrFailedToCast     = fmt.Errorf("failed to cast spell")
 	ErrNoDBProvided     = fmt.Errorf("no db provided")
+	ErrNotFound         = fmt.Errorf("not found")
+	ErrEmptyQuery       = fmt.Errorf("empty search query")
 )

internal/models/methods.go

@@ -0,0 +1,12 @@
+package models
+
+func (sq *SearchQuery) IsEmpty() bool {
+	isEmpty := sq.Text == "" &&
+		sq.Name == "" &&
+		sq.Command == "" &&
+		sq.Description == "" &&
+		len(sq.Tags) < 1 &&
+		sq.Cursor == 0 &&
+		sq.Limit == 0
+	return isEmpty
+}