{"id":15608549,"url":"https://github.com/hypercubed/autocmdr","last_synced_at":"2025-04-28T11:46:12.341Z","repository":{"id":9394776,"uuid":"11258223","full_name":"Hypercubed/autocmdr","owner":"Hypercubed","description":"Task runner and commander.js app builder.","archived":false,"fork":false,"pushed_at":"2015-11-23T10:18:37.000Z","size":127,"stargazers_count":16,"open_issues_count":8,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-11T17:13:19.161Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Hypercubed.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-07-08T15:43:48.000Z","updated_at":"2021-12-28T16:24:22.000Z","dependencies_parsed_at":"2022-08-29T21:52:14.495Z","dependency_job_id":null,"html_url":"https://github.com/Hypercubed/autocmdr","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hypercubed%2Fautocmdr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hypercubed%2Fautocmdr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hypercubed%2Fautocmdr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hypercubed%2Fautocmdr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Hypercubed","download_url":"https://codeload.github.com/Hypercubed/autocmdr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251309088,"owners_count":21568744,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T05:21:23.202Z","updated_at":"2025-04-28T11:46:12.318Z","avatar_url":"https://github.com/Hypercubed.png","language":"JavaScript","funding_links":["https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=X7KYR6T9U2NHC"],"categories":[],"sub_categories":[],"readme":"autocmdr [![Build Status](https://secure.travis-ci.org/Hypercubed/autocmdr.png?branch=master)](https://travis-ci.org/Hypercubed/autocmdr) [![NPM version](https://badge.fury.io/js/autocmdr.png)](http://badge.fury.io/js/autocmdr) [![Code Climate](https://codeclimate.com/github/Hypercubed/autocmdr.png)](https://codeclimate.com/github/Hypercubed/autocmdr)\n=============\n\n[![NPM](https://nodei.co/npm/autocmdr.png?downloads=true)](https://nodei.co/npm/autocmdr/)\n\nautocmdr is a both a command line interface for running tasks and a set of components for building CLIs.  autocmdr is designed to work with [generator-commander](https://github.com/Hypercubed/generator-commander) to enable easily building of commander.js command line apps. \n\nautocmdr itself was partially built using autocmdr/[generator-commander](https://github.com/Hypercubed/generator-commander).  Please also see the obligatory todo app here [todo-md](https://github.com/Hypercubed/todo-md) (Works with GFM task lists!!).\n\nWarning... The usage is changing rapidly.  I'm working towards a [0.1.0](https://github.com/Hypercubed/autocmdr/issues?milestone=1) release soon.  Feedback is welcome.\n\n# Introduction\n\nThe diverse ecosystem of modules available for node.js through npm make it a great tool for the rapid development of a variety of tools including useful command line interfaces.  [Commander.js](https://github.com/visionmedia/commander.js) from [visionmedia](https://github.com/visionmedia) is an excellent node.js command line parser that, using a natural, clean and highly readable syntax, allows for easy development of versatile self-documenting command line interfaces (CLIs).  However, a command line parser is just the beginning.  Many CLIs will inevitably need to include additional components such as debug logging, configuration management, and other CLI type actions.  autocmdr is a command line tool that implements these modules, so you don't have too.  In fact using the autocmdr executable all you need to do is add commands to your local directory and autocmdr will load them automatically along with a reasonable set of additional support components.  Using autocmdr along with [yo](https://github.com/yeoman/yo) and [generator-commander](https://github.com/Hypercubed/generator-commander) provides tools for easily building command components and full CLI applications.  This includes converting a detached set of command components into a independent CLI application that uses autocmdr (along with all it's support modules) as a library.\n\n## Philosophy and Workflow\n\n**Building excellent command tools using excellent tools.  Using the right tool for the right task**\n\n[commander.js](https://github.com/visionmedia/commander.js) is an node.js command line parser from [visionmedia](https://github.com/visionmedia).\n\nautocmdr is a set of components that add interfaces and support to commander.js based applications built by Hypercubed (me).\n\n[yo](https://github.com/yeoman/yo) is a scaffolding tool built by Google.\n\n[generator-commander](https://github.com/Hypercubed/generator-commander) is a commander.js application generator for Yo also built by Hypercubed.\n\nYo, together with the commander generator, makes it easy to scaffold complete command line tools that uses commander.js command line parser and autocmdr components to enable great command line interfaces.\n\n# Usage\n\n## Summary\n\nEssentially autocmdr, like most node.js modules, works in two modes; executable (command line) mode and library (require) mode.  In executable mode autocmdr will load any commands located in the current working directory's (cwd's) `cmds/` folder.  By convention each file in the `cmds/` directory corresponds to one commander.js command, although this is not necessary.  In this mode it is not necessary to install autocmdr in the current working directory, you are using the global autocmdr executable with the local `cmds/` commands.\n\nIn library mode a commander.js based CLI executable has access to autocmdr components extending its interface.\n\n## Using autocmdr as a task runner\n\nInstall autocmdr globally\n\n    npm install -g Hypercubed/autocmdr\n\nWhen running in executable mode all commands located in the `cmds/` folder of the current working directory are automatically loaded.  These commands can be be run by invoking `autocmdr commandname`.  `autocmdr --help` will list help on these local commands.  By using the globally installed `autocmdr` executable the rest of your project remains untouched so you can add commands to augment existing projects.\n\n## Using generator-commander to add command components\n\nInstall yo and generator-commander\n\n    npm install -g yo generator-commander\n\nusing yo and generator-commander you can add commands to the current working directory's `cmds/` folder.  Referring to the example below `yo commander:command mycmd` will add the `mycmd` command to the cwd's `cmd/` directory.  The `autocmdr mycmd` call executes the `mycmd` command.  If you change to another directory these commands are no longer available.\n\n    $ mkdir example \u0026\u0026 cd example\n    $ autocmdr --help\n\n      Usage: autocmdr [options] [command]\n\n      Commands:\n\n        config [key] [value]   Get and set options\n        completion             Print command completion script\n\n      Options:\n\n        -h, --help     output usage information\n        -d, --debug    enable debugger\n        -V, --version  output the version number\n\n      Bug reports, suggestions, updates:\n       https://github.com/Hypercubed/autocmdr/issues\n\n    $ yo commander:command mycmd\n\t\n\t[?] Command name: mycmd\n\t[?] version: 0.0.0\n\t[?] description: A commander command\n\t   create cmds/mycmd.js\n\n\tI'm all done. Add `require('../cmds/mycmd.js')(program);` to your app before program.parse.\n\n    $ autocmdr --help\n\n      Usage: autocmdr [options] [command]\n\n      Commands:\n\n        mycmd [options]        A commander command\n        config [key] [value]   Get and set options\n        completion             Print command completion script\n\n      Options:\n\n        -h, --help     output usage information\n        -d, --debug    enable debugger\n        -V, --version  output the version number\n\n      Bug reports, suggestions, updates:\n       https://github.com/Hypercubed/autocmdr/issues\n\n    $ autocmdr mycmd\n    $ cd ..\n    $ autocmdr mycmd\n    $ error:    'mycmd' is not a known command. See 'autocmdr --help'.\n\n## Using generator-commander\n\nIf a set of commands in a folder are useful globally you can convert a set of tasks to an self contained commander.js command line application.  Notice after running `yo commander` the previously created command `mycmd` is available within the newly created `example` application.\n\n1. Create an independent commander.js based app with autocmdr default plug-ins.\n\n\t    $ cd example\n\t    $ yo commander\n\t    \n\t\t[?] Name (must be only letters, spaces, or dashes) example\n\t\t[?] Version: 0.0.0\n\t\t[?] Description: A commander CLI app\n\t\t[?] GitHub username:\n\t\t[?] license: MIT\n\t\t\u003e[x] Logger (adds a Winston logger)\n\t\t [x] Commander loader (automatically loads commands from cmds/ directory)\n\t\t [x] Autocompletion (adds command line autocompletion)\n\t\t [x] Package (load reasonable defaults from your application's package.json)\n\t\t [x] Config (adds a config command)\n\t\t [x] Help (adds a `did you mean` messege when an unknown command is given)\n\t\t  \n\t\t   create package.json\n\t\t   create bin/example\n\t\t   create Readme.md\n\t\t   create test/example.js\n\t\t   create .editorconfig\n\t\t   create .jshintrc\n\t\t   create .gitignore\n\t\t   create .travis.yml\n\t\n\t\tI'm all done. Running npm install for you to install the required dependencies. If this fails, try running the command yourself.\n\t    \n\t    $ ./bin/example --help\n\t    \n\t      Usage: example [options] [command]\n\t      \n\t      Commands:\n\t        mycmd [options]        A commander command\n\t        config [key] [value]   Get and set options\n\t        completion             Print command completion script\n\t    \n\t      Options:\n\t        -h, --help     output usage information\n\t        -d, --debug    enable debugger\n\t        -V, --version  output the version number\n\n2. (Optional) Make it global\n\n\t    $ npm link\n\t    $ cd ..\n\t    $ example --help\n\t\n\t      Usage: example [options] [command]\n\t\n\t      Commands:\n\t        mycmd [options]        A commander command\n\t        config [key] [value]   Get and set options\n\t        completion             Print command completion script\n\t\n\t      Options:\n\t        -h, --help     output usage information\n\t        -d, --debug    enable debugger\n\t        -V, --version  output the version number\n\nThe new executable you just created, when you include the autocmdr components, will have access to the autocmdr features as well as the commands in the `cmds/` folder.  Edit `bin/example` to change what components are loaded.\n\n# Commander.js components\n\nautocmdr components are node.js modules that export a single initialization function.  This function is called with a commander.js program and an optional options object.  Components have a simple syntax that doesn't deviate far from the syntax established by commander.js itself. See autocmdr's [example commands](https://github.com/Hypercubed/autocmdr/tree/master/cmds) and [lib](https://github.com/Hypercubed/autocmdr/tree/master/lib) for examples.\n\n## Commands\n\nThe most basic form of a command component is shown below.  Within the exported function a single command is added to the commander.js `program` as you would in any other commander.js program (see [commander.js api documentation](http://visionmedia.github.io/commander.js/)).  \n\n    module.exports = function(program) {\n\n        program\n            .command('name')\n            .version('version')\n            .description('description')\n            .action(function(args){\n                // Do something\n            });\n    \n    };\n\n## Components\n\nautocmdr component modules have the same structure as command modules.  The only difference is that they are not designed to be automatically loaded.  Plugins are loaded using node's require function again exporting a single initialization function; this time accepting an optional options object as the second parameter.  Below are the built-in autocmdr plug-ins.\n\n    module.exports = function(program, options) {\n\n        // Do plug-in stuff here\n    \n    };\n\n# autocmdr supplied components\n\n## loader\n\nThis component is what loads the `cmds/` modules. \n\nAdding `require('autocmdr/lib/loader.js')(program)` will load all modules in the `cmds` folder just above the executable.  This path can be overridden by setting the path option; for example `require('autocmdr/lib/loader.js')(program, { path: path.join(process.cwd(), 'cmds/') )` will load modules from the cwd's `/cmds` folder.\n\n## logger\n\nThe logger component uses [Winston](https://github.com/flatiron/winston) for logging.\n\nAdding `require('autocmdr/lib/logger')(program)` will add `program.log` to your application.  The plug-in will enable  output to the terminal depending on the log level.  The plug-in will also add the `-d` option to your application to enable debug logging.  Then logging can be done like this:\n\n    program.log('info', 'Hello!');\n    program.info('Hello again');\n    program.debug('Can you hear me now?');\n\nWhile this component is optional other components expect to find and instant of Winston at `program.log`.\n\n## config\n\nThis component will load [nconf](https://github.com/flatiron/nconf) for handling of configuration.  It will add program.config as an instance of nconf.\n\nAdding `require('autocmdr/lib/config')(program)` will enable this.\n\nWhile this component is optional other components expect to find and instant of nconf at `program.config`.\n\n## help\n\nThis component will use [didyoumean](https://github.com/dcporter/didyoumean.js) to add a \"Did you mean:\" message to your application when an unknown command is given.\n\nAdding `require('autocmdr/lib/help')(program)` will enable this.\n\n## package\n\nThis component will use the will load reasonable defaults (such as description and bug reporting URL) from your application's package.json.\n\nAdding `require('autocmdr/lib/package')(program)` will load the package.json file located one directory above the executable.  You can override this path using the options object.\n\n## completion\n\nThis component will use [node-tabtab](https://github.com/mklabs/node-tabtab) to add auto-completion support to your application.\n\nAdding `require('autocmdr/lib/completion')(program)` just before `program.parse(argv);` will will enable auto-completion support.  You will then need to do one of the following to enable auto-completion in your shell.\n\n* Add completion helper to ~/.bashrc (or ~/.zshrc) `pkgname completion \u003e\u003e ~/.bashrc`\n* Add completion to current shell `. \u003c(pkgname completion)`\n\n# Share\n\nThe modular nature of autocmdr command files makes it easy to share using gist, git or similar tool.  Simply copying files into `cmds/` folder can work in many cases.\n\n# Todo\n\nSee [todo.md](https://github.com/Hypercubed/autocmdr/blob/master/todo.md) \\( managed using [todo-md](https://github.com/Hypercubed/todo-md) and it's self an [autocmdr](https://github.com/Hypercubed/autocmdr/tree/master/lib) app\\)\n\n# License\n\n[MIT License](http://en.wikipedia.org/wiki/MIT_License)\n\nCopyright (c) 2013 J. Harshbarger\n[![Gittip donate button](http://badgr.co/gittip/hypercubed.png)](https://www.gittip.com/hypercubed/ \"Donate weekly to this project using Gittip\")\n[![Paypal donate button](http://badgr.co/paypal/donate.png?bg=%23feb13d)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=X7KYR6T9U2NHC \"One time donation to this project using Paypal\")\n\n# Acknowledgments\n\nautocmdr itself was (partially) built using [autocmdr](https://github.com/Hypercubed/autocmdr).\n\nautocmdr is build on top of [commander.js](https://github.com/visionmedia/commander.js) and inspired by other task managers \\( [grunt](https://github.com/gruntjs/grunt), [automaton](https://github.com/IndigoUnited/automaton) \\) and command line tools \\( [docpad](https://github.com/bevry/docpad), [git](https://github.com/git/git) \\).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypercubed%2Fautocmdr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhypercubed%2Fautocmdr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypercubed%2Fautocmdr/lists"}