Earlier quoted context omitted.
Absolutely - I can't buy into the "don't write man pages" idea. For many years I've had this function in my RC files for macOS: pman() { man -t "$@" | open -f -a Preview; } It opens the given man page in Preview, typeset beautifully. No such thing is available for random text printed to the console, nor is a console pager (as recommended by this article) an acceptable substitute for this.
What is Preview?
CLI Guidelines – A guide to help you write better command-line programs
101–110 of 217 posts
Re: CLI Guidelines – A guide to help you write better command-line programs
#102Nice read, makes me happy to see people invest in CLI. "Humans first"... How about "Humans with Tools first" ? :) I would say that ALL logging should go to stderr (level should be --configurable of course), so that when running a container for example I can capture all the logging easily on stderr. Also that [WARN], [ERROR], etc tags are quite nice to have in there when grep'ing over it.. Just saying :) I would very…
It would be nice to see an example of space.sh usage somewhere on the landing page. I was intrigued by “through 10 firewalls” but not quite enough to go to the documentation and look it up.
Thanks for the tip! Yes, upping the site with articles and examples is on the TODO :)
In the SSH module doc [0] there are a few examples, such as:
space -m ssh /ssh/ -e SSHHOST=jump1.example.com,jump2.example.com,jump3.example.com,destination.example.com -e SSHCOMMAND="ls -l"
One very fun feature is that you can tab auto-complete filenames and container names and also files inside container on a remote host: space -m ssh -e SSHHOST=1.2.3.4 -e SSHPORT=2233 -e SSHUSER=rabbit /wrap/ -m docker /wrap_exec/ -e DOCKERCONTAINER=[tab tab]
Then: space -m ssh -e SSHHOST=1.2.3.4 -e SSHPORT=2233 -e SSHUSER=rabbit /wrap/ -m docker /wrap_exec/ -e DOCKERCONTAINER=something -m file /cat/ -e file=/home/[tab tab]
Note that server jumping (over firewalls) is perfectly viable in the last example too, by adding more hosts (comma separated). Note that it can be important to balance host names to user names (see the doc [0]).In the examples space wraps module functionality where the last module file is the one finally running inside the container, wrapped first by the `ssh` module then the `docker` module.
It is totally agent-less so nothing is uploaded to the server, it's just like SSHing in and running commands.
If you add the `-d` flag to space it will dump the script to output, which you can save to a .sh file and run later (without needing space.sh at all). Space it self requires bash, but the output runs with POSIX shells, so it also works with dash/ash/busybox, etc which is good because servers/containers often doesn't come with bash, but simpler ash/dash instead.
Thanks for showing interest, this makes me keen on pushing a few fixes and updates I have pending. Let me know if it doesn't work and I'll fix that :)
[0] https://space.sh/gitlab.com/space-sh/ssh/doc/master/examples...
Re: CLI Guidelines – A guide to help you write better command-line programs
#103These are some pretty good guidelines! Many thanks to the authors for writing them up. Some nitpicks (what would HN be without nitpicks?): > If your command is expecting to have something piped to it and stdin is an interactive terminal, display help immediately and quit. I disagree with this advice: being able to spoon-feed input into a program is extremely useful, and is part of the "conversational" CLI paradigm th…
Re: CLI Guidelines – A guide to help you write better command-line programs
#104Hello HN! We’re Ben, Aanand, Carl, Eva, and Mark, and we made the Command Line Interface Guidelines. Earlier this year, I was working on the Replicate CLI [0]. I had previously worked on Docker so I had a bunch of accumulated knowledge about what makes a good CLI, but I wanted to make Replicate really good, so I looked for some design guides or best practices. Turns out, nothing substantial had been published since t…
I did not see a personal pet-peeve of mine: If a user of your CLI tool has explicitly requested the built-in help text via --help (or an equivalent switch that requests help) then that help text shall be output on stdout. It always peeves me to do: command --help | less only to find that the explicit request for help (the --help switch) has output the help text on stderr, and I then have to redo the invocation: comma…
command --help |& less
Less characters to type.Re: CLI Guidelines – A guide to help you write better command-line programs
#105My advice as a user of CLI: - no emojis please, ever - if you want to make it look nice, use ANSI escape codes for color rather than emojis. even then, don't use color alone to convey meaning because it will most likely get destroyed by whatever you're piping it to. - please take the time to write detailed man pages, not just a "--help" screen - implement "did you mean?" for typos (git style) and potentially dangerou…
Why not? Do you also don't want to see icons in GUIs?
Re: CLI Guidelines – A guide to help you write better command-line programs
#106My advice as a user of CLI: - no emojis please, ever - if you want to make it look nice, use ANSI escape codes for color rather than emojis. even then, don't use color alone to convey meaning because it will most likely get destroyed by whatever you're piping it to. - please take the time to write detailed man pages, not just a "--help" screen - implement "did you mean?" for typos (git style) and potentially dangerou…
Re: CLI Guidelines – A guide to help you write better command-line programs
#107> "Don’t bother with man pages. [...] Not enough people use man pages [...] your time is best spent improving web docs and built-in help text." I couldn't disagree more.
It's really weird to me that a few people here seem to really like their man page... when you can just do `cmd --help` and it works in pretty much any program, and you can visit the website for in-depth information.
Re: CLI Guidelines – A guide to help you write better command-line programs
#108My advice as a user of CLI: - no emojis please, ever - if you want to make it look nice, use ANSI escape codes for color rather than emojis. even then, don't use color alone to convey meaning because it will most likely get destroyed by whatever you're piping it to. - please take the time to write detailed man pages, not just a "--help" screen - implement "did you mean?" for typos (git style) and potentially dangerou…
Explicit escape codes is problematic when using any terminal that isnt' fully compatible with the xterm control codes, and doesn't allow me to turn those codes off by setting TERM to dumb.
Far too many times have I redirected output from a program to a file only be be bombarded with escape codes, breaking grep and other tools that process the output.
Not to mention the fact that using terminfo is much easier than manually outputting the control codes.
Re: CLI Guidelines – A guide to help you write better command-line programs
#109> and they don’t work on Windows
My cygwin install says otherwise.
And even if that were not the case I wouldn't not do something useful because of a deficiency in a particular platform. We have enough issues with that via needing to support IE11 still in the day job! Include the man page on the other documentation. You probably already have it written and can convert it from other docs so it might be very little work.
Re: CLI Guidelines – A guide to help you write better command-line programs
#110Earlier quoted context omitted.
Right. I still prefer terse help text from the command line, and more in-depth in the man pages. I find commands with copious -h output and having to pipe that into a pager or using scroll back a far worse UX than just opening up a man page that’s easily searchable / scrollable.
Yea that's reasonable, but there are pros and cons and it's also definitely an opinion :). I don't see the problem with piping help text through a pager (that's literally all `man` is doing). Alternatively, a tool can use a pager automatically (as `git help ...` does). So `man` isn't required to have a pager. Whether you should use a pager by default is a different argument. That said, I find pagers annoying because…
I tend to live inside byobu on the command line, or "pure" tmux/screen depending on availability. When opening a man page or similar I do it in a fresh pane so there is less back & forth.
Or of course usually you are using the CLI within a GUI so you have the option of a separate terminal too, or a web browser to the one version or other docs, though when using an external resources rather than the local man page there is the slight gotcha of making sure versions match (the main docs online may be for a newer revision than the one your OS currently has in its package repo).