157 lines
4.9 KiB
Markdown
157 lines
4.9 KiB
Markdown
# 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
|