https://github.com/brsyuksel/shellican
manage, document, and share your shell scripts easily. a structured alternative to shell aliases.
https://github.com/brsyuksel/shellican
cli golang productivity script-management
Last synced: 5 months ago
JSON representation
manage, document, and share your shell scripts easily. a structured alternative to shell aliases.
- Host: GitHub
- URL: https://github.com/brsyuksel/shellican
- Owner: brsyuksel
- License: mit
- Created: 2025-12-08T23:33:06.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-12-10T21:25:42.000Z (6 months ago)
- Last Synced: 2025-12-11T00:42:00.354Z (6 months ago)
- Topics: cli, golang, productivity, script-management
- Language: Go
- Homepage:
- Size: 3.21 MB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# shellican
**shellican** (*shell-i-can*) is a powerful CLI for managing runnables (scripts/commands) in collections. It allows you to organize your shell scripts, define their environment, and run them easily.
[](https://goreportcard.com/report/github.com/brsyuksel/shellican)
## Why shellican?
**shellican** bridges the gap between simple shell aliases and complex Makefile setups.
- **Beyond One-Liners & Aliases**: Instead of cluttering your `.zshrc` or `.bashrc` with forgotten aliases, turn them into organized **runnables**. Keep your logic structured, named, and easy to find.
- **Shareable Workflows**: Stop saying "copy this script and change line 5". With **import / export**, you can package your collections and share them with friends or colleagues. They get a ready-to-run environment without manual editing.
- **Self-Documenting**: Every runnable supports a `help` description and a full `README`. You (and your team) will know exactly what a script does, even months later.
## Features
- **Collections & Runnables**: Organize your scripts into collections.
- **YAML Configuration**: Define runnables and environments in `collection.yml` and `runnable.yml`.
- **Environment Management**: Inject environment variables defined in configuration.
- **Hooks**: Pre (`before`) and post (`after`) hooks for runnables.
- **Shell Helper**: Generate shell wrappers for easy access.
- **Import/Export**: Share collections easily.
## Installation
### Go Install
```bash
go install github.com/brsyuksel/shellican@latest
```
### Binary Releases
You can download the pre-compiled binary for your operating system (macOS, Linux) from the [Releases](https://github.com/brsyuksel/shellican/releases) page.
## Usage
### Structure
Default storage location: `~/.shellican` (or `$SHELLICAN_HOME/.shellican`).
```
~/.shellican/
├── my-collection/
│ ├── collection.yml
│ ├── script-a/
│ │ └── runnable.yml
│ └── script-b/
│ ├── runnable.yml
│ └── main.sh
```
### Commands
- **New Collection**: `shellican new collection `
- **New Runnable**: `shellican new runnable `
- **Run**: `shellican run [args...]`
- **List**: `shellican list collections` or `shellican list runnables `
- **Show**: `shellican show collection ` or `shellican show runnable `
- **Create Shell Shortcut**: `shellican create-shell ` (creates `~/.local/bin/-shell`)
- **Import/Export**: `shellican import ` / `shellican export `
## Configuration
**collection.yml**
```yaml
name: "My Scripts"
help: "A collection of useful scripts"
readme: "README.md"
runnables:
- script-a
environments:
GLOBAL_VAR: "true"
```
**script-a/runnable.yml**
```yaml
name: "Script A"
help: "This script does something awesome"
readme: "README.md"
run: "./main.sh" # or "echo hello"
before: "echo 'Starting...'"
after: "echo 'Finished!'"
environments:
LOCAL_VAR: "123"
```
## Examples
- [dirty-vm](https://github.com/brsyuksel/dirty-vm) - A collection for creating and managing virtual machines with QEMU, cloud-init, and networking support.
## Contributing
1. Fork the repo
2. Create feature branch
3. Commit changes
4. Push and create PR
## License
MIT