# knife cookbook site

The Cookbooks Site API is used to provide access to the cookbooks community hosted at https://cookbooks.opscode.com. All of the cookbooks in the community are accessible through a REST API located at https://cookbooks.opscode.com/api/v1/ by using any of the supported endpoints. In most cases, using Knife and the knife cookbook site sub-command (and any of its arguments) is the recommended method of interacting with these cookbooks, but in some cases, using the REST API directly may make sense.

The knife cookbook site subcommand is used to interact with cookbooks that are located at https://cookbooks.opscode.com. A user account is required for any community actions that write data to this site. The following arguments do not require a user account: `download`, `search`, `install`, and `list`.

Note

Review the list of common options available to this (and all) Knife subcommands and plugins.

## download

The `download` argument is used to download a cookbook from the community website. A cookbook will be downloaded as a tar.gz archive and placed in the current working directory. If a cookbook (or cookbook version) has been deprecated and the `--force` option is not used, Knife will alert the user that the cookbook is deprecated and then will provide the name of the most recent non-deprecated version of that cookbook.

### Syntax

This argument has the following syntax:

    $ knife cookbook site download COOKBOOK_NAME [COOKBOOK_VERSION] (options)

### Options

This argument has the following options:

`COOKBOOK_VERSION`
  The version of a cookbook to be downloaded. 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.
`-f`, `--force`
  Indicates that an existing directory will be overwritten.

### Examples

The following examples show how to use this Knife subcommand:

Download a cookbook

To download the cookbook “getting-started”, enter:

    $ knife cookbook site download getting-started

to return something like:

    Downloading getting-started from the cookbooks site at version 0.3.0 to
      /Users/sdanna/opscodesupport/getting-started-0.3.0.tar.gz
    Cookbook saved: /Users/sdanna/opscodesupport/getting-started-0.3.0.tar.gz

## install

The `install` argument is used to install a cookbook that has been downloaded from the community site to a local git repository . This action uses the git version control system in conjunction with the https://cookbooks.opscode.com site to install community-contributed cookbooks to the local chef-repo. Using this argument does the following:

> 1. A new “pristine copy” branch is created in git for tracking the upstream.
> 2. All existing versions of a cookbook are removed from the branch.
> 3. The cookbook is downloaded from https://cookbooks.opscode.com in the tar.gz format.
> 4. The downloaded cookbook is untarred and its contents are committed to git and a tag is created.
> 5. The “pristine copy” branch is merged into the master branch.

This process allows the upstream cookbook in the master branch to be modified while letting git maintain changes as a separate patch. When an updated upstream version becomes available, those changes can be merged while maintaining any local modifications.

### Syntax

This argument has the following syntax:

    $ knife cookbook site install COOKBOOK_NAME [COOKBOOK_VERSION] (options)

### Options

This argument has the following options:

`-b`, `--use-current-branch`
  Indicates that the current branch will be used.
`-B BRANCH`, `--branch BRANCH`
  The name of the default branch. This will default to the master branch.
`COOKBOOK_VERSION`
  The version of the cookbook to be installed. If a version is not specified, the most recent version of the cookbook will be installed.
`-D`, `--skip-dependencies`
  Indicates that all cookbooks to which the installed cookbook has a dependency will not be installed.
`-o PATH:PATH`, `--cookbook-path PATH:PATH`
  The directory in which cookbook are created. This can be a colon-separated path.

### Examples

The following examples show how to use this Knife subcommand:

Install a cookbook

To install the cookbook “getting-started”, enter:

    $ knife cookbook site install getting-started

to return something like:

    Installing getting-started to /Users/sdanna/opscodesupport/.chef/../cookbooks
    Checking out the master branch.
    Creating pristine copy branch chef-vendor-getting-started
    Downloading getting-started from the cookbooks site at version 0.3.0 to
      /Users/sdanna/opscodesupport/.chef/../cookbooks/getting-started.tar.gz
    Cookbook saved: /Users/sdanna/opscodesupport/.chef/../cookbooks/getting-started.tar.gz
    Removing pre-existing version.
    Uncompressing getting-started version /Users/sdanna/opscodesupport/.chef/../cookbooks.
    removing downloaded tarball
    1 files updated, committing changes
    Creating tag cookbook-site-imported-getting-started-0.3.0
    Checking out the master branch.
    Updating 4d44b5b..b4c32f2
    Fast-forward
     cookbooks/getting-started/README.rdoc              |    4 +++
     cookbooks/getting-started/attributes/default.rb    |    1 +
     cookbooks/getting-started/metadata.json            |   29 ++++++++++++++++++++
     cookbooks/getting-started/metadata.rb              |    6 ++++
     cookbooks/getting-started/recipes/default.rb       |   23 +++++++++++++++
     .../templates/default/chef-getting-started.txt.erb |    5 +++
     6 files changed, 68 insertions(+), 0 deletions(-)
     create mode 100644 cookbooks/getting-started/README.rdoc
     create mode 100644 cookbooks/getting-started/attributes/default.rb
     create mode 100644 cookbooks/getting-started/metadata.json
     create mode 100644 cookbooks/getting-started/metadata.rb
     create mode 100644 cookbooks/getting-started/recipes/default.rb
     create mode 100644 cookbooks/getting-started/templates/default/chef-getting-started.txt.erb
    Cookbook getting-started version 0.3.0 successfully installed

## list

The `list` argument is used to view a list of cookbooks that are currently available at https://cookbooks.opscode.com.

### Syntax

This argument has the following syntax:

    $ knife cookbook site list

### Options

This argument has the following options:

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

### Examples

The following examples show how to use this Knife subcommand:

View a list of cookbooks

To view a list of cookbooks at https://cookbooks.opscode.com server, enter:

    $ knife cookbook site list

to return:

    1password             homesick              rabbitmq
    7-zip                 hostname              rabbitmq-management
    AmazonEC2Tag          hosts                 rabbitmq_chef
    R                     hosts-awareness       rackspaceknife
    accounts              htop                  radiant
    ack-grep              hudson                rails
    activemq              icinga                rails_enterprise
    ad                    id3lib                redis-package
    ad-likewise           iftop                 redis2
    ant                   iis                   redmine
    [...truncated...]

## search

The `search` argument is used to search for a cookbook at https://cookbooks.opscode.com. A search query is used to return a list of cookbooks at https://cookbooks.opscode.com and uses the same syntax as the knife search sub-command.

### Syntax

This argument has the following syntax:

    $ knife cookbook site search SEARCH_QUERY (options)

### Options

This command does not have any specific options.

### Examples

The following examples show how to use this Knife subcommand:

Search for cookbooks

To search for all of the cookbooks that can be used with Apache, enter:

    $ knife cookbook site search apache*

to return something like:

    apache2:
      cookbook:              http://cookbooks.opscode.com/api/v1/cookbooks/apache2
      cookbook_description:  Installs and configures apache2 using Debian symlinks with helper definitions
      cookbook_maintainer:   opscode
      cookbook_name:         apache2
    instiki:
      cookbook:              http://cookbooks.opscode.com/api/v1/cookbooks/instiki
      cookbook_description:  Installs instiki, a Ruby on Rails wiki server under passenger+Apache2.
      cookbook_maintainer:   jtimberman
      cookbook_name:         instiki
    kickstart:
      cookbook:              http://cookbooks.opscode.com/api/v1/cookbooks/kickstart
      cookbook_description:  Creates apache2 vhost and serves a kickstart file.
      cookbook_maintainer:   opscode
      cookbook_name:         kickstart
    [...truncated...]

## share

The `share` argument is used to add a cookbook to https://cookbooks.opscode.com. This action will require a user account and a certificate for http://community.opscode.com. By default, Knife will use the user name and API key that is identified in the configuration file used during the upload; otherwise these values must be specified on the command line or in an alternate configuration file. If a cookbook already exists on https://cookbooks.opscode.com, then only an owner or maintainer of that cookbook can make updates.

### Syntax

This argument has the following syntax:

    $ knife cookbook site share COOKBOOK_NAME CATEGORY (options)

### Options

This argument has the following options:

`CATEGORY`
  The cookbook category: `Databases`, `Web Servers`, `Process Management`, `Monitoring and Trending`, `Programming Languages`, `Package Management`, `Applications`, `Networking`, `Operations Systems and Virtualization`, `Utilities`, or `Other`.
`-o PATH:PATH`, `--cookbook-path PATH:PATH`
  The directory in which cookbook are created. This can be a colon-separated path.

### Examples

The following examples show how to use this Knife subcommand:

Share a cookbook

To share a cookbook named “apache2”:

    $ knife cookbook site share "apache2" "Web Servers"

## show

The `show` argument is used to view information about a cookbook on https://cookbooks.opscode.com.

### Syntax

This argument has the following syntax:

    $ knife cookbook site show COOKBOOK_NAME [COOKBOOK_VERSION]

### 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.

### Examples

The following examples show how to use this Knife subcommand:

Show cookbook data

To show the details for a cookbook named “haproxy”:

    $ knife cookbook site show haproxy

to return something like:

    average_rating:
    category:        Networking
    created_at:      2009-10-25T23:51:07Z
    description:     Installs and configures haproxy
    external_url:
    latest_version:  http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/1_0_3
    maintainer:      opscode
    name:            haproxy
    updated_at:      2011-06-30T21:53:25Z
    versions:
       http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/1_0_3
       http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/1_0_2
       http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/1_0_1
       http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/1_0_0
       http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/0_8_1
       http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/0_8_0
       http://cookbooks.opscode.com/api/v1/cookbooks/haproxy/versions/0_7_0

Show cookbook data as JSON

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`.

## unshare

The `unshare` argument is used to stop the sharing of a cookbook at https://cookbooks.opscode.com. Only the maintainer of a cookbook may perform this action.

### Syntax

This argument has the following syntax:

    $ knife cookbook site unshare COOKBOOK_NAME

### Options

This command does not have any specific options.

### Examples

The following examples show how to use this Knife subcommand:

Unshare a cookbook

To unshare a cookbook named “getting-started”, enter:

    $ knife cookbook site unshare getting-started