[Suggestion] Additional Text On CLI help page

[pgamerx]

Hi there, Your package is amazing!
I made my own CLI using it.

On the help page, it says this:

Powered by @christianjuth/ts-cli-generator

Commands:
  save	Save the data identified by the unique key.
  show	Show the data identified by the unique key.
  del 	Deletes a key from the localStorage

Options:
  -h, --help       	Output usage information
  -i, --interactive	Run CLI in interactive mode

I don't mind the "Powered by @christianjuth/ts-CLI-generator" line, but I was wondering if there was a way for us to add custom lines along with it as well!
If Not then I would highly suggest adding a feature like this!

[christianjuth]

@pgamerx I decided to remove Powered by @christianjuth/ts-CLI-generator. Update to the latest version and it should be gone.

I'm planning on adding a way to override the help text. I'm thinking something like this:

function __help__({ name, version, commands, options }) {
  console.log("...whatever you want to say")
}

export const cli = {
  __help__
}

I could even pass the default text in so you can just append/prepend your own message.

function __help__({ defaultMessage }) {
  console.log(defaultMessage + "\n your custom message")
}

Thoughts?

[pgamerx]

@pgamerx I decided to remove Powered by @christianjuth/ts-CLI-generator. Update to the latest version and it should be gone.

I'm planning on adding a way to override the help text. I'm thinking something like this:

function __help__({ name, version, commands, options }) {
  console.log("...whatever you want to say")
}

export const cli = {
  __help__
}

I could even pass the default text in so you can just append/prepend your own message.

function __help__({ defaultMessage }) {
  console.log(defaultMessage + "\n your custom message")
}

Thoughts?

That does seem a great idea! Also, I had a little bit of issue working with options like <cli> info --website. The CLI still asks for the value of Boolean even though I had declared it as an optional parameter with default value to false.

function info(website: boolean = false)....

It was something like this, can you guide me on this as well? Thanks!

[christianjuth]

I think two things are happening here.

1. Default Paramaters and Interactive Mode

The first is I haven't set up the library to handle parameters with default values yet. I'm not sure yet the best way to do this. Consider the the following two ways to run the CLI:

1. Arguments can be passed to the CLI when the command is run like so <cli> info true
2. When you exclude and argument <cli> info the cli enters an interactive mode where it prompts you for a value for website

Interactive mode example:

$ <cli> info
? website › - Use arrow-keys. Return to submit.
❯   True
    False

What's unclear to me is whether having a default value for website should bypass interactive mode for that parameter. Based on what you are saying it sounds like it should bypass the interaction and just use the default value.

However, by giving it a default value you would be making it so there is no way to interact with that parameter via interactive mode, but maybe that's ok?

You would also have this usecase where a function could be partially interactive. In the example below, you can interact with a, but you will never be able to interact with b (assuming we make it so default values bypass interactive mode).

function example(a: number, b: boolean = false) {}

2. Handling flags

The CLI is not currently setup to handle user created flags. All parameters after a command are positional. I am thinking about adding flags, but there are a few things to consider.

1. What happens if your function takes a parameter that conflicts with one of the internal flags that the library is already using (--help, --interactive)? Should the user be able to override these flags?
2. Including a library to parse flags will increase the size of the CLI (it could go up a lot). I don't have any numbers yet, but I'm aiming for builds to be 50-60kb, which I picked arbitrarily.
3. How do we handle duplicate parameter names? (example below)

Consider the example below:

function foo(a: { a: number }, b: { a: number }) {}

If you run <cli> foo -a=5, which param should a be mapped to? We could fix this by having it be <cli> foo -b.a=5, but it gets complicated very quickly.

One more thing

I haven't decided how to handle arrays yet, and I'm curious to hear your thoughts on this. How should we handle the following function:

function foo(arr: (string | number)[]) {}

I'm not sure the best interface to handle arrays like this. We would need to ask the user if they want to end input for that array, enter another value, and if they enter another value whether it should be a string or number. I'm skeptical how useful these array parameters will be which is why I decided to handle objects first, but I think they will come up at some point. Any thoughts?

[christianjuth]

Btw, I really appriciate your input. Its much easier for me to make the right design choices when I can understand usecases that I might not be envisioning. Please keep the questions coming!

[pgamerx]

Thanks for the update, and no problem.
I am currently eating food as I just finished my exam, I shall read everything thoroughly and reply to you within 24 hours.

[pgamerx]

I think two things are happening here.

1. Default Paramaters and Interactive Mode

The first is I haven't set up the library to handle parameters with default values yet. I'm not sure yet the best way to do this. Consider the the following two ways to run the CLI:

1. Arguments can be passed to the CLI when the command is run like so <cli> info true
2. When you exclude and argument <cli> info the cli enters an interactive mode where it prompts you for a value for website

Interactive mode example:

$ <cli> info
? website › - Use arrow-keys. Return to submit.
❯   True
    False

What's unclear to me is whether having a default value for website should bypass interactive mode for that parameter. Based on what you are saying it sounds like it should bypass the interaction and just use the default value.

However, by giving it a default value you would be making it so there is no way to interact with that parameter via interactive mode, but maybe that's ok?

You would also have this usecase where a function could be partially interactive. In the example below, you can interact with a, but you will never be able to interact with b (assuming we make it so default values bypass interactive mode).

function example(a: number, b: boolean = false) {}

2. Handling flags

The CLI is not currently setup to handle user created flags. All parameters after a command are positional. I am thinking about adding flags, but there are a few things to consider.

1. What happens if your function takes a parameter that conflicts with one of the internal flags that the library is already using (--help, --interactive)? Should the user be able to override these flags?
2. Including a library to parse flags will increase the size of the CLI (it could go up a lot). I don't have any numbers yet, but I'm aiming for builds to be 50-60kb, which I picked arbitrarily.
3. How do we handle duplicate parameter names? (example below)

Consider the example below:

function foo(a: { a: number }, b: { a: number }) {}

If you run <cli> foo -a=5, which param should a be mapped to? We could fix this by having it be <cli> foo -b.a=5, but it gets complicated very quickly.

One more thing

I haven't decided how to handle arrays yet, and I'm curious to hear your thoughts on this. How should we handle the following function:

function foo(arr: (string | number)[]) {}

I'm not sure the best interface to handle arrays like this. We would need to ask the user if they want to end input for that array, enter another value, and if they enter another value whether it should be a string or number. I'm skeptical how useful these array parameters will be which is why I decided to handle objects first, but I think they will come up at some point. Any thoughts?

Hi, sorry for the late response I was just very busy with my studies.

1. I think there should be another way to make a command that isn't interactive or just making options that aren't interactive so users can run commands like [command] links --website

1. There should be an option to disable the default flags if we want to use them.
2. Yeah I understand, the size will increase no matter what we do!
3. We don't need to care much about it, you can state it in the documentation and I think anyone who is planning on developing a CLI should see this for himself.

3. Honestly I cannot really imagine a use case where we would need the user to pass Arrays as a parameter, but even if we do maybe we can add some key combination for ending the array.

[christianjuth]

Got it. I need to think about this a little more. I'm already in the process of removing the internal flags. I'm gonna try to keep the internal commands as slim as possible to avoid conflicts.