goalist

[![Build Status](https://travis-ci.org/jrmykolyn/goalist.svg?branch=master)](https://travis-ci.org/jrmykolyn/goalist) [![Coverage Status](https://coveralls.io/repos/github/jrmykolyn/goalist/badge.svg?branch=master)](https://coveralls.io/github/jrmykolyn/goalist?branch=master) # Goalist ## Table of Contents - [About](#about) - [Installation](#installation) - Overview - CLI - Import - [Setup](#setup) - [Usage](#usage) - Overview - Subcommands - CLI - Import - [Documentation](#documentation) ## About Goalist is a tool for managing daily goals. Goalist can be run directly from the command line, or imported by a dependent script. ## Installation ### Overview Goalist can be installed in multiple ways depending on the use case. To interact with Goalist's CLI, follow the 'CLI' installation instructions. To use the Goalist module within a dependent script, follow the 'Import' installation instructions. ### CLI To install Goalist globally, run the command below: ``` npm install -g goalist ``` ### Import To install Goalist as a dependency within a node/npm project, run the command below: ``` npm install --save goalist ``` ## Setup Goalist does not require any additional configuration. ## Usage ### Overview The Goalist module may used/accessed in either of the following ways: - via import by/within a dependent script; - via CLI. Documentation for both modes is provided below. ### Subcommands Included below is an overview of all subcommands exposed by the Goalist package. See the **CLI** and/or **Import** sections below for detailed usage instructions. | Subcommand | Description | | --- | --- | | add | Add a new goal. | | archive | Archive an existing goal. | | backup | Create a backup of all goal data. | | complete | Mark an existing goal as complete. | | list | List all goal data. | | progress | Display progress data, including: total number of goals; complete goals; incomplete goals; etc. | | remove | Remove an existing goal. | | update | Update an existing goal. | ### CLI When installed globally, Goalist exposes the `gl` command. Running `gl` from the command line will display the help menu. In order to interact with the core functionality of the Goalist package, a selection of subcommands are exposed. Each subcommand can be invoked using its full name (eg. `add`), or via a single character alias (eg. `a`). See below for the full list commands. Please note: - The help menu can *also* be accessed by invoking `gl` with the `--help` flag (eg. `gl --help`). - The current version can be accessed by invoking `gl` with the `--version` flag (eg. `gl --version`). - Goalist can be run in 'silent' mode by invoking `gl {{ COMMAND }}` with the `--silent` flag (eg. `gl add "My new goal." --silent`). This suppresses all output. - Goalist can be run in 'verbose' mode by invoking `gl {{ COMMAND }}` with the `--verbose` flag (eg. `gl list --verbose`). This displays additional information about the internals of a given command, and may be useful for debugging purposes. ### `add` / `a` This command is used to add a new goal to the log file for the current. ``` gl add "This is the title of the goal." ``` ### `archive` / `ar` This command is used to archive/deactivate a given goal. ``` gl archive {{ ID }} ``` Executing the command above will result in the following: - Target goal is moved from the 'active' log file to the 'archive' file. - Target goal will have its `active` key/property set to `false`. When invoked with the `--active` flag, this command will perform the reverse operation. ``` gl archive {{ ID }} --active ``` Executing the command above will result in the following: - Target goal is moved from the 'archive' log file to the 'active' file. - Target goal will have its `active` key/property set to `true`. ### `backup` / `b` This command is used to created a backup of the 'active' log file. ``` gl backup ``` When invoked with the `--archive` file, an 'archive' log file backup is created instead. ``` gl backup --archive ``` ### `complete` / `c` This command is used to toggle the 'complete' property for a specific goal. By default, this command operates on 'active' goals. To mark a goal as complete, invoke the subcommand with the goal ID. ``` gl complete {{ ID }} ``` This command can also be used to set the status of a goal to 'incomplete'. ``` gl complete {{ ID }} --false ``` To toggle the 'complete' state of a goal within the 'archive' log, provide the `--archive` flag. ``` gl complete {{ ID }} --archive // Set an archived goal to complete. gl complete {{ ID }} --archive --false // Set an archived goal to incomplete. ``` ### `list` / `l` This command is used to list all goals present in the 'active' log file. This command is especially useful for goal IDs, which are required by the `update` subcommand. By default, only the ID and title for each goal will be displayed. ``` gl list ``` When invoked with the `--archive` flag, this command will display the contents of the 'archive' log file. ``` gl list --archive ``` To display **all** of the data for a given goal, invoke the `list` command with the `--all` flag/argument. ``` gl list --all gl list --archive --all ``` To display specific properties , the `list` command may be invoked with the `--show` flag. When provided with a series of comma delimited strings, `--show` flag displays the corresponding properties (in addition to the ID and title). ``` gl list --show=title,complete // title: My New Goal // complete: true ``` ### `progress` / `p` This command is used to display progress information relating to the 'active' log file (eg. total number of goals, number of completed goals, etc.). ``` gl progress ``` ### `remove` / `r` This command is used to remove a specific goal within the 'active' log file. ``` gl remove {{ ID }} ``` If invoked with the `--archive` flag, this command will attempt to remove the target goal from the 'archive' log file. ``` gl remove {{ ID }} --archive ``` ### `update` / `u` This command is used to update a specific goal within the 'active' log file. ``` gl update {{ ID }} --title="This is the new title of the goal." ``` ### Import When installed locally, Goalist can be imported into a dependent script. ``` const Goalist = require( 'goalist' ); ``` After Goalist has been imported, create a new instance as follows: ``` let goalist = new Goalist(); ``` By default, Goalist will write to/read from a hidden `.goalist` folder within the the current user's home directory. This behavior can be overridden by providing an object with a key of `utilsOpts` at instantiation time. ``` let goalist = new Goalist( { utilsOpts: { path: '/path/to/custom/goalist/dir', }, } ); ``` By default, Goalist does not log any information to stdout. However, this behavior can be enabled by providing an object with a key of `debuggerOpts` at instantiation time. ``` let goalist = new Goalist( { debuggerOpts: { mode: 'verbose', // Valid values are: 'verbose'; 'normal'; 'silent'. }, } ); ``` Goalist exposes the `#run()` instance method, which is used to execute individual subcommands. ``` goalist.run( 'list' ); // Execute the 'list' subcommand. ``` `#run()` returns a Promise, which will resolve or reject depending on whether the operation was successful. To access the data returned by the `#run()` method, invoke the `.then( ... )` on the value returned by `#run()`. ``` goalist.run( 'list' ) .then( ( data ) => { // Do something with the data returned by 'list' here. } ) .catch( ( err ) => { // Handle potential errors here. } ); ``` Some of the Goalist subcommands require additional information in order to function properly (this is generally the case if the subcommand operates on a specific goal). These can be provided by invoking the `#run()` command with a second argument. ``` goalist.run( 'complete', [ '1516126195749' ] ); // Mark the goal with id '1516126195749' as complete. ``` Additional options can be provided by invoking `#run()` with a third argument. ``` goalist.run( 'update', [ '1516126195749' ], { title: 'My cool new title.' } ); // Update the title property of the goal with id '1516126195749'. ``` For cases where the options object is required but the array of supplementary information is not, provide an empty array or null value as the second argument. ``` goalist.run( 'list', [], { archive: true } ); // List all of the 'archived' goals. goalist.run( 'backup', null, { archive: true } ); // Create a backup of the 'archived' goals file. ``` ## Documentation Currently, Goalist does not include any external documentation. For an overview of the project's evolution, please consult the CHANGELOG.