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 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.