A newer version of this documentation is available.

View Latest

Accessing data from a command line

The Couchbase command line client, cbc, is part of the C SDK. The most common form of installation is via the Couchbase software repositories, though it can also be built from source or downloaded directly.

Installing cbc on Linux

To install cbc on Linux, you can use a simple Perl setup script that automatically configures your system to use the Couchbase software repositories. Use the following commands to download and execute this script (as root or using sudo):

$ wget http://packages.couchbase.com/clients/c/couchbase-csdk-setup
$ perl couchbase-csdk-setup

The script prompts you before each modification it makes. When done setting up the repository, it installs the C SDK (just a few simple libraries) and the command-line tool.

Installing cbc on OS X

The cbc utility is available with the libcouchbase package, which you can install by using the Homebrew package manager for OS X:

$ brew install libcouchbase

Running the client

The command-line client contains subcommands that perform various operations on the server. The basic commands are:

  • cbc create (create/update documents)

  • cbc cat (retrieve a document)

  • cbc n1ql (execute a query)

  • cbc rm (remove a document).

To point the client at a cluster, provide one of the cluster nodes using the -U argument:

$ cbc cat document_id -U couchbase://

Most commands accept a document ID (key) as a positional argument. Some commands (specifically, mutation commands) require a value as well.

On Unix-like platforms, shortcuts for the various subcommands are available in the form of cbc-<command>. For example, the following commands to retrieve an item are equivalent:

cbc cat foo
cbc-cat foo

The symbolic link works well with your shell’s tab completion features to help you discover new commands.


Unlike most SDKs, the command line client is not JSON-aware. If dealing with JSON documents, ensure that values passed to it are well formed JSON because the cbc program does not do any validation.

Storing a document

Documents can be created or replaced using the create subcommand. To specify one of the mutation modes (such as upsert), use the --mode argument. The default mode is upsert.

The document to be stored can be supplied on the command line using the -V parameter. If the document is large or is the result of another program’s output, cbc-create can also read the document from standard input.

$ cbc-create document_id -V '{"json":"value"}'
$ echo '{"json":"value"}' | cbc-create document_id

If the operation was successful, the client will output the CAS of the document. If an error was received, it will be printed as well.

Retrieving a document

Documents can be retrieved using the cbc-cat command. The document ID to retrieve should be specified as a positional argument.

The output of the command contains the actual document value on stdout and any metadata/error information on stderr.

$ cbc-cat document_id
document_id          CAS=0xe0004ea40100, Flags=0x0. Size=16

The metadata consists of the document’s ID, the CAS, flags, and the size of the document in bytes.

Issuing N1QL queries

The cbc tool can be used as a simple N1QL (query) client. It accepts the query string as its argument.

Ensure the string is properly escaped for the shell. It is best to place the query string in single quotes; this way the shell does not recognize double-quotes or backticks, which are often used in N1QL queries
$ cbc-n1ql 'SELECT airportname, city FROM `travel-sample` WHERE type="airport" LIMIT 2'

Named placeholders can also be specified using the --qarg argument.

$ cbc-n1ql 'SELECT airportname, city FROM `travel-sample` WHERE faa=$faa' --qarg faa='"RNO"'

Other commands

There are many other subcommands available with cbc. Use cbc help to see the full listing.