https://github.com/chef/mixlib-cli

A mixin for creating command line applications - gives an easy DSL for argument specification and processing
https://github.com/chef/mixlib-cli

Keywords from Contributors

chef configuration-management discovery ohai cfgmgt deployment rubygems crash-reporting static-code-analysis rubocop

Last synced: about 5 hours ago
JSON representation

Repository metadata

A mixin for creating command line applications - gives an easy DSL for argument specification and processing

Host: GitHub
URL: https://github.com/chef/mixlib-cli
Owner: chef
License: apache-2.0
Created: 2009-03-13T00:42:30.000Z (almost 17 years ago)
Default Branch: main
Last Pushed: 2026-01-27T03:21:47.000Z (about 1 month ago)
Last Synced: 2026-02-10T04:40:00.413Z (22 days ago)
Language: Ruby
Homepage: https://www.chef.io
Size: 301 KB
Stars: 118
Watchers: 65
Forks: 41
Open Issues: 10
Releases: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Notice: NOTICE

Mixlib::CLI

Umbrella Project: Chef Foundation

Project State: Active

Issues Response Time Maximum: 14 days

Pull Request Response Time Maximum: 14 days

Mixlib::CLI provides a class-based command line option parsing object, like the one used in Chef, Ohai and Relish. To use in your project:

require "mixlib/cli"

class MyCLI
  include Mixlib::CLI

  option :config_file,
    short: "-c CONFIG",
    long: "--config CONFIG",
    default: "config.rb",
    description: "The configuration file to use"

  option :log_level,
    short: "-l LEVEL",
    long: "--log_level LEVEL",
    description: "Set the log level (debug, info, warn, error, fatal)",
    required: true,
    in: [:debug, :info, :warn, :error, :fatal],
    proc: Proc.new { |l| l.to_sym }

  option :help,
    short: "-h",
    long: "--help",
    description: "Show this message",
    on: :tail,
    boolean: true,
    show_options: true,
    exit: 0

end

# ARGV = [ '-c', 'foo.rb', '-l', 'debug' ]
cli = MyCLI.new
cli.parse_options
cli.config[:config_file] # 'foo.rb'
cli.config[:log_level]   # :debug

If you are using this in conjunction with Mixlib::Config, you can do something like this (building on the above definition):

class MyConfig
  extend(Mixlib::Config)

  log_level   :info
  config_file "default.rb"
end

class MyCLI
  def run(argv = ARGV)
    parse_options(argv)
    MyConfig.merge!(config)
  end
end

c = MyCLI.new
# ARGV = [ '-l', 'debug' ]
c.run
MyConfig[:log_level] # :debug

For supported arguments to option, see the function documentation in lib/mixlib/cli.rb.

If you need access to the leftover options that aren't captured in the config, you can get at them through +cli_arguments+ (referring to the above definition of MyCLI).

# ARGV = [ '-c', 'foo.rb', '-l', 'debug', 'file1', 'file2', 'file3' ]
cli = MyCLI.new
cli.parse_options
cli.cli_arguments # [ 'file1', 'file2', 'file3' ]

Deprecating CLI Options

mixlib-cli 2.1.0 and later supports declaring options as deprecated. Using a deprecated option
will result in a warning message being displayed. If a deprecated flag is supplied,
its value is assigned to the replacement flag. You can control this assignment by specifying a
value_mapper function in the arguments (see example below, and function docs)

Usage notes (see docs for arguments to Mixlib::CLI::ClassMethods#deprecated_option for more):

Define deprecated items last, after all non-deprecated items have been defined.
You will see errors if your deprecated item references a replacement that hasn't been defined yet.
deprecated_option only takes a subset of 'option' configuration. You can only specify short, long - these should
map to the short/long values of the option from before its deprecation.
- item description will automatically be generated along the lines of "-f/--flag is deprecated. Use -n/--new-flag instead."
- if the replacement argument is not given, item description will look like "-f/--flag is deprecated and will be removed in a future release"

Example

Given the following example:


# my_cli.rb

class MyCLI
  include Mixlib::CLI


  option :arg_not_required,
    description: "This takes no argument.",
    long: "--arg-not-required",
    short: "-n"

  option :arg_required,
    description: "This takes an argument.",
    long: "--arg-required ARG",
    short: "-a",
    in: ["a", "b", "c"]

  deprecated_option :dep_one,
    short: "-1",
    long: "--dep-one",
    # this deprecated option maps to the '--arg-not-required' option:
    replacement: :arg_not_required,
    # Do not keep 'dep_one' in `config` after parsing.
    keep: false

  deprecated_option :dep_two,
    short: "-2",
    long: "--dep-two ARG",
    replacement: :arg_required,
    # will map the  given value to a valid value for `--arg-required`.
    value_mapper: Proc.new { |arg|
      case arg
      when "q"; "invalid" # We'll use this to show validation still works
      when "z"; "a"
      when "x"; "b"
      else
        "c"
      end
    }

end

c = MyCLI.new()
c.parse_options

puts "arg_required: #{c.config[:arg_required]}" if c.config.key? :arg_required
puts "arg_not_required: #{c.config[:arg_not_required]}" if c.config.key? :arg_not_required
puts "dep_one: #{c.config[:dep_one]}" if c.config.key? :dep_one
puts "dep_two: #{c.config[:dep_two]}" if c.config.key? :dep_two

In this example, --dep-one will be used. Note that dep_one will not have a value of its own in
options because keep: false was given to the deprecated option.


$ ruby my_cli.rb --dep-one

-1/--dep-one: This flag is deprecated. Use -n/--arg-not-required instead
arg_not_required: true

In this example, the value provided to dep-two will be converted to a value
that --arg-required will accept,a nd populate :arg\_required with


$ ruby my_cli.rb --dep-two z # 'q' maps to 'invalid' in the value_mapper proc above

-2/--dep-two: This flag is deprecated. Use -a/--arg-required instead.

arg_required: a # The value is mapped to its replacement using the function provided.
dep_two: z  # the deprecated value is kept by default

In this example, the value provided to dep-two will be converted to a value
that --arg-required will reject, showing how content rules are applied even when
the input is coming from a deprecated option:

$ ruby my_cli.rb --dep-two q

-2/--dep-two: This flag is deprecated. Use -a/--arg-required instead.
-a/--arg-required: invalid is not one of the allowed values: 'a', 'b', or 'c'

Documentation

Class and module documentation is maintained using YARD. You can generate it by running:

rake docs

You can serve them locally with live refresh using:

bundle exec yard server --reload

Contributing

For information on contributing to this project please see our Contributing Documentation

License & Copyright

Copyright:: Copyright (c) 2008-2018 Chef Software, Inc.
License:: Apache License, Version 2.0

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Owner metadata

Name: Progress Chef
Login: chef
Email: ops@chef.io
Kind: organization
Description:
Website: https://www.chef.io/
Location: United States of America
Twitter: chef
Company:
Icon url: https://avatars.githubusercontent.com/u/29740?v=4
Repositories: 245
Last ynced at: 2023-04-10T00:51:04.360Z
Profile URL: https://github.com/chef

GitHub Events

Total

Delete event: 4
Member event: 1
Pull request event: 15
Fork event: 2
Issues event: 1
Issue comment event: 8
Push event: 22
Pull request review event: 8
Create event: 14

Last Year

Delete event: 4
Member event: 1
Pull request event: 15
Fork event: 1
Issue comment event: 8
Push event: 22
Pull request review event: 8
Create event: 14

Committers metadata

Last synced: 2 days ago

Total Commits: 222
Total Committers: 45
Avg Commits per committer: 4.933
Development Distribution Score (DDS): 0.676

Commits in past year: 19
Committers in past year: 7
Avg Commits per committer in past year: 2.714
Development Distribution Score (DDS) in past year: 0.579

Name	Email	Commits
Tim Smith	t**h@c**o	72
Chef Expeditor	c**i@c**o	37
danielsdeleo	d**n@o**m	13
John Keiser	j**r@o**m	10
Lamont Granquist	l**t@s**g	7
Chef Expeditor	e**i@c**o	6
AJ Christensen	aj@j****z	5
Chef Expeditor	e**r@c**o	4
Thom May	t**m@c**o	4
Chris Roberts	c**e@g**m	4
Phil Dibowitz	p**l@i**m	4
Mehrez Alachheb	l**z@g**m	4
Adam Jacob	a**m@o**m	4
Christopher Brown	cb@o****m	3
John McCrae	j**e@p**m	3
Marc A. Paradise	m**e@g**m	3
dreamcat4	d**4@g**m	3
jayashri garud	j**d@m**m	3
Noah Kantrowitz	n**h@c**t	2
Tom Duffield	t**m@c**o	2
dependabot[bot]	4****]	2
Mehrez Alachheb	m**b@i**r	2
Stephen Delano	s**n@o**l	2
sersut	s**r@o**m	2
dependabot-preview[bot]	2****]	1
chef-expeditor[bot]	4****]	1
brianLoomis	l**s@p**m	1
Tyler Ball	t****l	1
Tsubasa Takayama	t**1@g**m	1
Swati Keshari	s**i@m**m	1
and 15 more...

Committer domains:

Issue and Pull Request metadata

Last synced: 10 days ago

Total issues: 20
Total pull requests: 104
Average time to close issues: 10 months
Average time to close pull requests: 3 months
Total issue authors: 20
Total pull request authors: 38
Average comments per issue: 1.2
Average comments per pull request: 1.34
Merged pull request: 71
Bot issues: 1
Bot pull requests: 22

Past year issues: 1
Past year pull requests: 19
Past year average time to close issues: N/A
Past year average time to close pull requests: 22 days
Past year issue authors: 1
Past year pull request authors: 8
Past year average comments per issue: 0.0
Past year average comments per pull request: 0.05
Past year merged pull request: 10
Past year bot issues: 0
Past year bot pull requests: 3

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/chef/mixlib-cli

Top Issue Authors

rbuck (1)
kagarmoe (1)
bararchy (1)
mwrock (1)
marcparadise (1)
tpowell-progress (1)
skewart (1)
kvivek1115 (1)
rubiojr (1)
dafyddcrosby (1)
bjoernalbers (1)
Saburesh07 (1)
cmparkinson (1)
dmitrypol (1)
grawlinson (1)

Top Pull Request Authors

tas50 (25)
dependabot[bot] (21)
lamont-granquist (6)
jaymzh (5)
danielsdeleo (4)
cgunasree08 (4)
Saburesh07 (2)
kvivek1115 (2)
johnmccrae (2)
tduffield (2)
jayashrig158 (2)
sean-sype-simmons (2)
marcparadise (2)
tsub (1)
ksubrama (1)

Top Issue Labels

Status: Untriaged (4)
Triage: Feature Request (4)
Type: Bug (3)
Status: Good First Issue (1)
oss-standards (1)

Top Pull Request Labels

dependencies (22)
Expeditor: Skip All (9)
oss-standards (5)
Expeditor: Bump Version Minor (4)
ruby (3)
Type: Enhancement (2)
Triage: Needs Information (1)
Aspect: Documentation (1)
Type: Bug (1)
ai-assisted (1)

Package metadata

Total packages: 11
Total downloads:
- rubygems: 143,210,271 total
Total docker downloads: 932,625,762
Total dependent packages: 123 (may contain duplicates)
Total dependent repositories: 8,487 (may contain duplicates)
Total versions: 47
Total maintainers: 3

gem.coop: mixlib-cli

A simple mixin for CLI interfaces, including option parsing

Homepage: https://github.com/chef/mixlib-cli
Documentation: http://www.rubydoc.info/gems/mixlib-cli/
Licenses: Apache-2.0
Latest release: 2.1.8 (published over 5 years ago)
Last Synced: 2026-02-28T12:01:44.480Z (3 days ago)
Versions: 19
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 71,598,831 Total
Docker Downloads: 466,312,881
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 0.155%
- Docker downloads count: 0.225%
- Downloads: 0.395%
Maintainers (3)

rubygems.org: mixlib-cli

A simple mixin for CLI interfaces, including option parsing

Homepage: https://github.com/chef/mixlib-cli
Documentation: http://www.rubydoc.info/gems/mixlib-cli/
Licenses: Apache-2.0
Latest release: 2.1.8 (published over 5 years ago)
Last Synced: 2026-03-02T00:03:41.927Z (1 day ago)
Versions: 19
Dependent Packages: 123
Dependent Repositories: 8,487
Downloads: 71,611,440 Total
Docker Downloads: 466,312,881
Rankings:
- Docker downloads count: 0.276%
- Dependent packages count: 0.279%
- Dependent repos count: 0.353%
- Downloads: 0.399%
- Average: 1.73%
- Forks count: 4.097%
- Stargazers count: 4.979%
Maintainers (3)

ubuntu-24.04: ruby-mixlib-cli

Homepage: https://github.com/chef/mixlib-cli
Licenses:
Latest release: 2.1.6-1 (published 25 days ago)
Last Synced: 2026-02-06T15:34:30.442Z (25 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:

debian-11: ruby-mixlib-cli

Homepage: https://github.com/chef/mixlib-cli
Documentation: https://packages.debian.org/bullseye/ruby-mixlib-cli
Licenses:
Latest release: 2.1.6-1 (published 21 days ago)
Last Synced: 2026-02-13T08:22:37.247Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-23.04: ruby-mixlib-cli

Homepage: https://github.com/chef/mixlib-cli
Licenses:
Latest release: 2.1.6-1 (published 20 days ago)
Last Synced: 2026-02-11T06:43:41.496Z (20 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-23.10: ruby-mixlib-cli

Homepage: https://github.com/chef/mixlib-cli
Licenses:
Latest release: 2.1.6-1 (published 18 days ago)
Last Synced: 2026-02-13T18:25:50.273Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-20.04: ruby-mixlib-cli

Homepage: https://github.com/chef/mixlib-cli
Licenses:
Latest release: 2.1.6-1 (published 18 days ago)
Last Synced: 2026-02-13T07:17:52.728Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

ubuntu-22.04: ruby-mixlib-cli

Homepage: https://github.com/chef/mixlib-cli
Licenses:
Latest release: 2.1.6-1 (published 18 days ago)
Last Synced: 2026-02-13T13:20:43.492Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

debian-12: ruby-mixlib-cli

Homepage: https://github.com/chef/mixlib-cli
Documentation: https://packages.debian.org/bookworm/ruby-mixlib-cli
Licenses:
Latest release: 2.1.6-1 (published 19 days ago)
Last Synced: 2026-02-12T23:35:16.038Z (19 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:

ubuntu-24.10: ruby-mixlib-cli

Homepage: https://github.com/chef/mixlib-cli
Licenses:
Latest release: 2.1.6-1 (published 22 days ago)
Last Synced: 2026-02-09T16:57:23.168Z (22 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:

debian-13: ruby-mixlib-cli

Homepage: https://github.com/chef/mixlib-cli
Documentation: https://packages.debian.org/trixie/ruby-mixlib-cli
Licenses:
Latest release: 2.1.6-1 (published 19 days ago)
Last Synced: 2026-02-13T13:17:34.395Z (18 days ago)
Versions: 1
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 100%

Dependencies

Gemfile rubygems

chefstyle >= 0 development
github-markup >= 0 development
pry >= 0 development
pry-byebug >= 0 development
pry-stack_explorer ~> 0.4.0 development
rake >= 0 development
rb-readline >= 0 development
redcarpet >= 0 development
rspec ~> 3.0 development
rubocop-ast ~> 1.4.1 development
yard >= 0 development

.github/workflows/lint.yml actions

actions/checkout v4 composite
r7kamura/rubocop-problem-matchers-action v1 composite
ruby/setup-ruby v1 composite

.github/workflows/archived/ci-main-pull-request-checks.yml actions

.github/workflows/unit.yml actions

actions/checkout v4 composite
ruby/setup-ruby v1 composite

.github/workflows/ci-main-pull-request-stub-1.0.7.yml actions

mixlib-cli.gemspec rubygems

Score: 29.45506528553641