[CLI Help] Usage Tips and Tricks

Discuss anything related to command line tools here.
Post Reply
Message
Author
User avatar
vevy
Posts: 795
Joined: Tue Sep 10, 2019 11:17 am

[CLI Help] Usage Tips and Tricks

#1 Post by vevy »

0. Resources: 1. y/N prompt capitalization is a relevant convention:
  • Capital N = default is "No". If you just press Enter without choosing/typing, it will be interpreted as No. Same with Y.
  • Equal capitalization "Y/N" means you have to choose.

2. In help, arguments in square brackets are optional, pipe=alternatives:
  • Code: Select all

    pdftohtml [options] <PDF-file> <html-dir>
    means options can be omitted, but you have to provide file and dir.
  • Code: Select all

    netcfg [-v] [-winpe] [-l <full-path-to-component-INF>] -c <p|s|c>
    means:
    -v, -winpe are optional.
    -l is optional, but if you use it you must provide the path.
    -c is mandatory and you have to provide an argument for it by picking one of p or s or c.
3. Often, you don't have to enter the full switch as long as it is unique.
can be entered as:
wget.exe --http-k <URL> or wget.exe --http-kee <URL>, etc.
If you try --http only, it will throw an error because there are multiple switches beginning with --http, for example, --http-password.
4. It is a better practice to have your CLI tools in a path without spaces.
C:\CLI_Tools instead of C:\CLI Tools
It will save you a lot of hassle with quotes and escaping etc.
5. For some tools, any thing after (-- ) (hyphen-hyphen-whitespace) is not parsed as a switch.
If you have a file or a string that begins with a hyphen-minus (-), a CLI tool might think that you are trying to use a switch.
For example, you may want to search a text file for the string (-h). If you enter type myfile.txt|grep -h, grep might think you are trying to see the help for grep itself.
To avoid this, you can:
  • put the string in quotes ("-h"), but that doesn't always work or can be problematic.
  • use -- (if the tool supports this) to indicate "No more switches. Whatever comes next is a string parameter":

    Code: Select all

    type myfile.txt|grep -- -h
6. Some tools allow you to enter the text before processing it. Finish by Ctrl+Z then Enter.
If a tool opens but only shows a blinking cursor at the beginning of the next line, and the purpose of this tool is to act upon text in some way (analyze, convert, etc), try the following steps:
  1. entering some text, in one or more lines like you would in Notepad.
  2. Press Ctrl+Z.
  3. Press Enter.
This will tell the tool that you finished the input text and it should process it.

This is useful for allowing free-form, multi-line entering and editing of text in the terminal first then running the tool (as opposed to redirecting the text as standard input).
7. Some tools allow you to reverse a yes/no option by inserting no-.
For example, wget --quiet becomes wget --no-quiet.
Or the opposite, wget --verbose becomes wget --no-verbose.

In tools that behave like that, this should apply to any long Boolean (yes/no) option. Long here means the option begins with two dashes (--quiet), not an abbreviated form (-q). The actual character length of the long option shouldn't matter.

Another example,
--default-browser-check is disabled like this: --no-default-browser-check.
Last edited by vevy on Sun Aug 01, 2021 12:07 pm, edited 10 times in total.

User avatar
webfork
Posts: 10818
Joined: Wed Apr 11, 2007 8:06 pm
Location: US, Texas
Contact:

Re: [CLI Help] Tips and Tricks

#2 Post by webfork »

Hey could you put a little text together describing what's happening in this entry? You obviously put a fair amount of work into this and I'm just not clear what problem it's trying to solve.

User avatar
vevy
Posts: 795
Joined: Tue Sep 10, 2019 11:17 am

Re: [CLI Help] Tips and Tricks

#3 Post by vevy »

I am not sure what you mean. Like what do you see as ambiguous?

User avatar
Cornflower
Posts: 244
Joined: Fri Aug 31, 2007 7:58 am
Location: Canada's capital

Re: [CLI Help] Tips and Tricks

#4 Post by Cornflower »

I really like this, and the inclusion of Angle Brackets as a standard I totally agree with.
Let me see if I understand the post by restating them in what I hope are lay terms, using the same examples. I tend to rewrite many of the CLI help documentation for my personal documentation file so that if I don't use something for a year, I can understand and don't have to relearn the syntax and parameters.My pre-Windows DOS batch files always had a help screen if parameters were omitted. Here goes.

1. If there is a CLI prompt, such as "Answer y/N" or "Direction? L/r" , the default response (that is, if you simply press {enter}) will be the response that is capitalized. In the first example, pressing {enter} will return a No response, and in the second, {enter} will return a L (for left) response.

2. In CLI help, there are a few punctuation standards for command parameters. These are
a. Square brackets [ ] mean that whatever is inside is optional.

b. Angle brackets < > mean that whatever is inside is mandatory and something must be put there. Anything without brackets is also mandatory.
e.g.

Code: Select all

pdftohtml [options] <PDF-file> <html-dir> 
; You don't have to include any options but you must include a pdf file and an html directory for this command
note that I added the ; as in ignore this in the command, everything to the right of it is a comment. This is more for documentation than for CLI help

c. Things in pipes | are alternatives for the parameter(s). They can reside withing optional [] or mandatory <> parameters
e.g.

Code: Select all

netcfg [-v] [-winpe] [-l <full-path-to-component-INF>] -c <p|s|c>
In this example the command has optional parameters, but must include one of -cp or -cs or -cc
Note that in this example, because there are no brackets, -c is mandatory. the example, if I understand it correctly, could also be written like this below with the same meaning

Code: Select all

 netcfg [-v] [-winpe] [-l <full-path-to-component-INF>] <-cp|-cs|-cc>
Question: Is there a standard for curly brackets { } ? The Wget example uses them for the URL, indicating in that case mandatory. In other cases, they can designate a key, such as {Tab} or {Enter}, but this is used primarily for GUI help screens. Otherwise, we might want to steer clear of them, or designate them for use solely for URLs.

3. Some commands are written so that you can use a shortened parameter instead of the full one, as long as that shortened parameter only refers to that one choice (it is a unique choice)
Wget is one of those commands
e.g.

Code: Select all

wget.exe --http-keep-alive {URL}
When you look at the complete set of parameter options for Wget, there are a number of them that begin with "--http", but only one of them that begins with "--http-k"
This means that --http-keep-alive requires at least the string "--http-k" or more for it to work.

I personally don't shorten parameters unless you can shorten them to a single letter. I find remembering them too confusing. I am tempted to leave them out in any help I write.

User avatar
vevy
Posts: 795
Joined: Tue Sep 10, 2019 11:17 am

Re: [CLI Help] Tips and Tricks

#5 Post by vevy »

@Cornflower You are pretty much on point for most things.

Just a few notes:
- Microsoft syntax.
- POSIX syntax.

Cornflower wrote: Sat Oct 17, 2020 5:32 am or "Direction? L/r"
I don't know if it applies to more than Yes/No. :?:
Angle brackets < > mean that whatever is inside is mandatory
Not necessarily. It is a placeholder. It means that it needs to be substituted with an actual value.
Question: Is there a standard for curly brackets { } ? The Wget example uses them for the URL, indicating in that case mandatory. In other cases, they can designate a key, such as {Tab} or {Enter}, but this is used primarily for GUI help screens. Otherwise, we might want to steer clear of them, or designate them for use solely for URLs.
:oops: That was just me! Based on the above, I guess I should have used wget.exe --http-keep-alive <URL> or so.

User avatar
webfork
Posts: 10818
Joined: Wed Apr 11, 2007 8:06 pm
Location: US, Texas
Contact:

Re: [CLI Help] Tips and Tricks

#6 Post by webfork »

vevy wrote: Fri Oct 16, 2020 7:51 pm I am not sure what you mean. Like what do you see as ambiguous?
As in who is this for? Tips and tricks for what situation? Is this for help authors/documentation, developers, users?

User avatar
vevy
Posts: 795
Joined: Tue Sep 10, 2019 11:17 am

Re: [CLI Help] Usage Tips and Tricks

#7 Post by vevy »

I forgot you write documentation! :mrgreen: Updated Title.

It is for users. To be able to understand some of the syntax and conventions used when they type tool.exe --help or so.

Post Reply