corgi

README

Corgi - CLI workflow manager

Corgi is a command-line tool that helps with your repetitive command usages by organizing them into reusable snippet. See usage by simply running corgi or corgi --help

Current version: v0.2.4

Examples

Create a new snippet to automate the commands you run repetitively

Execute an existing snippet knowing what command is being run and its output

Table of Contents

• Installation
  • Install corgi
    • Homebrew
    • Binary
    • Build from scratch
  • Install a fuzzy-finder
• Features
  • Create a snippet
    • Create from command history
    • Define template fields in snippet
    • Multi-line command support
  • List snippets
  • Execute a snippet
    • Use default value without prompt
    • Select steps to execute
    • Interactive snippet selection
  • Edit a snippet
  • Describe a snippet
  • Share snippets
    • Import snippets
    • Export snippets to JSON and SHELL script
  • Remove a snippet
  • Configure corgi
    • Choose your favorite text editor
    • Choose your favorite fuzzy matcher
    • Choose the directory to store all your snippets
• Roadmap
• Note

Installation

Install corgi

Homebrew

Run brew install drakew/corgi/corgi and you are good to roll!

Upgrade Instruction

Upgrade corgi from an old version by doing brew upgrade drakew/corgi/corgi

If you saw this error Error: corgi <old version> is already installed during installation or upgrade. Run the following commands to re-install:

brew unlink corgi && brew uninstall corgi && brew install drakew/corgi/corgi

Binary

To install the binary directly:

1. Download the latest package tarball from releases based on your system (currently support linux and macOS).
2. Unzip the package with tar -xzvf <downloaded tar.gz file>
3. cd <directory extracted>, and chmod a+x ./corgi to make sure execution bit is turned.
4. ln -s $(pwd)/corgi <your bin folder>/corgi to create a softlink
5. Start rolling with corgi

Build from scratch

If you would like to try some pre-release features, try building the executable from scratch:

1. Install the most recent version of go language on your system
2. go get github.com/DrakeW/corgi
3. go install github.com/DrakeW/corgi

Install a fuzzy-finder

corgi will enable interactive selection if you install a fuzzy finder, the currently supported two are fzf and peco.

Features

To view usage of a specific action, run corgi <action> --help

Create a snippet

corgi provides an interactive CLI interface to create snippet, and you can start by running

corgi new  

NOTE: To create a snippet, corgi will need access to your command history file, which is being set by the $HISTFILE env variable. If $HISTFILE is not explicitly set, corgi will try to infer its location based on currently supported shell types (bash, zsh and fish).

Create from command history

If you would like to quickly combine the last couple commands you just executed into a snippet, you could also run

corgi new --last <number of commands to look back>  

Define template fields in snippet

Furthermore, you could also add template fields (with or without default value) to command of a step and reuse the same field, for example:

tar -xzf <project>.tgz && scp <project> <user=ec2-user>@<ec2-instance-address>:~/

And you will be prompted to enter values for those fields when the snippet executes. The value set for the same field name will be applied to all steps in a snippet, so you don't have to enter multiple times.

Also if you have field with multiple default values, the latest appearance will take precedence over the previous values.

Multi-line command support

corgi also supports multi-line command where each line has trailling character "\". For example,

Step 1:
Command: docker run -p 2181:2181 -p 9092:9092 \
> --env ADVERTISED_HOST="172.17.0.1" \
> --env ADVERTISED_PORT=9092 \
> --env NUM_PARTITIONS="2" \
> --env TOPICS="topic1,topic2" \
> spotify/kafka

List snippets

To view all snippets saved on your system, run

corgi list  

Execute a snippet

To execute a snippet, simply run

corgi exec [<title of the snippet>] [--use-default] [--step <step range>]

Your commands will run smoothly just as they were being run on a terminal directly, and any prompt that asks for input (for example, password prompt when you ssh into a remote server) will work seamlessly as well.

Also note that if you run cd command in one of the steps, the current working directory will not change for subsequent steps. But you can always put cd <target dir> && <do something else> to get commands executed inside of your target directory.

Use default value without prompt

if --use-default is set, then the snippet will execute without asking explicitly for user to set a value for template fields defined, but if there are missing default values, the snippet will fail fast and tell you what fields are missed.

Select steps to execute

You can use the --step (or -s) flag to specify the steps (starting from index 1) you want to execute, for example

--step 3    # will only execute step 3
--step 3-5  # will execute step 3 to 5
--step 3-   # will execute step 3 to the last step

This can be particularly useful when your workflow fail midway, but you don't want to start the whole workflow from step 1 again.

Interactive snippet selection

This feature will guide you through the darkness if you don't have the title of your snippet memorized. Simply type

corgi exec [with or without options]

and you will be presented an interactive interface to fuzzy-find your snippet (To enable this feature, see installation instruction)

Edit a snippet

To edit a snippet, run

corgi edit [<title of the snippet>]  

You'll be able to edit the snippet json file directly with your preferred editor (configurable via corgi config command, details see below)

Furthermore, edit also provides fuzzy finding capabilities when you omit the snippet title.

Describe a snippet

To see the details of a snippet, you can run (without title will yield interactive title selection)

corgi describe [<title of the snippet>]

And it will print out each step of the snippet so that you don't have to memorize them.

Share snippets

Import snippets

If someone shares his/her snippet json file(s) with you, you can import it by running

corgi import <snippet json file 1> [<snippet json file 2>...]

Export snippets to json and shell script

And similarly, if you already have a workflow defined in a snippet, you can easily share it by exporting via (without title will yield interactive title selection)

corgi export [<title of the snippet>] [-o <output file path>] [-t <file type: json|shell>]

By default a json file will be exported, but you can also export a shell script that can run in an environment where corgi is not installed, while still having the same organized step-by-step corgi experience. To export snippet to a shell script, just do

corgi export [<title of the snippet>] -t shell

Remove a snippet

You can remove a snippet by running (without title will yield interactive title selection)

corgi remove [<title of the snippet>]

Configure corgi

You can configure corgi to use your existing tools or services and make it more usable (and fluffy)

Choose your favorite text editor

You can configure your text editor choice (default is vim) for snippet editing, simply run

corgi config --editor <editor of your choice, eg. vim, subl, atom, code etc>

Choose your favorite fuzzy matcher

You can also choose your favorite filter tool (default is 'fzf') for interactive snippet selection by running

corgi config --filter-cmd <fuzzy finder like fzf, peco etc>

Choose the directory to store all your snippets

You can configure the path to store all your snippets by running

corgi config --snippets-dir <path, eg. ~/Dropbox/my_corgi_snippets>

This way, you can use online file sync/backup services like Dropbox, Box to make your snippet available across all your devices.

Roadmap

Here are some features that are currently on the roadmap:

1. Support concurrent execution of steps
2. Support remote server configuration, so that snippet can run seamlessly on a remote computer

Note

Corgi is inspired by Pet, and aims to advance Pet's command-level usage to a workflow level.