Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CBC(1)									CBC(1)

       cbc - Couchbase Client Commandline Utility

       cbc COMMAND [OPTIONS]
       cbc help
       cbc version
       cbc cat KEYS ...	[OPTIONS]
       cbc create KEY -V VALUE [OPTIONS]
       cbc create KEY [OPTIONS]
       cbc cp FILES ...	[OPTIONS]
       cbc incr	KEY [OPTIONS]
       cbc decr	KEY [OPTIONS]
       cbc rm KEY [OPTIONS]
       cbc hash	KEY [OPTIONS]
       cbc stats KEYS ... [OPTIONS]
       cbc observe KEYS	... [OPTIONS]
       cbc view	VIEWPATH [OPTIONS]
       cbc lock	KEY [OPTIONS]
       cbc unlock KEY CAS [OPTIONS]
       cbc admin -P PASSWORD RESTAPI [OPTIONS]
       cbc bucket-create -P PASSWORD NAME [OPTIONS]
       cbc bucket-delete -P PASSWORD NAME [OPTIONS]
       cbc bucket-flush	NAME [OPTIONS]
       cbc connstr SPEC
       cbc n1ql	QUERY ... [OPTIONS]

       cbc is a	utility	for communicating with a Couchbase cluster.

       cbc  should be invoked with the command name first and then a series of
       command options appropriate for the specific command. cbc help will al-
       ways show the full list of available commands.

       Options	may be read either from	the command line, or from a configura-
       tion file (see cbcrc(4)):

       The following common options may	be applied to most of the commands

       -U, --spec=SPEC
	      A	string describing the cluster to connect to. The string	is  in
	      a	 URI-like  syntax, and may also	contain	other options. See the
	      EXAMPLES section for information.	Typically such a URI will look
	      like couchbase://host1,host2,host3/bucket.

	      The default for this option is couchbase://localhost/default

       -u, --username=USERNAME
	      Specify  the username for	the bucket. As of Couchbase Server 2.5
	      this field should	be either left empty or	set to the name	of the
	      bucket itself.

       -P, --password=SASLPASS:

       -P -, --password=-
	      Specify the SASL password	for the	bucket.	This is	only needed if
	      the bucket is protected with a password. Note that this  is  not
	      the administrative password used to log into the web interface.

	      Specifying  the  -  as  the  password indicates that the program
	      should prompt for	the password. You may also specify  the	 pass-
	      word  on	the  commandline, directly, but	is insecure as command
	      line arguments are visible via commands such as ps.

       -T, --timings
	      Dump command timings at the end of execution. This will  display
	      a	histogram showing the latencies	for the	commands executed.

       -v, --verbose
	      Specify more information to standard error about what the	client
	      is doing.	You may	specify	this option  multiple  times  for  in-
	      creased output detail.

       -D, --cparam=OPTION=VALUE
	      Provide  additional  client options. Acceptable options can also
	      be placed	in the connection string, however this option is  pro-
	      vided  as	 a  convenience. This option may be specified multiple
	      times, each time specifying a key=value pair (for	example, -Dop-
	      eration_timeout=10  -Dconfig_cache=/foo/bar/baz).	See ADDITIONAL
	      OPTIONS for more information

       The following options may be included in	the connection string (via the
       -U  option) as URI-style	query params (e.g. couchbase://host/bucket?op-
       tion1=value1&option2=value2) or as individual key=value pairs passed to
       the  -D switch (e.g. -Doption1=value1 -Doption2=value). The -D will in-
       ternally	build the connection string, and is provided as	a  convenience
       for options to be easily	passed on the command-line

	      Specify  the  operation timeout in seconds. This is the time the
	      client will wait for an operation	to complete before  timing  it
	      out. The default is 2.5

	      Enables  the  client  to	make use of a file based configuration
	      cache rather than	connecting for the bootstrap operation.	If the
	      file  does not exist, the	client will first connect to the clus-
	      ter and then cache the bootstrap information in the file.

	      The path to the server's SSL certificate.	This is	typically  re-
	      quired  for  SSL connectivity unless the certificate has already
	      been added to the	openssl	installation on	the system  (only  ap-
	      plicable with couchbases:// scheme)

	      Temporarily  disable  certificate	verification for SSL (only ap-
	      plicable with couchbases:// scheme). This	should	only  be  used
	      for quickly debugging SSL	functionality.

	      Force  a	specific SASL mechanism	to be used when	performing the
	      initial connection. This should only need	to be modified for de-
	      bugging  purposes.  The currently	supported mechanisms are PLAIN
	      and CRAM-MD5

	      Specify the bootstrap protocol the client	should	use  when  at-
	      tempting to connect to the cluster. Options are: cccp: Bootstrap
	      using the	Memcached protocol  (supported	on  clusters  2.5  and
	      greater);	 http:	Bootstrap  using  the HTTP REST	protocol (sup-
	      ported on	any cluster version); and both:	 First	attempt	 boot-
	      strap  over the Memcached	protocol, and use the HTTP protocol if
	      Memcached	bootstrap fails. The default is	both

       The following commands are supported by cbc.  Unless  otherwise	speci-
       fied, each command supports all of the options above.

       Write the value of keys to standard output.

       This  command  requires	that at	least one key may be passed to it, but
       may accept multiple keys. The keys should be  specified	as  positional
       arguments after the command.

       In  addition  to	 the options in	the OPTIONS section, the following op-
       tions are supported:

       r, --replica=all|INDEX
	      Read the value from a replica server. The	value for this	option
	      can  either be the string	all which will cause the client	to re-
	      quest the	value from each	replica, or INDEX  where  INDEX	 is  a
	      0-based replica index.

       e, --expiry=EXPIRATION
	      Specify  that this operation should be a get-and-touch operation
	      in which the key's expiry	time is	updated	along with  retrieving
	      the item.

       Create  a  new  item in the cluster, or update the value	of an existing
       item. By	default	this command will read the value from  standard	 input
       unless the --value option is specified.

       The  cp	command	 functions  the	 same, except it operates on a list of
       files. Each file	is stored in the cluster under the name	 specified  on
       the command line.

       In  addition  to	 the options in	the OPTIONS section, the following op-
       tions are supported:

       -V, --value=VALUE
	      The value	to store in the	cluster. If omitted, the value is read
	      from  standard  input.  This option is valid only	for the	create

       f, --flags=ITEMFLAGS
	      A	32 bit unsigned	integer	to be stored alongside the value. This
	      number  is  returned  when  the  item  is	retrieved again. Other
	      clients commonly use this	value to determine the	type  of  item
	      being stored.

       e, --expiry=EXPIRATION
	      The  number of time in seconds from now at which the item	should

       M, --mode=upsert|insert|replace
	      Specify the storage mode.	Mode can be one	of insert (store  item
	      if  it  does not yet exist), replace (only store item if key al-
	      ready exists), or	upsert (unconditionally	store item)

       p, --persist-to=NUMNODES
	      Wait until the item has been  persisted  to  at  least  NUMNODES
	      nodes'  disk.  If	 NUMNODES is 1 then wait until only the	master
	      node has persisted the item for this key.	You may	not specify  a
	      number greater than the number of	nodes actually in the cluster.

       r --replicate-to=NREPLICAS
	      Wait  until  the	item has been replicated to at least NREPLICAS
	      replica nodes. The bucket	must be	configured with	at  least  one
	      replica, and at least NREPLICAS replica nodes must be online.

       Retrieve	persistence and	replication information	for items.

       This command will print the status of each key to standard error.

       See the OPTIONS for accepted options

       These  commands increment or decrement a	counter	item in	the cluster. A
       counter is a value stored as an ASCII string which  is  readable	 as  a
       number, thus for	example	42.

       These  commands will by default refuse to operate on an item which does
       not exist in the	cluster.

       The incr	and decr command differ	with how they treat the	--delta	 argu-
       ment.  The  incr	 command will treat the	value as a positive offset and
       increment the current value by the amount specified, whereas  the  decr
       command	will  treat  the  value	as a negative offset and decrement the
       value by	the amount specified.

       In addition to OPTIONS, the following options are supported:

	      Set the initial value for	the item if it does not	exist  in  the
	      cluster. The value should	be an unsigned 64 bit integer. If this
	      option is	not specified and the item does	not exist, the	opera-
	      tion will	fail. If the item does exist, this option is ignored.

	      Set  the absolute	delta by which the value should	change.	If the
	      command is incr then the	value  will  be	 incremented  by  this
	      amount.  If  the	command	 is decr then the value	will be	decre-
	      mented by	this amount. The default value for this	option is 1.

       -e, --expiry=EXPIRATION
	      Set the expiration time for the key, in terms  of	 seconds  from

       Display mapping information for a key.

       This  command  diplays mapping information about	a key. The mapping in-
       formation indicates which vBucket the  key  is  mapped  to,  and	 which
       server is currently the master node for the given vBucket.

       See the OPTIONS for accepted options

       Lock an item in the cluster.

       This  will retrieve and lock an item in the cluster, making it inacces-
       sible for modification until it is unlocked (see	unlock).

       In addition to the common options (OPTIONS), this command  accepts  the
       following options:

       e, --expiry=LOCKTIME
	      Specify  the  amount of time the lock should be held for.	If not
	      specified, it will default to the	server side maximum of 15 sec-

       Unlock a	previously locked item.

       This  command  accepts two mandatory positional arguments which are the
       key and CAS value. The CAS value	should be specified  as	 printed  from
       the lock	command	(i.e. with the leading 0x hexadecimal prefix).

       See the OPTIONS for accepted options

       Remove an item from the cluster.

       This command will remove	an item	from the cluster. If the item does not
       exist, the operation will fail.

       See the OPTIONS for accepted options

       Retrieve	a list of cluster  statistics.	If  positional	arguments  are
       passed to this command, only the	statistics classified under those keys
       will be retrieved. See the server documentation for a full list of pos-
       sible statistics	categories.

       This  command will contact each server in the cluster and retrieve that
       node's own set of statistics.

       The statistics are printed to standard output in	 the  form  of	SERVER
       STATISTIC  VALUE	 where	SERVER	is the host:port representation	of the
       node from which has provided this statistic, STATISTIC is the  name  of
       the current statistical key, and	VALUE is the value for this statistic.

       See the OPTIONS for accepted options

       Display	information  about  the	 underlying version of libcouchbase to
       which the cbc binary is linked.

       Set the memcached logging versbosity on the cluster. This  affects  how
       the memcached processes write their logs. This command accepts a	single
       positional argument which is a string describing	the verbosity level to
       be set. The options are detail, debug info, and warning.

       Flush  a	 memcached  bucket.  This command takes	no arguments, and will
       fail if the bucket specified is not a memcached bucket.	You  may  also
       use  bucket-flush  to  flush any	bucket (including a couchbase bucket).
       The mcflush command may be quicker for memcached	buckets, though.

       Execute an HTTP request against the server's view (CAPI)	interface.

       The request may be one to create	a design document, view	a design docu-
       ment, or	query a	view.

       To  create  a design document, the definition of	the document (in JSON)
       should be piped to the command on standard input.

       This command accepts one	positional argument which is the  path	(rela-
       tive to the bucket) to execute. Thus to query the brewery_beers view in
       the beer	design document	within the beer-sample bucket  one  would  do:
       cbc  view  -U  couchbase://localhost/beer-sample	design/beer/view/brew-

       In addition to the OPTIONS specified above, the following  options  are

       -X, --method=GET|PUT|POST|DELETE
	      Specify the HTTP method to use for the specific request. The de-
	      fault method is GET to query a view. To delete an	 existing  de-
	      sign  document, specify DELETE, and to create a new design docu-
	      ment, specify PUT.

       Execute a N1QL Query. The cluster must have at least one	query node en-

       The query itself	is passed as a positional argument on the commandline.
       The query may contain named placeholders	(in  the  format  of  $param),
       whose  values  may be supplied later on using the --qarg='$param=value'

       It is recommended to place the statement	 in  single  quotes  to	 avoid
       shell expansion.

       In  addition  to	the OPTIONS specified above, the following options are

       -Q, --qopt=SETTING=VALUE
	      Specify additional options  controlling  the  execution  of  the
	      query. This can be used for example, to set the scan_consistency
	      of the query.

       -A, --qarg=PLACEHOLDER=VALUE
	      Supply values for	placeholders found in the  query  string.  The
	      placeholders must	evaluate to valid JSON values.

       Execute an administrative request against the management	REST API. Note
       that in order to	perform	an administrative API you will need to provide
       administrative  credentials  to	cbc admin. This	means the username and
       password	used to	log into the administration console.

       This command accepts a single positional	argument which is the REST API
       endpoint	(i.e. HTTP path) to execute.

       If  the request requires	a body,	it should be supplied via standard in-

       In addition to the OPTIONS specified above, the following  options  are

       -X, --method=GET|PUT|POST|DELETE
	      Specify the HTTP method to use for the specific request. The de-
	      fault method is GET.

       Create a	bucket in the cluster.

       This command will create	a bucket with the name specified as  the  lone
       positional argument on the command line.

       As this is an administrative command, the --username and	--password op-
       tions should be supplied	administrative credentials.

       In addition to the OPTIONS specified above, the following  options  are

	      Specify  the  type  of  bucket to	create.	A couchbase bucket has
	      persistence to  disk  and	 replication.  A  memached  bucket  is
	      in-memory	only and does not replicate.

	      Specify  the  maximum  amount of memory the bucket should	occupy
	      (per node) in megabytes. If not specified, the default is	512.

	      Specify the password to secure  this  bucket.  If	 passed,  this
	      password	will  be required by all clients attempting to connect
	      to the bucket. If	ommitted, this bucket may be accessible	to ev-
	      eryone for both read and write access.

	      Specify the amount of replicas the bucket	should have. This will
	      set the number of	nodes each item	will be	replicated to. If  not
	      specified	the default is 1.

       This  command will flush	the bucket with	the name specified as the lone
       positional argument on the command line.

       This command does not require administrative level credentials, however
       it does require that flush be enabled for the bucket.

       See the OPTIONS for accepted options

       This  command will parse	a connection string into its constituent parts
       and display them	on the screen. The command takes a  single  positional
       argument	which is the string to parse.

       The  following  shows how to connect to various types of	buckets. These
       examples	all show how to	retrieve the key key. See  OPERATION  EXAMPLES
       for more	information on specific	sub-commands.

       Run against a bucket (a_bucket) on a cluster on a remote	host:

	   cbc cat key -U couchbase://

       Connect	to an SSL cluster at The certificate for the clus-
       ter is stored locally at	/home/couchbase/couchbase_cert.pem:

	   cbc cat key -U couchbases://

       Connect to an SSL cluster at,	ignoring certificate verifica-
       tion. This is insecure but handy	for testing:

	   cbc cat key -U couchbases://

       Connect to a password protected bucket (protected) on a remote host:

	   cbc cat key -U couchbase://	-P-
	   Bucket password:

       Connect	to a password protected	bucket,	specifying the password	on the
       command line (INSECURE, but useful for testing dummy environments)

	   cbc cat key -U couchbase://	-P t0ps3cr3t

       Connect to a bucket running on a	cluster	with a custom REST API port

	   cbc cat key -U http://localhost:9000/default

       Connec to bucket	running	on a cluster with a custom memcached port

	   cbc cat key -U couchbase://localhost:12000/default

       Connect to a memcached ( cluster using the	binary
       protocol.  A  vanilla  memcached	cluster	is not the same	as a memcached
       bucket residing within a	couchbase cluster (use the normal couchbase://
       scheme for that):

	   cbc cat key -U memcached://host1,host2,host3,host4

       Connect to a cluster using the HTTP protocol for	bootstrap, and set the
       operation timeout to 5 seconds

	   cbc cat key -U couchbase://host/bucket -Dbootstrap_on=http -Doperation_timeout=5

       Store a file to the cluster:

	   $ cbc cp mystuff.txt
	   mystuff.txt	       Stored. CAS=0xe15dbe22efc1e00

       Retrieve	persistence/replication	information about an item  (note  that
       Status is a set of bits):

	   $ cbc observe mystuff.txt
	   mystuff		[Master] Status=0x80, CAS=0x0

       Display mapping information about keys:

	   $cbc	hash foo bar baz
	   foo:	[vBucket=115, Index=3] Server: cbnode3:11210, CouchAPI:	http://cbnode3:8092/default
	   bar:	[vBucket=767, Index=0] Server: cbnode1:11210, CouchAPI:	http://cbnode1:8092/default
	   baz:	[vBucket=36, Index=2] Server: cbnode2:11210, CouchAPI: http://cbnode2:8092/default

       Create a	bucket:

	   $ cbc bucket-create --bucket-type=memcached --ram-quota=100 --password=letmein -u Administrator -P 123456 mybucket
	   Requesting /pools/default/buckets
	     Cache-Control: no-cache
	     Content-Length: 0
	     Date: Sun,	22 Jun 2014 22:43:56 GMT
	     Location: /pools/default/buckets/mybucket
	     Pragma: no-cache
	     Server: Couchbase Server

       Flush a bucket:

	   $ cbc bucket-flush default
	   Requesting /pools/default/buckets/default/controller/doFlush

	     Cache-Control: no-cache
	     Content-Length: 0
	     Date: Sun,	22 Jun 2014 22:53:44 GMT
	     Pragma: no-cache
	     Server: Couchbase Server

       Delete a	bucket:

	   $ cbc bucket-delete mybucket	-P123456
	   Requesting /pools/default/buckets/mybucket
	     Cache-Control: no-cache
	     Content-Length: 0
	     Date: Sun,	22 Jun 2014 22:55:58 GMT
	     Pragma: no-cache
	     Server: Couchbase Server

       Use  cbc	stats to determine the minimum and maximum timeouts for	a lock

	   $ cbc stats | grep ep_getl
	   localhost:11210 ep_getl_default_timeout 15
	   localhost:11210 ep_getl_max_timeout 30

       Create a	design document:

	   $ echo '{"views":{"all":{"map":"function(doc,meta){emit(,null)}"}}}' | cbc view -X PUT _design/blog
	     Cache-Control: must-revalidate
	     Content-Length: 32
	     Content-Type: application/json
	     Date: Sun,	22 Jun 2014 23:03:40 GMT
	     Location: http://localhost:8092/default/_design/blog
	     Server: MochiWeb/1.0 (Any of you quaids got a smint?)

       Query a view:

	   $ cbc view _design/blog/_view/all?limit=5
	     Cache-Control: must-revalidate
	     Content-Type: application/json
	     Date: Sun,	22 Jun 2014 23:06:09 GMT
	     Server: MochiWeb/1.0 (Any of you quaids got a smint?)
	     Transfer-Encoding:	chunked

       Issue a N1QL query:

	   $ cbc n1ql 'SELECT *	FROM `travel-sample` WHERE type="airport" AND city=$city' -Qscan_consistency=request_plus -A'$city=\"Reno\"'

       cbc(1) and cbc-pillowfight(1) may also read options from	cbcrc(4).  The
       default	path  for cbcrc	is $HOME/.cbcrc, but may be overridden by set-
       ting the	CBC_CONFIG evironment variable to an alternate path.

       The options in this utility and their behavior are subject  to  change.
       This script should be used for experiemntation only and not inside pro-
       duction scripts.

       cbc-pillowfight(1), cbcrc(4)

       The cbc command first appeared in version 0.3.0 of the library. It  was
       significantly rewritten in version 2.4.0

				   July	2015				CBC(1)


Want to link to this manual page? Use this URL:

home | help