cbt CLI reference

Thecbt CLI is a command-line interface that lets you interact with Bigtable.See thecbt CLI overview to learn how to install thecbt CLI.Before you use thecbt CLI, you should be familiar with theBigtable overview.

The examples on this page usesample data similar to datathat you might store in Bigtable.

Usage:

cbt [-<option> <option-argument>] <command> <required-argument> [optional-argument]

The commands are:

addtocellAddavaluetoanaggregatecell(write)countCountrowsinatablecreateappprofileCreateappprofileforaninstancecreateclusterCreateaclusterintheconfiguredinstancecreatefamilyCreateacolumnfamilycreateinstanceCreateaninstancewithaninitialclustercreatetableCreateatabledeleteallrowsDeleteallrowsdeleteappprofileDeleteappprofileforaninstancedeleteclusterDeleteaclusterfromtheconfiguredinstancedeletecolumnDeleteallcellsinacolumndeletefamilyDeleteacolumnfamilydeleteinstanceDeleteaninstancedeleterowDeletearowdeletetableDeleteatabledocPrintgodoc-suitabledocumentationforcbtgetappprofileReadappprofileforaninstancehelpPrinthelptextimportBatchwritemanyrowsbasedontheinputfilelistappprofileListsappprofileforaninstancelistclustersListclustersinaninstancelistinstancesListinstancesinaprojectlookupReadfromasinglerowlsListtablesandcolumnfamiliesmddocPrintdocumentationforcbtinMarkdownformatnoticesDisplaylicenceinformationforanythird-partydependenciesreadReadrowssetSetvalueofacell(write)setgcpolicySetthegarbage-collectionpolicy(age,versions)foracolumnfamilyupdateappprofileUpdateappprofileforaninstanceupdateclusterUpdateaclusterintheconfiguredinstanceversionPrintthecurrentcbtversionwaitforreplicationBlockuntilallthecompletedwriteshavebeenreplicatedtoalltheclusters

The options are:

-project string    project ID. If unset uses gcloud configured project-instance string    Cloud Bigtable instance-creds string    Path to the credentials file. If set, uses the application credentials in this file-timeout string    Timeout (e.g. 10s, 100ms, 5m )

Example: cbt -instance=my-instance ls

Use "cbt help <command>" for more information about a command.

Preview features are not available to all Bigtable customers, theymight be changed in ways that are backward-incompatible, and we don't recommendthem for production use. They are not subject to any SLA or deprecation policy.

Syntax rules for the Bash shell apply to thecbt CLI. This means, for example,that you must put quotes around values that contain spaces or operators. It also means thatif a value is arbitrary bytes, you need to prefix it with a dollar sign and use single quotes.

Example:

cbt -project my-project -instance my-instance lookup my-table $'\224\257\312W\365:\205d\333\2471\315\'

For convenience, you can add values for the -project, -instance, -creds, -admin-endpoint and -data-endpointoptions to your ~/.cbtrc file in the following format:

project = my-project-123instance = my-instancecreds = path-to-account-key.jsonadmin-endpoint = hostname:portdata-endpoint = hostname:portauth-token = AJAvW039NO1nDcijk_J6_rFXG_...timeout = 30s

All values are optional and can be overridden at the command prompt.

Add a value to an aggregate cell (write)

cbtaddtocell<table-id><row-key>[app-profile=<app-profile-id>]<family>:<column>=<val>[@<timestamp>]...app-profile=<appprofileid>TheappprofileIDtousefortherequest<family>:<column>=<val>[@<timestamp>]mayberepeatedtosetmultiplecells.If<val>canbeparsedasanintegeritwillbeusedasone,otherwisethecallwillfail.timestampisanoptionalinteger.Ifthetimestampcannotbeparsed,'@<timestamp>'willbeinterpretedaspartofthevalue.Formostuses,atimestampisthenumberofmicrosecondssince1970-01-0100:00:00UTC.Examples:cbtaddtocelltable1user1sum_cf:col1=1@12345

Count rows in a table

cbt count <table-id> [prefix=<row-key-prefix>]

Create app profile for an instance

cbt createappprofile <instance-id> <app-profile-id> <description> (route-any | [ route-to=<cluster-id> : transactional-writes]) [-force]  force:  Optional flag to override any warnings causing the command to fail    Examples:      cbt createappprofile my-instance multi-cluster-app-profile-1 "Routes to nearest available cluster" route-any      cbt createappprofile my-instance single-cluster-app-profile-1 "Europe routing" route-to=my-instance-cluster-2

Create a cluster in the configured instance

cbtcreatecluster<cluster-id><zone><num-nodes><storage-type>cluster-idPermanent,uniqueIDfortheclusterintheinstancezoneThezoneinwhichtocreatetheclusternum-nodesThenumberofnodestocreatestorage-typeSSDorHDDExample:cbtcreateclustermy-instance-c2europe-west1-b3SSD

Create a column family

cbt createfamily <table-id> <family>    Example: cbt createfamily mobile-time-series stats_summary

Create an instance with an initial cluster

cbtcreateinstance<instance-id><display-name><cluster-id><zone><num-nodes><storage-type>instance-idPermanent,uniqueIDfortheinstancedisplay-nameDescriptionoftheinstancecluster-idPermanent,uniqueIDfortheclusterintheinstancezoneThezoneinwhichtocreatetheclusternum-nodesThenumberofnodestocreatestorage-typeSSDorHDDExample:cbtcreateinstancemy-instance"My instance"my-instance-c1us-central1-b3SSD

Create a table

cbtcreatetable<table-id>[families=<family>:<gcpolicy-expression>:<type-expression>,...][splits=<split-row-key-1>,<split-row-key-2>,...]familiesColumnfamiliesandtheirassociatedgarbagecollection(gc)policiesandtypes.Putgcpoliciesinquoteswhentheyincludeshelloperators &&and||.Forgcpolicy,see"setgcpolicy".Types"intsum","intmin","intmax",and"inthll"aresupported.splitsRowkey(s)wherethetableshouldinitiallybesplitExample:cbtcreatetablemobile-time-series"families=stats_summary:maxage=10d||maxversions=1,stats_detail:maxage=10d||maxversions=1"splits=tablet,phone

Delete all rows

cbt deleteallrows <table-id>    Example: cbt deleteallrows  mobile-time-series

Delete app profile for an instance

cbt deleteappprofile <instance-id> <profile-id>    Example: cbt deleteappprofile my-instance single-cluster

Delete a cluster from the configured instance

cbt deletecluster <cluster-id>    Example: cbt deletecluster my-instance-c2

Delete all cells in a column

cbt deletecolumn <table-id> <row-key> <family> <column> [app-profile=<app-profile-id>]  app-profile=<app-profile-id>        The app profile ID to use for the request    Example: cbt deletecolumn mobile-time-series phone#4c410523#20190501 stats_summary os_name

Delete a column family

cbt deletefamily <table-id> <family>    Example: cbt deletefamily mobile-time-series stats_summary

Delete an instance

cbt deleteinstance <instance-id>    Example: cbt deleteinstance my-instance

Delete a row

cbt deleterow <table-id> <row-key> [app-profile=<app-profile-id>]  app-profile=<app-profile-id>        The app profile ID to use for the request    Example: cbt deleterow mobile-time-series phone#4c410523#20190501

Delete a table

cbt deletetable <table-id>    Example: cbt deletetable mobile-time-series

Print godoc-suitable documentation for cbt

cbt doc

Read app profile for an instance

cbt getappprofile <instance-id> <profile-id>

Print help text

cbt help <command>    Example: cbt help createtable

Batch write many rows based on the input file

cbtimport<table-id> <input-file>[app-profile=<app-profile-id>][column-family=<family-name>][batch-size=<500>][workers=<1>][timestamp=<now|value-encoded>]app-profile=<app-profile-id>TheappprofileIDtousefortherequestcolumn-family=<family-name>Thecolumnfamilylabeltousebatch-size=<500>Themaxnumberofrowsperbatchwriterequestworkers=<1>Thenumberofworkerthreadstimestamp=<now|value-encoded>Whethertousecurrenttimeforallcellsorinterpretthetimestampfromcellvalue.Defaultsto'now'.ImportdatafromaCSVfileintoanexistingCloudBigtabletablethatalreadyhasthecolumnfamiliesyourdatarequires.TheCSVfilecansupporttworowsofheaders:-(Optional)columnfamilies-ColumnqualifiersBecausethefirstcolumnisreservedforrowkeys,leaveitemptyintheheaderrows.Inthecolumnfamilyheader,provideeachcolumnfamilyonce;itappliestothecolumnitisinandeverycolumntotherightuntilanothercolumnfamilyisfound.Eachrowaftertheheaderrowsshouldcontainarowkeyinthefirstcolumn,followedbythedatacellsfortherow.Seetheexample.Ifyoudon't provide a column family header row, the column header is your first row and your import command must include the `column-family` flag to specify an existing column family.Thetimestampforeachcellwilldefaulttocurrenttime(timestamp=now),toexplicitlysetthetimestampforcells,settimestamp=value-encodeduse <val>[@<timestamp>]asthevalueforthecell.Ifnotimestampisdelimitedforacell,currenttimewillbeused.Ifthetimestampcannotbeparsed,'@<timestamp>'willbeinterpretedaspartofthevalue.Formostuses,atimestampisthenumberofmicrosecondssince1970-01-0100:00:00UTC.,column-family-1,,column-family-2,//Optionalcolumnfamilyrow(1stcellempty),column-1,column-2,column-3,column-4//Columnqualifiersrow(1stcellempty)a,TRUE,,,FALSE//Rowkey'a'followedbydatab,,,TRUE,FALSE//Rowkey'b'followedbydatac,,TRUE,,TRUE//Rowkey'c'followedbydatad,TRUE@1577862000000000,,,FALSE//Rowkey'd'followedbydataExamples:cbtimportcsv-import-tabledata.csvcbtimportcsv-import-tabledata-no-families.csvapp-profile=batch-write-profilecolumn-family=my-familyworkers=5

Lists app profile for an instance

cbt listappprofile <instance-id>

List clusters in an instance

cbt listclusters

List instances in a project

cbt listinstances

Read from a single row

cbt lookup <table-id> <row-key> [columns=<family>:<qualifier>,...] [cells-per-column=<n>] [app-profile=<app profile id>]  row-key                             String or raw bytes. Raw bytes must be enclosed in single quotes and have a dollar-sign prefix  columns=<family>:<qualifier>,...    Read only these columns, comma-separated  cells-per-column=<n>                Read only this number of cells per column  app-profile=<app-profile-id>        The app profile ID to use for the request  format-file=<path-to-format-file>   The path to a format-configuration file to use for the request  keys-only=<true|false>              Whether to print only row keys  include-stats=full                  Include a summary of request stats at the end of the request Example: cbt lookup mobile-time-series phone#4c410523#20190501 columns=stats_summary:os_build,os_name cells-per-column=1 Example: cbt lookup mobile-time-series $'\x41\x42'

List tables and column families

cbt ls                List tablescbt ls <table-id>     List a table's column families and garbage collection policies    Example: cbt ls mobile-time-series

Print documentation for cbt in Markdown format

cbt mddoc

Display licence information for any third-party dependencies

cbt notices

Read rows

cbtread<table-id>[authorized-view=<authorized-view-id>][start=<row-key>][end=<row-key>][prefix=<row-key-prefix>][regex=<regex>][columns=<family>:<qualifier>,...][count=<n>][cells-per-column=<n>][app-profile=<app-profile-id>]authorized-view=<authorized-view-id>Readfromthespecifiedauthorizedviewofthetablestart=<row-key>Startreadingatthisrowend=<row-key>Stopreadingbeforethisrowprefix=<row-key-prefix>Readrowswiththisprefixregex=<regex>Readrowswithkeysmatchingthisregexreversed=<true|false>Readrowsinreverseordercolumns=<family>:<qualifier>,...Readonlythesecolumns,comma-separatedcount=<n>Readonlythismanyrowscells-per-column=<n>Readonlythismanycellspercolumnapp-profile=<app-profile-id>TheappprofileIDtousefortherequestformat-file=<path-to-format-file>Thepathtoaformat-configurationfiletousefortherequestkeys-only=<true|false>Whethertoprintonlyrowkeysinclude-stats=fullIncludeasummaryofrequeststatsattheendoftherequestExamples:(see'set'examplestocreatedatatoread)cbtreadmobile-time-seriesprefix=phonecolumns=stats_summary:os_build,os_namecount=10cbtreadmobile-time-seriesstart=phone#4c410523#20190501end=phone#4c410523#20190601cbtreadmobile-time-seriesregex="phone.*"cells-per-column=1cbtreadmobile-time-seriesstart=phone#4c410523#20190501end=phone#4c410523#20190601reversed=truecount=10Note:Usingaregexwithoutalsospecifyingstart,end,prefix,orcountresultsinafulltablescan,whichcanbeslow.

Set value of a cell (write)

cbtset<table-id><row-key>[authorized-view=<authorized-view-id>][app-profile=<app-profile-id>]<family>:<column>=<val>[@<timestamp>]...authorized-view=<authorized-view-id>Writetothespecifiedauthorizedviewofthetableapp-profile=<appprofileid>TheappprofileIDtousefortherequest<family>:<column>=<val>[@<timestamp>]mayberepeatedtosetmultiplecells.timestampisanoptionalinteger.Ifthetimestampcannotbeparsed,'@<timestamp>'willbeinterpretedaspartofthevalue.Formostuses,atimestampisthenumberofmicrosecondssince1970-01-0100:00:00UTC.Examples:cbtsetmobile-time-seriesphone#4c410523#20190501stats_summary:connected_cell=1@12345stats_summary:connected_cell=0@1570041766cbtsetmobile-time-seriesphone#4c410523#20190501stats_summary:os_build=PQ2A.190405.003stats_summary:os_name=android

Set the garbage-collection policy (age, versions) for a column family

cbtsetgcpolicy<table><family>((maxage=<d>|maxversions=<n>)[(and|or) (maxage=<d> | maxversions=<n>),...]|never)[force]force:Optionalflagtooverridewarningswhenrelaxingthegarbage-collectionpolicyonreplicatedclusters.Thismaycauseyourclusterstobetemporarilyinconsistent,makesureyouunderstandtheriskslistedathttps://cloud.google.com/bigtable/docs/garbage-collection#increasingmaxage=<d>Maximumtimestampagetopreserve.Acceptableunits:ms,s,m,h,dmaxversions=<n>MaximumnumberofversionstopreservePutgarbagecollectionpoliciesinquoteswhentheyincludeshelloperators &&and||.Examples:cbtsetgcpolicymobile-time-seriesstats_detailmaxage=10dcbtsetgcpolicymobile-time-seriesstats_summarymaxage=10dormaxversions=1force

Update app profile for an instance

cbt updateappprofile  <instance-id> <profile-id> <description>(route-any | [ route-to=<cluster-id> : transactional-writes]) [-force]  force:  Optional flag to override any warnings causing the command to fail    Example: cbt updateappprofile my-instance multi-cluster-app-profile-1 "Use this one." route-any

Update a cluster in the configured instance

cbt updatecluster <cluster-id> [num-nodes=<num-nodes>]  cluster-id    Permanent, unique ID for the cluster in the instance  num-nodes     The new number of nodes    Example: cbt updatecluster my-instance-c1 num-nodes=5

Print the current cbt version

cbt version

Block until all the completed writes have been replicated to all the clusters

cbt waitforreplication <table-id>

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.