cmdr

cmdr is a POSIX-compliant, command-line UI (CLI) library in Golang. It is a getopt-like parser of command-line options, be compatible with the getopt_long command line UI, which is an extension of the syntax recommended by POSIX.

We made many enhancements beyond the standard library flag.

There is a fully-functional Options Store (configurations) for your hierarchical configuration dataset too.

The .netCore version Cmdr.Core is available now. And, a cxx version cmdr-cxx was pre-released just now (Happy Spring Festival 2021).

See the image frames at #1.

See our extras:

• cmdr-docs: documentations (Working)
• cmdr-addons: a new daemon plugin dex for linux/macOS/windows.
• cmdr-examples: collects the samples for cmdr
• cmdr-go-starter: public template repo to new your cli app

and Bonus of #cmdr Series:

• dotnetCore: Cmdr.Core
• C++17 or higher: cmdr-cxx

News

• docs (WIP):

  • english documentation NOT completed yet
  • documentation at: https://hedzr.github.io/cmdr-docs/

• v1.10.11 (WIP)

• v1.10.9

  • fix: setNx with slices merging
  • fix: aliases might be added to multiple groups
  • fea: secondary config file locations

• v1.10.8

  • fix/fea/imp: make cmdr aliases subsystem better

• v1.10.7

  • fix: generate shell may be lost buffered contents on writing to file

• v1.10.6

  • fix: internal commands and flags has wrong group declarations since last refactored.
  • fea: -o file for generate shell command.

• v1.10.5

  • fix: logex might crash on a nil skip field

• v1.10.3

  • last release failed because some deps cannot committed due to weak network

• v1.10.1

  • move to go1.17 to get a split declaration
  • fix: added the forgotten long-desc field
  • fix: transfer proper log-level to hedzr/log if in debug/trace mode
  • fix/imp: log.ForDir, ForFile
  • fix: log.LeftPad
  • fea: added InvokeCommand to run a sub-command from somewhere

• v1.10.0

  • fix: toggle-group key not sync while set via envvar
  • imp: speed up by extracting a re compiling code
  • imp: upgrade deps with more enh-helpers from hedzr/log
  • imp: yaml indent size
  • imp: StripOrderPrefix
  • imp/fix: sync debug/trace mode back to hedzr/log
  • fix: options after tail args (positional args) might be ignored
  • fix: ResetOptions not clean up internal hierarchy-list
  • fea: added Checkpoints on Option Store
    you may save and restore multiple checkpoints for cmdr Option Store, so that some temporary changes can be made.
  • fix/imp: --man crashes if manpages not installed - the responding manpage will be generated temporarily and instantly now
  • add GitSummary field into conf package
  • imp: speed up by reduce get worker
    • centralize rxxtOptions to store()
    • flatten backtrace(Flg|Cmd)Names, added dottedPathToCommand
  • NOTE: the phrase wrapped by backtick(````) in Description field will be extracted as `DefaultValuePlaceholder` field automatically, so beware this feature.
  • fea: -vv (dup -v more than once) will print the hidden commands & flags in help screen NOW.
    To take a sight of running fluent generate --help --verbose -verbose.
  • ...

• v1.9.9

  • improved: prevent sent to closed channel defensively
  • SPECIAL: needs go1.16+ because some indirect-dep-lib wants io/fs (such as .../toml, zap ...).

• v1.9.8

  • upgrade log and logex
  • added DebugOutputTildeInfo()

• v1.9.7

  • fixed: dead-lock while setting up env keys

• v1.9.6

  • fixed: incorrect rune count at calc escaped text in help screen.
  • remove deprecated internal options: --help-zsh, --help-bash
  • add new option --man to enter manpage entry of a sub-command, try fluent ms tags ls --man. [linux/darwin only]
  • fixed: Flag.Action return err but cmdr.Exec no breaking its flow.

• v1.9.5

  • improved: zsh completion generator (app gen sh --zsh/--auto) - supports unlimited nested sub-command now.

• v1.9.4

  • fixed: potential nil exception while writing back to the alternative config files
  • fixed: wrong calculating on remain args sometimes
  • improved: rewrote builtin options constructions
  • added 'cmdr.version' into Option Store
  • added some tool helpers
  • improved: zsh completion generator (app gen sh --zsh/--auto)

• v1.9.3

  • fixed: commands might not work when loading from config file. ref: fluent services kx3, and/or fluent ls/pwd
  • fixed: incorrect usage on bytes.Buffer, for toggle-group choicer

• v1.9.2

  • fixed: parsing not stop while a should-be-stopped flag (such as --version) found
  • fixed: incorrect usage line at top level help screen
  • improved: better toggle-group show in help screen
    new style for ToggleGroup items: A unicode character '⬡'(U+2B21) as the prefix of the option description. (see here)
  • improved: better toggle-group choicer in help screen 1. '⬢'(U+2B22) & '⬡'(U+2B21) for the default choicer style (named as hexagon), 1. '▸'(U+25B8) & '▹'(U+25B9) as another one (triangle-right),
  • improved: WithToggleGroupChoicerStyle(style) and WithToggleGroupChoicerNewStyle(style, trueChoicer, falseChoicer).

• v1.9.1:

  • A public template repo may simplify your new CLI app: cmdr-go-starter.
  • crashed at an elder fsnotify on macOS, with go1.17
  • minor fixes

• v1.9.0

  • .fossa.yaml so a pre-release scan can be launched locally
  • BREAK: remove plugin/daemon - use cmdr-addons/pkg/plugins/dex instead
  • updated log, added: closers, detects and more
  • use closers for better closing hooks
  • just a early BREAK release

• More details at CHANGELOG

Features

Features.md

Old README.md: README.old.md

For Developer

For Developer

Import cmdr

With go-modules enabled:

import "github.com/hedzr/cmdr"

About the Docker build

Here is a docker build for cmdr/examples/fluent so that you can run it without go building or downloading the release files:

# from Docker Hub:
$ docker run -it --rm hedzr/cmdr-fluent
$ docker run -it --rm hedzr/cmdr-fluent --help

# from Github Packages (please following the guide of GitHub Packages Site):
$ docker run -it --rm docker.pkg.github.com/hedzr/cmdr/cmdr-fluent
$ docker run -it --rm docker.pkg.github.com/hedzr/cmdr/cmdr-fluent --help

Examples

1. short
   simple codes with structured data style.

2. demo
   normal demo with external config files.

3. wget-demo
   partial-covered for GNU wget.

4. fluent
   demostrates how to define your command-ui with the fluent api style.

5. ffdemo

   a demo to show you how to migrate from go flag smoothly.

6. cmdr-http2
   http2 server with daemon supports, graceful shutdown

7. awesome-tool
   awesome-tool is a cli app that fetch the repo stars and generate a markdown summary, accordingly with most of awesome-xxx list in github (such as awesome-go).

See Also the examples index: Examples.md (zh-cn TODO: Examples.zh-cn.md)

Uses

• https://github.com/hedzr/consul-tags
• https://github.com/hedzr/ini-op
• https://github.com/hedzr/awesome-tool
• austr
• Issue me to adding yours

Contrib

Feel free to issue me bug reports and fixes. Many thanks to all contributors.

Thanks to JODL

Thanks to JetBrains for donating product licenses to help develop cmdr

License

MIT