Installation

Install Globally

npm i -g @kibibit/cli-lit 

and run it using

cli-lit --name <cli_name> --file <typescript_file> --class <exported_class>

Install Locally

npm i --save @kibibit/cli-lit

Then, you can add it to your package.json as a script:

"scripts": {
  // ...
  "generate-cli": "cli-lit --name <cli_name> --file <typescript_file> --class <exported_class>"
}

and run it using

npm run generate-cli

NPM Development Commands

When running npm install @kibibit/cli-lit, it will automatically compile the typescript decorators.

• npm run compile - compile typescript decorators file to javascript
• npm run build:doc - will compile a new README.md file based on general-readme.md and the decorators' jsdoc comments.

Examples

import * as request from 'request-promise';
import * as keytar from 'keytar';
import * as homeConfig from 'home-config';
import { description, cligroup, cliRename, cliOptionalParams, cliBeforeEach } from '@kibibit/cli-lit';

const cfg = homeConfig.load('.myConfigFile');

export class UserActions {
    /* Added FOR the CLI.
     * This will make sure the user is logged in
     * already and retrieve the user token to
     * pass to the function called. If the
     * user is not logged in, throw an error. */
    @cliBeforeEach()
    static getUserToken() {
        const loginErr = Error('Please run my-cli setup to login');

        if (!cfg.username) throw loginErr;

        return keytar.getToken('myCLI', cfg.username)
          .then((token) => {
              return {
                  token: token
              };
          })
          .catch((err) => {
              throw loginErr;
          });
    }

    /* Added FOR the CLI.
     * This will save the user token in the OS's keychain,
     * and the logged in username in a configuration
     * file called .myConfigFile in order to do this once and pass the token using the getUserToken function */
    @cliAfterEach()
    static saveUserToken(functionName, returnValue, givenParams) {
        if (functionName === 'loginUser') {
            return keytar
                .setPassword('myCLI', givenParams.username, returnValue)
                .then(() => cfg.username = givenParams.username)
                .then(() => cfg.save())
        }
    }

    @cliRename('setup')
    @clidescription(`Initial setup to use the CLI`)
    static loginUser(username, password) {
        const options = createLoginOptions(username, password);

        return request(options);
    }

    @cliRename('set')
    @clidescription(`Set the logged in user's email`)
    @cligroup('user.email')
    static setEmail(token, email) {
        const options = postOptions('/user', token, {
            email: email
        });

        return request(options);
    }

    @cliRename('get')
    @clidescription(`Get the logged in user's email`)
    @cligroup('user.email')
    static getEmail(token) {
        const options = getOptions('/user/email', token);

        return request(options);
    }

    @cliRename('publish')
    @clidescription(`Publish a new blog piece`)
    @cligroup('user.blog')
    static postBlog(token, title, markdown) {
        const options = postOptions('/blog', token, {
            title: title,
            body: markdown
        });

        return request(options);
    }

    @cliRename('read')
    @clidescription(`Read a blog piece. Get's a title as a search term`)
    @cligroup('user.blog')
    static getBlog(token, title) {
        const options = getOptions(`/blog/${title}`, token);

        return request(options);
    }
}

Available Decorators

Functions

cliDescription(...args)

Kind: global function

| Param | Description | | --- | --- | | ...args | the description of the function |

Example

.@cliDescription(`get the user's info`)
static getUserInfo(userId) { ... }

cliGroup(cliGroup)

Kind: global function

| Param | Type | Description | | --- | --- | --- | | cliGroup | string | The group path string. every inner group is separated by a dot (.) |

Example

// will create a cli command:
// $ cli user info get <user_id>
.@cliRename('get')
.@cliGroup('user.info')
static getUserInfo(userId) { ... }

cliRename(newFunctionName)

Kind: global function

| Param | Type | Description | | --- | --- | --- | | newFunctionName | string | the new function name |

Example

// will create a cli command:
// $ cli get <user_id>
.@cliRename('get')
static getUserInfo(userId) { ... }

cliOptionalParams(optionalArray)

Kind: global function

| Param | Type | Description | | --- | --- | --- | | optionalArray | Array.<string> | array of optional params |

Example

// will create a cli command:
// $ cli renameUser <new_name>
.@cliOptionalParams(['newName'])
static renameUser(newName: string = randomName()) { ... }

cliHiddenParams(hiddenArray)

Kind: global function

| Param | Type | Description | | --- | --- | --- | | hiddenArray | Array.<string> | array of hidden params |

Example

// won't ask the user to set a token.
.@cliHiddenParams(['token'])
static getUserInfo(token: string, ) { ... }

cliBeforeEach()

Kind: global function
Example

// won't ask the user to set a token.
.@cliBeforeEach()
static fetchTokenFromKeychain() {
  return keytar.getPassword(cfg.username)
    .then((token) => ({ token: token }))
    .catch(() => throw new Error('user not logged in'));
}

cliAfterEach()

Kind: global function
Example

.@cliAfterEach()
static logResult(functionName, returnValue, givenParams) {
  console.log('function result: ', returnValue);
}

cliIgnore()

Kind: global function
Example

.@cliIgnore()
static dontTraslate(arg) { ... }

Contributing

If you have suggestions for how @kibibit/cli-lit could be improved, or want to report a bug, open an issue! We'd love all and any contributions.

For more, check out the Contributing Guide.

Contributors

License

MIT © 2019 Neil Kalman [email protected]