README

frameless

introduction

“frameless” is a framework to write command line programs. “frameless” allows you to write command line programs that are easy to read, and fun to write.

thus, “frameless” is two things: (1) a set of decisions focused around how command line programs should work; and (2) a node.js module that demonstrates those decisions

the main design goal behind “frameless” is to allow you to migrate your day-to-day scripts to the command line with minimal effort

“frameless” is designed with hackers in mind so all the internals are deliberately exported. this allows fellow developers to tailor behavior if they disagree with the decisions made by the maintainers of the “frameless” itself, as well as perform necessary customization in style and security

the best way to get a feel for “frameless” is to simply look at an node.js program that uses “frameless”. for example, you can check the usage examples listed in the project’s repository

“frameless” is free software, available under the apache open source license (v2). see the license for more information

basics

default options

command line programs are expected to respond consistently to options such as version, yes, raw, verbose, help, setup. “frameless” will perform all these operations and behave according to the principle of least surprise. you can check which options are reserved by printing frameless.reserved_options, and customize styles by overriding the style methods that correspond to the options

var frameless = require('frameless');

// assuming placement in `bin/` folder
frameless.version = require('../package').version;

frameless.main(function () {
  frameless.silly(frameless.reserved_options);
});

printing to the stdout is achieved with frameless methods named frameless.info, frameless.silly, frameless.err, and frameless.warn which behave as you would expect. a generic callback

prompt

“frameless” will ask for options that are required but were not provided at run time using a prompt

frameless.main('name', function (input) {
  frameless.info('hello ' + input.name);
});

if you run “frameless” without specifying --name alice “frameless” will prompt you for the name.

“frameless” prompt is built on top of the flatiron/prompt module. all the arguments to the main function (except the callback) are assumed to be either a string (i.e. a mandatory option) or an object that represents a flatiron/prompt option object

the confirmation prompt

“cli” will enable an “are you sure?” prompt if deliberately ask for it in your code

frameless.confirm(true);

this check can then be overridden by the end user by using the -y or --yes option

persisting options across different requests

“frameless” enables programs to save and reuse the options specified in a request by exposing the frameless.save function. calling this function with true will make frameless automatically record the options inputed in a dot file located in your home directory

frameless.save(true);

frameless.main('name', 'password', function (opts) {
  frameless.info(frameless.dotfile, 'dotfile');
  frameless.info(frameless.sensitive_options,  'sensitive');
});

special considerations are taken for saving options which are member of an internal array called frameless.sensitive_options. “frameless” will attempt to encrypt options that include any of the substrings listed in this array, using the frameless.cypher_type and frameless.key. “frameless” ships with a default key, but you are encouraged to change it in your program. “frameless” will also attempt to read the ~/.ssh/id_rsa private key and use it as an encryption key whenever possible

“frameless” allows you to select which options should be saved. the default is to save the option once you called the frameless.save method

frameless.save(true);

frameless.main('name',
  { name: 'password', required: true, save: false}, function (opts) {
  frameless.info(frameless.dotfile, 'dotfile');
  frameless.info(frameless.sensitive_options,  'sensitive');
});

router

tbd.

themes

internally “frameless” exposes methods that format output presented to user. please check the source code in the style section for a better understanding of all functions you can customize to your liking (e.g. frameless.PS1)

man pages

publishing your module with npm