Provided by: chef_11.8.2-2_all bug

NAME

       knife-cookbook - The man page for the knife cookbook subcommand.

       A cookbook is the fundamental unit of configuration and policy distribution. Each cookbook
       defines a scenario, such as everything needed to install and configure MySQL, and then  it
       contains all of the components that are required to support that scenario, including:

       · Attribute values that are set on nodes

       · Definitions that allow the creation of reusable collections of resources

       · File distributions

       · Libraries that extend the chef-client and/or provide helpers to Ruby code

       · Recipes  that  specify  which resources to manage and the order in which those resources
         will be applied

       · Custom resources and providers

       · Templates

       · Versions

       · Metadata  about  recipes  (including  dependencies),  version   constraints,   supported
         platforms, and so on

       The  knife  cookbook subcommand is used to interact with cookbooks that are located on the
       server or the local chef-repo.

       This subcommand has the following syntax:

       $ knife cookbook [ARGUMENT] (options)

COMMON OPTIONS

       The following options can be run with all Knife sub-commands and plug-ins:

       -c CONFIG, --config CONFIG
              The configuration file to use.

       --color
              Indicates that colored output will be used.

       -d, --disable-editing
              Indicates that $EDITOR will not be opened; data will be accepted as-is.

       --defaults
              Indicates that Knife will use the default  value,  instead  of  asking  a  user  to
              provide one.

       -e EDITOR, --editor EDITOR
              The $EDITOR that is used for all interactive commands.

       -E ENVIRONMENT, --environment ENVIRONMENT
              The  name  of  the environment. When this option is added to a command, the command
              will run only against the named environment.

       -f FILE_NAME, --file FILE_NAME
              Indicates that the private key will be saved to a specified file name.

       -F FORMAT, --format FORMAT
              The output format: summary (default), text, json, yaml, and pp.

       -h, --help
              Shows help for the command.

       -k KEY, --key KEY
              The private key that Knife will use to sign requests made by the API client to  the
              server.

       --no-color
              Indicates that color will not be used in the output.

       -p PASSWORD, --password PASSWORD
              The user password.

       --print-after
              Indicates that data will be shown after a destructive operation.

       -s URL, --server-url URL
              The URL for the server.

       -u USER, --user USER
              The  user name used by Knife to sign requests made by the API client to the server.
              Authentication will fail if the user name does not match the private key.

       -v, --version
              The version of the chef-client.

       -V, --verbose
              Set for more verbose outputs. Use -VV for maximum verbosity.

       -y, --yes
              Indicates that the response to all confirmation prompts will  be  "Yes"  (and  that
              Knife will not ask for confirmation).

BULK DELETE

       The  bulk delete argument is used to delete cookbook files that match a pattern defined by
       a regular expression. The regular expression must be within quotes and not  be  surrounded
       by forward slashes (/).

       Syntax

       This argument has the following syntax:

       $ knife cookbook bulk delete REGEX (options)

       Options

       This argument has the following options:

       -p, --purge
              Indicates  that  a cookbook (or cookbook version) will be removed entirely from the
              server. This action should be used carefully because only one copy  of  any  single
              file  is  stored  on  the server. Consequently, purging a cookbook will disable any
              other cookbook that references one or more files from  a  cookbook  that  has  been
              purged.

       Examples

       To bulk delete many cookbooks, use a regular expression to define the pattern:

       $ knife cookbook bulk delete "^[0-9]{3}$" -p

CREATE

       The  create  argument  is  used  to  create a new cookbook directory on the local machine,
       including the following directories and files:

          · cookbook/attributes

          · cookbook/CHANGELOG.md

          · cookbook/definitions

          · cookbook/files/default

          · cookbook/libraries

          · cookbook/metadata.rb

          · cookbook/providers

          · cookbook/README.md (or .rdoc)

          · cookbook/recipes/default.rb

          · cookbook/resources

          · cookbook/templates/default

       After the cookbook is created, it can be uploaded to the server  using  the  knife  upload
       argument.

       Syntax

       This argument has the following syntax:

       $ knife cookbook create COOKBOOK_NAME (options)

       Options

       This argument has the following options:

       -C COPYRIGHT_HOLDER, --copyright COPYRIGHT_HOLDER
              The  name  of  the copyright holder. This option will place a copyright notice that
              contains the name of the copyright holder in each of the pre-created files. If this
              option  is  not  specified,  a  copyright  name of "your_company_name" will be used
              instead; it can be easily modified later.

       -I LICENSE, --license LICENSE
              The type of license under which a cookbook is distributed: apachev2, gplv2,  gplv3,
              mit,  or  none  (default). This option will place the appropriate license notice in
              the pre-created files. Be aware of the licenses for files inside of a cookbook  and
              be sure to follow any restrictions they describe.

       -m EMAIL, --email EMAIL
              The  email  address for the individual who maintains the cookbook. This option will
              place an email address in each of the pre-created files.  If  this  option  is  not
              specified,  an  email  name  of "your_email" will be used instead; it can be easily
              modified later.

       -o PATH, --cookbook-path PATH
              The directory in which cookbook are created. This can be a colon-separated path.

       -r FORMAT, --readme-format FORMAT
              The document format of the readme file: md (markdown) and rdoc (Ruby docs).

       Examples

       To create a cookbook named "my_cookbook" with copyright, email, license, and readme format
       options specified, enter:

       $ knife cookbook create my_cookbook -C "My Name" -m "my@email.com" -I apachev2 -r md

       to return something like:

       ** Creating cookbook my_cookbook
       ** Creating README for cookbook: my_cookbook
       ** Creating metadata for cookbook: my_cookbook

DELETE

       The  delete  argument  is  used  to delete a specified cookbook or cookbook version on the
       server (and not locally).

       Syntax

       This argument has the following syntax:

       $ knife cookbook delete COOKBOOK_NAME [COOKBOOK_VERSION] (options)

       Options

       This argument has the following options:

       -a, --all
              Indicates that a cookbook and every version of that cookbook will be deleted.

       COOKBOOK_VERSION
              The version of a cookbook to be deleted. If a cookbook has only one  version,  this
              option  does  not need to be specified. If a cookbook has more than one version and
              this option is not specified, Knife will prompt for a version.

       -p, --purge
              Indicates that a cookbook (or cookbook version) will be removed entirely  from  the
              server.  This  action  should be used carefully because only one copy of any single
              file is stored on the server. Consequently, purging a  cookbook  will  disable  any
              other  cookbook  that  references  one  or more files from a cookbook that has been
              purged.

       Examples

       To delete version "0.8" from a cookbook named "smartmon", enter:

       $ knife cookbook delete smartmon 0.8

       Type Y to confirm a deletion.

DOWNLOAD

       The download argument is used to download a  cookbook  from  the  server  to  the  current
       working directory.

       Syntax

       This argument has the following syntax:

       $ knife cookbook download COOKBOOK_NAME [COOKBOOK_VERSION] (options)

       Options

       This argument has the following options:

       -d DOWNLOAD_DIRECTORY, --dir DOWNLOAD_DIRECTORY
              The directory into which a cookbook will be downloaded.

       -f, --force
              Indicates that an existing directory will be overwritten.

       -N, --latest
              Indicates that the most recent version of a cookbook will be downloaded.

       Examples

       To download a cookbook named "smartmon", enter:

       $ knife cookbook download smartmon

LIST

       The  list argument is used to view a list of cookbooks that are currently available on the
       server. The list will contain only the most recent version for each cookbook by default.

       Syntax

       This argument has the following syntax:

       $ knife cookbook list (options)

       Options

       This argument has the following options:

       -a, --all
              Indicates that all available versions of each cookbook will be returned.

       -w, --with-uri
              Indicates that the corresponding URIs will be shown.

       Examples

       To view a list of cookbooks:

       $ knife cookbook list

METADATA

       The metadata argument is used to generate the metadata for one or more cookbooks.

       Syntax

       This argument has the following syntax:

       $ knife cookbook metadata (options)

       Options

       This argument has the following options:

       -a, --all
              Indicates that metadata should be generated for all cookbooks, and not just  for  a
              specified cookbook.

       -o PATH:PATH, --cookbook-path PATH:PATH
              The directory in which cookbook are created. This can be a colon-separated path.

       Examples

       To generate metadata for all cookbooks:

       $ knife cookbook metadata -a

METADATA FROM FILE

       The metadata from file argument is used to load the metadata for a cookbook from a file.

       Syntax

       This argument has the following syntax:

       $ knife cookbook metadata from file FILE

       Options

       This command does not have any specific options.

       Examples

       To view cookbook metadata from a JSON file:

       $ knife cookbook metadta from file /path/to/file

SHOW

       The  show  argument  is  used  to  view  information about a cookbook, parts of a cookbook
       (attributes, definitions, files, libraries, providers, recipes, resources, and templates),
       or  a  file  that  is associated with a cookbook (including attributes such as checksum or
       specificity).

       Syntax

       This argument has the following syntax:

       $ knife cookbook show COOKBOOK_NAME [COOKBOOK_VERSION] [PART...] [FILE_NAME] (options)

       Options

       This argument has the following options:

       COOKBOOK_VERSION
              The version of a cookbook to be shown. If a cookbook has  only  one  version,  this
              option  does  not need to be specified. If a cookbook has more than one version and
              this option is not specified, a list of cookbook versions will be returned.

       -f FQDN, --fqdn FQDN
              The FQDN of the host.

       FILE_NAME
              The name of a file that is associated with a cookbook.

       -p PLATFORM, --platform PLATFORM
              The platform for which a cookbook is designed.

       PART   The part of the  cookbook  to  show:  attributes,  definitions,  files,  libraries,
              providers, recipes, resources, or templates. More than one part can be specified.

       -V PLATFORM_VERSION, --platform-version PLATFORM_VERSION
              The version of the platform.

       -w, --with-uri
              Indicates that the corresponding URIs will be shown.

       Examples

       To get the list of available versions of a cookbook named "getting-started", enter:

       $ knife cookbook show getting-started

       to return something like:

       getting-started   0.3.0  0.2.0

       To  show  a  list of data about a cookbook using the name of the cookbook and the version,
       enter:

       $ knife cookbook show getting-started 0.3.0

       to return something like:

       attributes:
         checksum:     fa0fc4abf3f6787aeb5c3c5c35de667c
         name:         default.rb
         path:         attributes/default.rb
         specificity:  default
         url:          https://somelongurlhere.com
       chef_type:      cookbook_version
       cookbook_name:  getting-started
       definitions:    []
       files:          []
       frozen?:        false
       json_class:     Chef::CookbookVersion
       libraries:      []

       To only view data about "templates", enter:

       $ knife cookbook show getting-started 0.3.0 templates

       to return something like:

       checksum:     a29d6f254577b830091f140c3a78b1fe
       name:         chef-getting-started.txt.erb
       path:         templates/default/chef-getting-started.txt.erb
       specificity:  default
       url:          https://someurlhere.com

       To view information in JSON format, use the -F common option as part of the  command  like
       this:

       $ knife role show devops -F json

       Other formats available include text, yaml, and pp.

TEST

       The  test  argument  is used to test a cookbook for syntax errors. This argument uses Ruby
       syntax checking to verify every file in a cookbook that ends  in  .rb  and  Embedded  Ruby
       (ERB).

       Syntax

       This argument has the following syntax:

       $ knife cookbook test COOKBOOK_NAME (options)

       Options

       This argument has the following options:

       -a, --all
              Indicates that all cookbooks will be tested.

       -o PATH:PATH, --cookbook-path PATH:PATH
              The directory in which cookbook are created. This can be a colon-separated path.

       Examples

       To test a cookbook named "getting-started", enter:

       $ knife cookbook test getting-started

UPLOAD

       The  upload  argument  is  used  to  upload  one or more cookbooks (and any files that are
       associated with those cookbooks) from a local repository to the server. Only files that do
       not already exist on the server will be uploaded.

       Note   Use  a chefignore file to prevent the upload of specific files and file types, such
              as temporary files or files placed in  folders  by  version  control  systems.  The
              chefignore file must be located in the root of the cookbook repository and must use
              rules similar to filename globbing (as defined by the Ruby File.fnmatch syntax).

       Syntax

       This argument has the following syntax:

       $ knife cookbook upload [COOKBOOK_NAME...] (options)

       Options

       This argument has the following options:

       -a, --all
              Indicates that all cookbooks will be uploaded.

       -d, --include-dependencies
              Indicates that when a cookbook has a dependency on one (or more)  cookbooks,  those
              cookbooks will also be uploaded.

       --force
              Indicates that a cookbook should be updated even if the --freeze flag has been set.

       --freeze
              Indicates  that a cookbook cannot be modified; any changes to this cookbook must be
              included as a new version. Only the --force option can override this setting.

       -o PATH:PATH, --cookbook-path PATH:PATH
              The directory in which cookbook are created. This can be a colon-separated path.

       Examples

       To upload a cookbook named "getting-started":

       $ knife cookbook upload getting-started

       To upload a cookbook, and then prevent other users from being able to make changes to  it,
       enter:

       $ knife cookbook upload redis --freeze

       to return something like:

       Uploading redis...
       Upload completed

       If  a  cookbook  is  frozen  and the --force option is not specified, Knife will return an
       error message similar to the following:

       Uploading redis...
       ERROR: Version 0.1.6 of cookbook redis is frozen. Use --force to override.

AUTHOR

       Opscode

                                           Chef 11.8.0                          KNIFE-COOKBOOK(1)