knife(8) -- Chef Server REST API utility
========================================

## SYNOPSIS

__knife__ _sub-command_ _(options)_

## DESCRIPTION

This manual page documents knife, a command-line utility used to interact with a Chef server directly through the RESTful API. Knife uses sub-commands to take various actions on different types of Chef objects. Some sub-commands take additional options. General options follow sub-commands and their options. A configuration file can be created for common defaults.

Unless otherwise specified, output is in JSON format, and input files are also JSON format.

## GENERAL OPTIONS

  * `-s`, `--server-url` URL:
    Chef Server URL
  * `-k`, `--key` KEY:
    API Client Key
  * `-c`, `--config` CONFIG:
    The configuration file to use
  * `-e`, `--editor` EDITOR:
    Set the editor to use for interactive commands
  * `-f`, `--format` FORMAT:
    Which format to use for output
  * `-l`, `--log_level` LEVEL:
    Set the log level (debug, info, warn, error, fatal)
  * `-L`, `--logfile` LOGLOCATION:
    Set the log file location, defaults to STDOUT
  * `-n`, `--no-editor`:
    Do not open EDITOR, just accept the data as is
  * `-u`, `--user` USER:
    API Client Username
  * `-p`, `--print-after`:
    Show the data after a destructive operation
  * `-v`, `--version`:
    Show chef version
  * `-y`, `--yes`:
    Say yes to all prompts for confirmation
  * `-h`, `--help`:
    Show this message

## SUB-COMMANDS

Knife sub-commands are structured as "_NOUN_ __verb__ _NOUN_ (options)". The sub-commands are meant to be intuitively named. Because the Chef Server API is RESTful, sub-commands generally utilize CRUD operations.

* create (create)
* list and show (read)
* edit (update)
* delete (destroy)

Objects stored on the server support these, as described below.

## GENERAL SUB-COMMANDS

The following are general sub-commands that do not fit within the other object types utilized in the Chef Server API.

__configure__ _(options)_

  * `-i`, `--initial`:
    Create an initial API Client
  * `-r`, `--repository REPO`:
    The path to your chef-repo

Create a configuration file for knife. This will prompt for values to enter into the file. Default values are listed in square brackets if no other entry is typed. See "__CONFIGURATION__" below for available options.

__index rebuild__ _(options)_

  * `-y`, `--yes`:
    don't bother to ask if I'm sure

Rebuilds all the search indexes on the server.

__search INDEX QUERY__ _(options)_

  * `-a`, `--attribute ATTR`:
    Show only one attribute
  * `-i`, `--id-only`:
    Show only the ID of matching objects
  * `-R`, `--rows INT`:
    The number of rows to return
  * `-r`, `--run-list`:
    Show only the run list
  * `-o`, `--sort SORT`:
    The order to sort the results in
  * `-b`, `--start ROW`:
    The row to start returning results at

Search indexes are a feature of the Chef Server and the search sub-command allows querying any of the available indexes using SOLR query syntax. The following data types are indexed for search: _node_, _role_, _client_, _data bag_.

__ssh QUERY COMMAND__ _(options)_

  * `-a`, `--attribute ATTR       `:
    The attribute to use for opening the connection - default is fqdn
  * `-C`, `--concurrency NUM      `:
    The number of concurrent connections
  * `-m`, `--manual-list          `:
    QUERY is a space separated list of servers
  * `-P`, `--ssh-password PASSWORD`:
    The ssh password
  * `-x`, `--ssh-user USERNAME    `:
    The ssh username

The __ssh__ sub-command opens an ssh session to each of the nodes in the search results of the _QUERY_. This sub-command requires that the net-ssh-multi and highline Ruby libraries are installed. On Debian systems, these are the libnet-ssh-multi-ruby and libhighline-ruby packages. They can also be installed as RubyGems (net-ssh-multi and highline, respectively).

## CLIENT SUB-COMMANDS

Clients are entities that communicate with the Chef Server API.

__client bulk delete REGEX__ _(options)_

Delete clients on the Chef Server based on a regular expression. The regular expression (_REGEX_) should be in quotes, not in //'s.

__client create CLIENT__ _(options)_

  * `-a`, `--admin    `:
    Create the client as an admin
  * `-f`, `--file FILE`:
    Write the key to a file

Create a new client. This generates an RSA keypair. The private key will be displayed on _STDOUT_ or written to the named file. The public half will be stored on the Server. For _chef-client_ systems, the private key should be copied to the system as `/etc/chef/client.pem`.

Admin clients should be created for users that will use _knife_ to access the API as an administrator. The private key will generally be copied to `~/.chef/CLIENT.pem` and referenced in the `knife.rb` configuration file.

__client delete CLIENT__ _(options)_

Deletes a registered client.

__client edit CLIENT__ _(options)_

Edit a registered client.

__client list__ _(options)_

  * `-w`, `--with-uri`:
      Show corresponding URIs

List all registered clients.

__client reregister CLIENT__ _(options)_

  * `-f`, `--file FILE`:
    Write the key to a file

Regenerate the RSA keypair for a client. The public half will be stored on the server and the private key displayed on _STDOUT_ or written to the named file.

__client show CLIENT__ _(options)_

  * `-a`, `--attribute ATTR`:
    Show only one attribute

Show a client.

## COOKBOOK SUB-COMMANDS

Cookbooks are the fundamental unit of distribution in Chef. They encapsulate all recipes of resources and assets used to configure a particular aspect of the infrastructure. The following sub-commands can be used to manipulate the cookbooks stored on the Chef Server.

__cookbook bulk delete REGEX__ _(options)_

Delete cookbooks on the Chef Server based on a regular expression. The regular expression (_REGEX_) should be in quotes, not in //'s.

__cookbook delete COOKBOOK__ _(options)_

Delete a single named _COOKBOOK_.

__cookbook download COOKBOOK__ _(options)_

  * `-f`, `--file FILE`:
    The filename to write to

Download a cookbook from the Chef Server as a gzip(1)'ed, tar(1) archive.

__cookbook list__ _(options)_

  * `-w`, `--with-uri`:
    Show corresponding URIs

List all the cookbooks.

__cookbook metadata COOKBOOK__ _(options)_

  * `-a`, `--all`:
    Generate metadata for all cookbooks, rather than just a single cookbook
  * `-o`, `--cookbook-path PATH:PATH`:
    A colon-separated path to look for cookbooks in

Generate cookbook metadata for the named _COOKBOOK_. The _PATH_ used here specifies where the "cookbooks" directory is located and corresponds to the `cookbook_path` configuration option.

__cookbook metadata from FILE__ _(options)_

Load the cookbook metadata from a specified file.

__cookbook show COOKBOOK [PART] [FILENAME]__ _(options)_

  * `-f`, `--fqdn FQDN               `:
    The FQDN of the host to see the file for
  * `-p`, `--platform PLATFORM       `:
    The platform to see the file for
  * `-V`, `--platform-version VERSION`:
    The platform version to see the file for

Show a particular part of a _COOKBOOK_. _PART_ can be one of:

  * _attributes_
  * _definitions_
  * _files_
  * _libraries_
  * _providers_
  * _recipes_
  * _resources_
  * _templates_

__cookbook test [COOKBOOKS...]__ _(options)_

  * `-a`, `--all`:
    Test all cookbooks, rather than just a single cookbook
  * `-o`, `--cookbook-path PATH:PATH`:
    A colon-separated path to look for cookbooks in

Test the specified cookbooks for syntax errors. This uses the built-in Ruby syntax checking option for files in the cookbook ending in `.rb`, and the ERB syntax check for files ending in `.erb` (templates).

__cookbook upload [COOKBOOKS...]__ _(options)_

  * `-a`, `--all`:
    Upload all cookbooks, rather than just a single cookbook
  * `-o`, `--cookbook-path PATH:PATH`:
    A colon-separated path to look for cookbooks in

Uploads the specified cookbooks to the Chef Server. The actual upload executes a number of commands, most of which occur on the local machine. The cookbook is staged in a temporary location. Then the `cookbook_path` (or `-o PATH`) is processed to search for the named cookbook, and each occurance is copied in the order specified. A syntax check is performed a la `cookbook test`, above. The metadata is generated, a la `cookbook metadata`. A gzip(1)'ed, tar(1) file is created, and is uploaded to the server.

## COOKBOOK SITE SUB-COMMANDS

The following sub-commands are still in the context of cookbooks, but they make use of Opscode's Cookbook Community site, _http://cookbooks.opscode.com/_. That site has an API, and these sub-commands utilize that API, rather than the Chef Server API.

__cookbook site download COOKBOOK [VERSION]__ _(options)_

  * `-f`, `--file FILE`:
    The filename to write to

Downloads a specific cookbook from the Community site, optionally specifying a certain version.

__cookbook site list__ _(options)_

  * `-w`, `--with-uri`:
    Show corresponding URIs

Lists available cookbooks from the Community site.

__cookbook site search QUERY__ _(options)_

Searches the Community site with the specified query.

__cookbook site show COOKBOOK [VERSION]__ _(options)_

Shows information from the site about a particular cookbook.

__cookbook site vendor COOKBOOK [VERSION]__ _(options)_

  * `-d`, `--dependencies`:
    Grab dependencies automatically

Downloads a cookbook and untars it in the cookbooks directory. If _-d_ is specified, all the cookbooks it depends on (via metadata _dependencies_) are downloaded and untarred as well.

## DATA BAG SUB-COMMANDS

Data bags are stores of JSON blobs. These blobs are called items. They are free form JSON and indexed by the Chef Server.

__data bag create BAG [ITEM]__ _(options)_

Create a new data bag, or an item in a data bag.

__data bag delete BAG [ITEM]__ _(options)_

Delete a data bag, or an item from a data bag.

__data bag edit BAG ITEM__ _(options)_

Edit an item in a data bag.

__data bag list__ _(options)_

  * `-w`, `--with-uri`:
    Show corresponding URIs

List the available data bags.

__data bag show BAG [ITEM]__ _(options)_

Show a specific data bag or an item in a data bag.

## NODE SUB-COMMANDS

Nodes are the entities which are configured with Chef. Typically these are servers or workstations. Nodes are registered as a client, by default by the fully qualified domain name (fqdn). A single client may configure more than one node.

__node bulk delete REGEX__ _(options)_

Delete nodes on the Chef Server based on a regular expression. The regular expression (_REGEX_) should be in quotes, not in //'s.

__node create NODE__ _(options)_

Create a new node.

__node delete NODE__ _(options)_

Delete a single node.

__node edit NODE__ _(options)_

Edit a node.

__node from file FILE__ _(options)_

Create a node from a JSON file.

__node list__ _(options)_

  * `-w`, `--with-uri`:
    Show corresponding URIs

List all nodes.

`node run_list add [NODE] [ENTRY]` _(options)_

  * `-a`, `--after ITEM`:
    Place the ENTRY in the run list after ITEM

Add a recipe or role to the node's `run_list`.

`node run_list remove [NODE] [ENTRY]` _(options)_

Remove a recipe or role from the node's `run_list`.

__node show NODE__ _(options)_

  * `-a`, `--attribute [ATTR]`:
    Show only one attribute
  * `-r`, `--run-list        `:
    Show only the run list

Show a node.

## ROLE SUB-COMMANDS

__role bulk delete REGEX__ _(options)_

Delete roles on the Chef Server based on a regular expression. The regular expression (_REGEX_) should be in quotes, not in //'s.

__role create ROLE__ _(options)_

  * `-d`, `--description`:
    The role description

Create a new role.

__role delete ROLE__ _(options)_

Delete a role.

__role edit ROLE__ _(options)_

Edit a role.

__role from file FILE__ _(options)_

Create or update a role from a role Ruby DSL (`.rb`) or JSON file.

__role list__ _(options)_

  * `-w`, `--with-uri`:
    Show corresponding URIs

List roles.

__role show ROLE__ _(options)_

  * `-a`, `--attribute ATTR`:
    Show only one attribute

Show a specific role.

## CLOUD COMPUTING SUB-COMMANDS

The next sections describe sub-commands to work with various Cloud Computing APIs to launch server instances with validation and run-time configuration that Chef knows about. These sub-commands require the fog Ruby library. On Debian and Ubuntu systems this is the package `libfog-ruby`. It is also available as a RubyGem, `fog`.

The Rackspace and Terremark sub-commands are early stage of development. Right now when creating instances of these types, knife will assume an Ubuntu image, install Ruby from packages, RubyGems from source and Chef as a RubyGem. As these commands are developed, other installation styles may become available, as options.

## EC2 SUB-COMMANDS

Chef is commonly used with Amazon AWS EC2 nodes. This sub-command will generate instance metadata that can be used to automatically configure an EC2 instance with Chef. This requires an AMI that has Chef preinstalled with a configuration file that can parse the metadata at run-time. At this time this is the only sub-command for EC2, but more may be added later similar to __RACKSPACE__ and __TERREMARK__ below.

__ec2 instance data [RUN LIST...]__ _(options)_

  * `-e`, `--edit`:
    Edit the instance data

The _RUN LIST_ should be specified as a space separated list of roles or recipes that will be used by the instance to configure the server.

## RACKSPACE SUB-COMMANDS

In addition to EC2 nodes, Chef can be used on Rackspace Cloud nodes. The following sub-commands allow manipulating Rackspace Cloud nodes via the `fog` library.

__rackspace server create [RUN LIST...]__ _(options)_

  * `-K`, `--rackspace-api-key KEY`:
    Your rackspace API key
  * `-A USERNAME`, `--rackspace-api-username`:
    Your rackspace API username
  * `-f`, `--flavor FLAVOR   `:
    The flavor of server
  * `-i`, `--image IMAGE     `:
    The image of the server
  * `-N`, `--server-name NAME`:
    The server name

Creates a new Rackspace Cloud server.

__rackspace server delete SERVER__ _(options)_

Deletes a running Rackspace Cloud server.

__rackspace server list__ _(options)_

Lists running Rackspace Cloud servers.

## TERREMARK SUB-COMMANDS

As above, Chef can also be used on Terremark vCloud nodes. The following sub-commands allow manipulating Terremark vCloud nodes via the `fog` library.

__terremark server create NAME [RUN LIST...]__ _(options)_

  * `-K PASSWORD`, `--terremark-password`:
    Your terremark password
  * `-S`, `--terremark-service SERVICE`:
    Your terremark service name
  * `-A USERNAME`, `--terremark-username`:
    Your terremark username

Creates a new Terremark vCloud server.

__terremark server delete SERVER__ _(options)_

Deletes a running Terremark vCloud server.

__terremark server list__ _(options)_

  * `-K PASSWORD`, `--terremark-password`:
    Your terremark password
  * `-S`, `--terremark-service SERVICE`:
    Your terremark service name
  * `-A USERNAME`, `--terremark-username`:
    Your terremark username

Lists running Terremark vCloud servers.

## CONFIGURATION

The knife configuration file is a Ruby DSL. If it exists, knife uses these settings for __GENERAL OPTIONS__ defaults.

`log_level`

A Ruby symbol specifying the log level. Corresponds to `-l` or `--log_level` option. Default is _:info_. Valid values are:

  * :info
  * :debug
  * :warn
  * :fatal

`log_location`

Corresponds to the `-L` or `--log-file` option. Defaults is __STDOUT__. Valid values are __STDOUT__ or a filename.

`node_name`

User to authenticate to the Chef server. Corresponds to the `-u` or `--user` option. This is requested from the user when running this sub-command.

`client_key`

Private key file to authenticate to the Chef server. Corresponds to the `-k` or `--key` option. This is requested from the user when running this sub-command.

`chef_server_url`

URL of the Chef server. Corresponds to the `-s` or `--server-url` option. This is requested from the user when running this sub-command.

`cache_type`

The type of cache to use. Default is BasicFile. This can be any type of Cache that moneta supports: BasicFile, Berkeley, Couch, DataMapper, File, LMC, Memcache, Memory, MongoDB, Redis, Rufus, S3, SDBM, Tyrant, Xattr, YAML.

`cache_options`

Specifies various options to use for caching. Default reads the Chef client configuration (/etc/chef/checksums).

`validation_client_name`

Specifies the name of the client used to validate new clients. This is requested from the user when running the configuration sub-command.

`validation_key`

Specifies the private key file to use for generating ec2 instance data for validating new clients. This is implied from the `validation_client_name`.

## FILES

_~/.chef/knife.rb_

Ruby DSL configuration file for knife. See "__CONFIGURATION__".

## SEE ALSO

Full documentation for Chef is located on the Chef wiki, http://wiki.opscode.com/display/chef/Home/.

JSON is JavaScript Object Notation and more information can be found at http://json.org/.

SOLR is an open source search engine. The Chef Server includes a SOLR installation. More information about SOLR, including the search query syntax, can be found at http://lucene.apache.org/solr/.

This manual page was generated in nroff from Markdown with ronn. Ryan Tomayko wrote ronn and more information can be found at http://rtomayko.github.com/ronn/ronn.5.html.

## AUTHOR

Chef was written by Adam Jacob <adam@opscode.com> of Opscode (http://www.opscode.com), with contributions from the community. This manual page was written by Joshua Timberman <joshua@opscode.com>. Permission is granted to copy, distribute and / or modify this document under the terms of the Apache 2.0 License.

On Debian systems, the complete text of the Apache 2.0 License can be found in `/usr/share/common-licenses/Apache-2.0`.