Couchbase Shell (cbsh) is a modern, productive and fun shell for Couchbase Server and Cloud.
Note that while the project is maintained by Couchbase, it is not covered under the EE support contract. We are providing community support through this bug tracker.
The documentation is available here.
First, download the archive for your operating system.
- Linux: cbsh-x86_64-unknown-linux-gnu.tar.gz
- macOS: cbsh-x86_64-apple-darwin.zip
- Linux aarch64 cbsh-aarch64-unknown-linux-gnu.tar.gz
- macOS aarch64: cbsh-aarch64-apple-darwin.zip
- Windows: cbsh-x86_64-pc-windows-msvc.zip
You do not need any extra dependencies to run cbsh, it comes "batteries included".
macOS Users: You will need to grant the binary permissions through Security & Privacy settings the first time you run it.
After extracting the archive, run the cbsh binary in your terminal.
❯ ./cbsh --version
The Couchbase Shell 1.0.0
Once the binary is available, you can connect to a cluster on the fly and run a simple command to list the (user-visible) buckets.
❯ ./cbsh --connstr 127.0.0.1 -u username -p
Password:
👤 username 🏠 default in 🗄 <not set>
> buckets
───┬─────────┬───────────────┬───────────┬──────────┬──────────────────────┬───────────┬───────────────┬────────┬───────
# │ cluster │ name │ type │ replicas │ min_durability_level │ ram_quota │ flush_enabled │ status │ cloud
───┼─────────┼───────────────┼───────────┼──────────┼──────────────────────┼───────────┼───────────────┼────────┼───────
0 │ default │ beer-sample │ couchbase │ 1 │ none │ 209.7 MB │ false │ │ false
1 │ default │ default │ couchbase │ 1 │ none │ 104.9 MB │ true │ │ false
2 │ default │ targetBucket │ couchbase │ 0 │ none │ 104.9 MB │ true │ │ false
3 │ default │ travel-sample │ couchbase │ 1 │ none │ 209.7 MB │ false │ │ false
───┴─────────┴───────────────┴───────────┴──────────┴──────────────────────┴───────────┴───────────────┴────────┴───────
While passing in command-line arguments is fine if you want to connect quickly, using the dotfile ~/.cbsh/config for configuration is much more convenient. Here is a simple config which connects to a cluster running on localhost:
version = 1
[[cluster]]
identifier = "my-local-cb-node"
hostnames = ["127.0.0.1"]
default-bucket = "travel-sample"
username = "Administrator"
password = "password"After the config is in place, you can run ./cbsh without any arguments and it will connect to that cluster after start automatically.
The downloaded archive contains an example directory which also contains sample configuration files for more information. Also, please see the docs for full guidance, including information about how to work with multiple clusters at the same time.
Contributions and suggestions are always welcome. If you have suggestions/bugs feel free to file an issue.
Looking for some issues to tackle yourself? Check the good first issue label for some more straightforward ones, or pick any that are of interest.
If the issue is unclear or vague ask any questions in the comments, and we'll happily elaborate.
Before your PR can be merged we require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. This can be signed electronically here: https://review.couchbase.org/settings/#Agreements. Please use the same e-mail that is linked to your Github.
On top of nushell built-in commands, the following couchbase commands are available:
analytics <statement>- Perform an analytics queryanalytics dataverses- List all dataversesanalytics datasets- List all datasetsanalytics indexes- List all analytics indexesanalytics links- List all analytics linksanalytics buckets- List all analytics bucketsanalytics pending-mutations- List pending mutationsbuckets- Fetches buckets through the HTTP APIbuckets config- Shows the bucket config (low level)buckets create- Creates a bucketbuckets drop- Drops buckets through the HTTP APIbuckets flush- Flushes buckets through the HTTP APIbuckets get- Fetches a bucket through the HTTP APIbuckets load-sample- Load a sample bucketbuckets update- Updates a bucketcb-env- lists the currently active bucket, collection, etc.cb-env bucket- Sets the active bucket based on its namecb-env capella-organization- Sets the active Capella organization based on its identifiercb-env cloud- Sets the active cloud based on its identifiercb-env cluster- Sets the active cluster based on its identifiercb-env collection- Sets the active collection based on its namecb-env managed- Lists all clusters currently managed by couchbase shellcb-env project- Sets the active cloud project based on its namecb-env scope- Sets the active scope based on its namecb-env timeouts- Sets the default timeoutsclouds- Lists all clusters on the active Capella organizationclusters- Lists all clusters on the active Capella organizationclusters create- Creates a new cluster against the active Capella organizationclusters drop- Deletes a cluster from the active Capella organizationclusters get- Gets a cluster from the active Capella organizationclusters health- Performs health checks on the target cluster(s)clusters register- Registers a cluster for use with the shellclusters unregister- Registers a cluster for use with the shellcollections- Fetches collections through the HTTP APIcollections create- Creates collections through the HTTP APIcollections drop- Removes a collectiondoc get- Perform a KV get operationdoc insert- Perform a KV insert operationdoc remove- Removes a KV documentdoc replace- Perform a KV replace operationdoc upsert- Perform a KV upsert operationfake- Generate fake/mock datahelp- Display help information about commandsnodes- List all nodes in the active clusterping- Ping available services in the clusterprojects- List all projects (cloud)projects create- Create a new project (cloud)projects drop- Remove a project (cloud)query <statement>- Perform a N1QL queryquery indexes- list query indexesquery advise- Ask the query advisoruse- Change the active bucket or cluster on the flyscopes- Fetches scopes through the HTTP APIscopes create- Creates scopes through the HTTP APIscopes drop- Removes a scopesearch- Runs a query against a search indextransations list-atrs- List all active transaction records (requires an index - create index id3 ontravel-sample(meta().id, meta().xattrs.attempts))tutorial- Runs you through a tutorial of both nushell and cbshellusers- List all usersusers roles- List roles available on the clusterusers get- Show a specific userusers upsert- Create a new user or replace oneversion- Shows the version of the shellwhoami- Shows roles and domain for the connected user
If you want to build from source, make sure you have a modern rust version and cargo installed (ideally through the rustup toolchain).
After that, you can build and/or run through cargo build / cargo run. By default it will build in debug mode, so if you want to build a binary and test the performance, make sure to include --release.
If you just want to use it and don't want to bother compiling all the time, you can use cargo install --path . to install it into your cargo bin path (run from the checked out source directory).
❯ cargo install --path .
Installing couchbase-shell v1.0.0 (/Users/michaelnitschinger/couchbase/code/rust/couchbase-shell)
Updating crates.io index
Downloaded plist v1.2.1
Downloaded onig v6.3.0
Downloaded string_cache v0.8.2
Downloaded num-bigint v0.4.2
...
Grab a quick coffee or tea since this will take some time to compile.
Couchbase Shell is licensed under the Apache 2.0 License.
Couchbase Shell is made possible through open source components as listed with their licenses in NOTICES.
Usage of Couchbase Shell is subject to the Couchbase Inc. License Agreement