# spellbook 0.5.0-beta

`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](#features)
- [Building from Source](#building-from-source)
- [Configuration](#configuration)
- [Usage](#usage)
- [Upcoming Features](#upcoming-features)
- [Known issues](#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](https://go.dev/) 1.22 or higher

### Build Steps

```shell
# 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.5.0-beta" -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

### Export spellbook

Use `spellbook export -f [format] -o [output]` to export your spellbook

| Name       | Shorthand | Description                                                                 |
|------------|-----------|-----------------------------------------------------------------------------|
| `--format` | `-f`      | Output format. Supported formats: `jsonl`                                   |
| `--output` | `-o`      | Output source. Leave empty to use `stdout` or provide with output file name |

### Import spellbook

Use `spellbook import -f [format] -i [input]` to import your spellbook

| Name       | Shorthand | Description                                                              |
|------------|-----------|--------------------------------------------------------------------------|
| `--format` | `-f`      | Input format. Supported formats: `jsonl`                                 |
| `--input`  | `-i`      | Input source. Leave empty to use `stdin` or provide with input file name |

### 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

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

To use it, run this command

```shell
spellbook my-spell
```

Or you may want to use dynamic parameters like this

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

And cast the spell like this

```shell
spellbook my-spell target=127.0.0.1
```

---

## Upcoming Features
- Namespaces
- More export/import formats