search

shannah / shellmarks

GUI for shell scripts
37 stars 8 forks source link

readme

Shellmarks

A documentation and GUI generator for your custom shell scripts.

Synopsis

Shellmarks is a productivity tool for developers who create lots of custom shell scripts, but can't remember where they saved them, how to use them, or both. It provides:

  1. A GUI markup language (using TOML) that can be embedded directly into a shell script. When the script is run using shellmarks, it will display a dialog to the user, prompting them to provide some environment variables. Currently the dialog can contain text fields, file selection fields, buttons, and checkbox fields, but more field types can easily be added as needs be.
  2. A searchable catalog of all of your installed scripts. The catalog includes documentation for each script, as well as buttons to Run, Edit, Clone, and Delete them.

Watch Screencast Intro (12 minutes)

License

MIT

Features

Hello World

The following is a simple script that prints hello ${name}, where ${name} is provided by the user.

#!/bin/bash
echo "Hello ${name}"
exit 0
---
[name]
  type="text"
  label="Please enter your name"
  required=true

If you run this script using bash directly, it will simply output:

Hello

This is because the ${name} environment variable is not set.

If you, instead, run this with shellmarks, it will prompt the user to enter their name in a GUI dialog:

Hello World

If the user enters "Steve" into the text field, and presses "Run", they'll see the following output in the console.

Hello Steve

More Advanced Example

The following script is a more advanced example that involves a few more field types. The script is one that I wrote to extract the entitlements and provisioning profile information from an IPA file. I use this script quite frequently to help support users of Codename One when they run into issues relating to entitlements and certificates on their iOS apps.

#!/bin/bash
file_extracted="${file}-extracted"
if [ ! -d "${file_extracted}" ]; then
    if [ ! -f "$file" ]; then
        echo "Cannot find file $file"
        exit 1
    fi
    mkdir "${file_extracted}"
    cp "$file" "${file_extracted}/App.zip"
    cd "${file_extracted}"
    unzip App.zip
else
    cd ${file_extracted}
fi
appname=$(ls Payload | grep '\.app$')
if [ ! -z "$showEntitlements" ]; then
    codesign -d --entitlements :- "Payload/${appname}"
fi
if [ ! -z "$showProvisioningProfile" ]; then
    security cms -D -i "Payload/${appname}/embedded.mobileprovision"
fi
exit 0
---
__title__="IPA Entitlements"
__description__='''
This script will print out the entitlements and provisioning profile for given .ipa file.

See https://developer.apple.com/library/archive/qa/qa1798/_index.html[Apple Tech Article] for more information.
'''
[file]
    type="file"
    label="Select ipa file"
    required=true
    help="Select the .ipa file that you wish to inspect."

[showEntitlements]
    type="checkbox"
    label="Show Entitlements"
    default="true"
    help="Check this to show the ipa entitlements."

[showProvisioningProfile]
    type="checkbox"
    label="Show Provisioning Profile"
    default="true"
    help="Check this to show the ipa provisioning profile details."

If this script is in a file named ipa-tools.sh, then you can run it via:

shellmarks ipa-tools.sh

The GUI dialog looks like:

ipa-tools

Script Structure

Shell scripts written for shellmarks are just regular shell scripts. At the end of the script you simply add a section with:

exit 0
---
... Your GUI definitions here in TOML format

Some notes:

We add exit 0 so that the script exits before reaching the shellmarks GUI configuration. This ensures that the script will remain compatible with the default shell iterpreter (e.g. bash).

The --- serves as a dividing line between the script content, and the shellmarks config.

The contents of this tag will be interpreted as TOML.

Script Catalog

If you run shellmarks with no arguments, it will open up the script catalog with all of the scripts that you've installed into shellmarks.

Each installed script in the catalog is rendered with an entry that allows you to run, edit, delete, or clone it.

Script Catalog

Installation

Installation requires that you have NodeJS installed, because the installer uses npm.

Download NodeJS here

Then, open a terminal, and enter:

sudo npm install -g shellmarks

NOTE: On windows you may not require the "sudo" part. Just npm install -g shellmarks

On Mac and Linux the sudo is required to give npm access to install it globally.

Requirements

Shellmarks should run on any modern Windows, Linux, or Mac system.

Documentation

Credits

Shellmarks was created by Steve Hannah. It owes a great deal to the Java open source eco-system, as its development would have been much more difficult without the mature set of Maven dependencies.

Notable dependencies:

See the pom.xml file for a full list of dependencies.

jDeploy app signature: a68277ce4f5b15f1f374053a9ca5188d440e84fe725d2a3fcda45026c87f4127