jrmykolyn
Goalist
Table of Contents
- About
- Installation
- Overview
- CLI
- Import
- Setup
- Usage
- Overview
- Subcommands
- CLI
- Import
- 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 goalistImport
To install Goalist as a dependency within a node/npm project, run the command below:
npm install --save goalistSetup
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
glwith the--helpflag (eg.gl --help). - The current version can be accessed by invoking
glwith the--versionflag (eg.gl --version). - Goalist can be run in 'silent' mode by invoking
gl {{ COMMAND }}with the--silentflag (eg.gl add "My new goal." --silent). This suppresses all output. - Goalist can be run in 'verbose' mode by invoking
gl {{ COMMAND }}with the--verboseflag (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
activekey/property set tofalse.
When invoked with the --active flag, this command will perform the reverse operation.
gl archive {{ ID }} --activeExecuting 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
activekey/property set totrue.
backup / b
This command is used to created a backup of the 'active' log file.
gl backupWhen invoked with the --archive file, an 'archive' log file backup is created instead.
gl backup --archivecomplete / 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 }} --falseTo 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 listWhen invoked with the --archive flag, this command will display the contents of the 'archive' log file.
gl list --archiveTo display all of the data for a given goal, invoke the list command with the --all flag/argument.
gl list --all
gl list --archive --allTo 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: trueprogress / 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 progressremove / 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 }} --archiveupdate / 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.