Update docs

Author: chvck

Cargo.lock

@@ -59,7 +59,7 @@ url = "2.1"
 uuid = { version = "0.8", features = ["v4"] }
 
 [dev-dependencies]
-nu-test-support = { version = "0.61.0"}
+nu-test-support = { version = "0.62.0"}
 dunce = "1.0.1"
 itertools = "0.10.3"
 lazy_static = "1.4.0"

Cargo.toml

@@ -2,11 +2,12 @@
 
 https://cloud.couchbase.com/sign-up?ref=cbsh-web-capella[Couchbase Capella] is a Database as a Service offering from Couchbase which you can interact with from Couchbase Shell.
 
-=== `use`  and the Environment
+[#_cb_env_and_the_environment]
+=== `cb-env` and the Environment
 
-For general usage of the `use` command see <<_use_and_the_environment>>.
-When using <<_management_commands>> with Couchbase Capella and Couchbase Shell we need to be able to manage more active resources than the base `use` command gives us.
-You can use the `use --capella` command to see which cloud resources are current active:
+For general usage of the `cb-env` command see <<cbenv.adoc#_cb_env_and_the_environment>>.
+When using <<_management_commands>> with Couchbase Capella and Couchbase Shell we need to be able to manage more active resources than the base `cb-env` command gives us.
+You can use the `cb-env --capella` command to see which cloud resources are current active:
 
 ```
 > cb-env--capella
@@ -17,7 +18,7 @@ You can use the `use --capella` command to see which cloud resources are current
 ──────────────────────┴──────────────────
 ```
 
-The active resource can be changed with the `use` command:
+The active resource can be changed with the `cb-env` command:
 
 ```
 > cb-env -h
@@ -42,11 +43,12 @@ Document level commands like those under `doc`, `analytics`, `query`, and `searc
 
 You need to:
 
-    - https://docs.couchbase.com/cloud/clusters/create-cluster.html[create a cluster] in your Couchbase Capella account
-    - ensure that your https://docs.couchbase.com/cloud/security/allow-ip-address.html[IP address is whitelisted]
-    - ensure that you have a https://docs.couchbase.com/cloud/security/manage-database-users.html[database user]
-    - Populate the relevant cluster section in the `config` file with the public address and database user credentials.
+- https://docs.couchbase.com/cloud/clusters/create-cluster.html[create a cluster] in your Couchbase Capella account
+- ensure that your https://docs.couchbase.com/cloud/security/allow-ip-address.html[IP address is whitelisted]
+- ensure that you have a https://docs.couchbase.com/cloud/security/manage-database-users.html[database user]
+- Populate the relevant cluster section in the `config` file with the public address and database user credentials.
 
+[#_management_commands]
 === Management Commands
 
 Management commands (such as `cluster` and `bucket` management) require a specific section to be added to the `config` file as well as an extra entry in the relevant cluster section.

docs/cloud.adoc docs/capella.adocdocs/cloud.adoc renamed to docs/capella.adoc

@@ -1,13 +1,14 @@
-== `use` and the Environment
+[#_cb_env_and_the_environment]
+== `cb-env` and the Environment
 
-While multiple clusters can be connected at the same time, there is only ever one cluster (at most) active.
+Whilst multiple clusters can be registered at the same time, there is only ever one cluster (at most) active.
 The same is true for buckets, scopes, and collections.
 When a resource is active then it used as the default to run commands against (this can be overridden on a per command basis).
 
-You can run the `use` command, which will tell you which resources are currently active (you are also able to tell from the prompt):
+You can run the `cb-env` command, which will tell you which resources are currently active (you are also able to tell from the prompt):
 
 ```
-> use
+> cb-env
 ────────────┬───────────────
  username   │ Susan
  cluster    │ dev.local
@@ -25,8 +26,8 @@ If you were to now run a command then we would be running it:
 * Against the "inventory" scope
 * Against the "hotel" collection
 
-You can also change the active resources with the `use` command.
-(Note there are extra resources listed here, see <<cloud.adoc#_use_and_the_environment>> for more information on these)
+You can also change the active resources with the `cb-env` command.
+(Note there are extra resources listed here, see <<capella.adoc#_cb_env_and_the_environment>> for more information on these)
 
 ```
 > cb-env -h
@@ -55,7 +56,7 @@ For example if you change the active bucket:
 ```
 
 ```
-> use
+> cb-env
 ────────────┬─────────────
  username   │ Susan
  cluster    │ dev.local
@@ -65,9 +66,9 @@ For example if you change the active bucket:
 ────────────┴─────────────
 ```
 
-Both the output of `use` and the prompt will reflect the changes.
+Both the output of `cb-env` and the prompt will reflect the changes.
 
-=== `Use`ing different execution environments
+=== Per command execution environments
 
 On many commands you will notice a set of flags which allow you to override the active execution environment.
 Different commands support different flags, depending on the command you can expect to see any of:

docs/use.adoc docs/cbenv.adocdocs/use.adoc renamed to docs/cbenv.adoc

@@ -4,7 +4,7 @@ The following sections discuss the individual couchbase specific commands in gre
 
 === Working with `clusters`
 
-The `clusters managed` command lists all the clusters you specified in your configuration and the shell might be connected to.
+The `clusters managed` command lists all the clusters you have registered with the shell.
 
 ```
 > clusters managed

docs/commands.adoc

@@ -14,7 +14,7 @@ include::quickstart.adoc[]
 
 include::intro.adoc[]
 
-include::use.adoc[]
+include::cbenv.adoc[]
 
 include::commands.adoc[]
 

docs/index.adoc

@@ -138,6 +138,13 @@ Couchbase Shell uses a custom, two line prompt to show you exactly in what envir
 
 It tells you that your user is `Administrator`, the current active cluster identifier is `local` and the active bucket is `travel-sample`.
 
+If you have an active scope or collection set then the prompt will also update to reflect that:
+
+```
+👤 Administrator 🏠 dev.local in 🗄 travel-sample.myscope.mycollection
+>
+```
+
 In the second line, your actual user prompt starts.
 
 === Pivot mode

docs/intro.adoc

@@ -2,18 +2,18 @@
 
 === Installation
 
-The current latest version is *1.0.0-beta.3*.
+The current latest version is *1.0.0-beta.4*.
 
 There are a couple ways you can get access to `cbsh`, the easiest one is to download our pre-built binaries for your platform of choice:
 
- - Linux: https://github.com/couchbaselabs/couchbase-shell/releases/download/v1.0.0-beta.3/cbsh-1.0.0-beta.3-linux.tar.gz[cbsh-1.0.0-beta.3-linux.tar.gz]
- - macOS: https://github.com/couchbaselabs/couchbase-shell/releases/download/v1.0.0-beta.3/cbsh-1.0.0-beta.3-mac.zip[cbsh-1.0.0-beta.3-mac.zip]
- - Windows: https://github.com/couchbaselabs/couchbase-shell/releases/download/v1.0.0-beta.3/cbsh-1.0.0-beta.3-windows.zip[cbsh-1.0.0-beta.3-windows.zip]
+ - Linux: https://github.com/couchbaselabs/couchbase-shell/releases/download/v1.0.0-beta.4/cbsh-1.0.0-beta.4-linux.tar.gz[cbsh-1.0.0-beta.4-linux.tar.gz]
+ - macOS: https://github.com/couchbaselabs/couchbase-shell/releases/download/v1.0.0-beta.4/cbsh-1.0.0-beta.4-mac.zip[cbsh-1.0.0-beta.4-mac.zip]
+ - Windows: https://github.com/couchbaselabs/couchbase-shell/releases/download/v1.0.0-beta.4/cbsh-1.0.0-beta.4-windows.zip[cbsh-1.0.0-beta.4-windows.zip]
 
 Once you've downloaded the `zip` file, extract it and switch into the just created directory. The following example shows it for mac, but it works very similar if you are on linux (just align the commands with the file you just downloaded):
 
 ```
-$ unzip cbsh-1.0.0-beta.3-mac.zip
+$ unzip cbsh-1.0.0-beta.4-mac.zip
 $ ls
 cbsh  examples  LICENSE  README.md
 ```
@@ -22,7 +22,7 @@ You can now run the `cbsh` binary:
 
 ```
 ❯ ./cbsh --version
-The Couchbase Shell 1.0.0-beta.3
+The Couchbase Shell 1.0.0-beta.4
 ```
 
 TIP: If you are running a recent macOS release (i.e. 10.15.x), you'll likely see an error similar to *"cbsh" was blocked from use because it is not from an identified developer*. This is because our binaries are not yet signed. To run it nonetheless you need to navigate to `System Preferences -> Security & Privacy` and click `Allow Anyway`. Next time you run the binary you'll get another prompt but then it should run fine. 
@@ -91,6 +91,6 @@ password = "password"
 # password = "pass"
 ```
 
-This will connect to two clusters, one called `local` and one called `remote` (commented out). The file format is `toml` in case you wonder. Now when you start the shell, it will connect to `local` automatically and you are all set. 
+This will register two clusters, one called `local` and one called `remote` (commented out). The file format is `toml` in case you wonder. Now when you start the shell, it will connect to `local` automatically and you are all set.
 
 Please check out the reference section on additional parameters you can set as well as how to move the credentials to a separate `credentials` file in case you want to share your config with other people and they do not use the same credentials.

docs/quickstart.adoc

@@ -64,7 +64,7 @@ Multiple Documents
    │      │         │ Rgnl        │          │ States  │     │      │ ago
 ───┴──────┴─────────┴─────────────┴──────────┴─────────┴─────┴──────┴──────────────
 
-> ls airports/ | open  $it.name | each { wrap content | insert id {echo $it.content.airportname} } | doc upsert
+> ls airports/ | open  $it.name | each { |it| wrap content | insert id {echo $it.content.airportname} } | doc upsert
 ───┬───────────┬─────────┬────────
  # │ processed │ success │ failed
 ───┼───────────┼─────────┼────────
@@ -80,7 +80,7 @@ Single Document
 id,cas,type,airportname,city,country,faa,icao,tz
 3719,1600344369374167040,airport,Columbia Rgnl,Columbia,United States,COU,KCOU,America/Chicago
 
-> open mydoc.csv | each { wrap content | insert id {echo $it.content.airportname} } | doc upsert
+> open mydoc.csv | each { |it| wrap content | insert id {echo $it.content.airportname} } | doc upsert
 ───┬───────────┬─────────┬────────
  # │ processed │ success │ failed
 ───┼───────────┼─────────┼────────
@@ -98,7 +98,7 @@ Les Loges,Nangis,France,,LFAI,1256,airport,Europe/Paris
 Couterne,Bagnole-de-l'orne,France,,LFAO,1257,airport,Europe/Paris
 Bray,Albert,France,,LFAQ,1258,airport,Europe/Paris
 
-> open airports.csv | each { wrap content | insert id {echo $it.content.airportname}  } | doc upsert
+> open airports.csv | each { |it| wrap content | insert id {echo $it.content.airportname}  } | doc upsert
 ───┬───────────┬─────────┬────────
  # │ processed │ success │ failed
 ───┼───────────┼─────────┼────────
@@ -170,7 +170,7 @@ Bray,Albert,France,,LFAQ,1258,Europe/Paris
 
 We can also add a column based on data from other columns, for instance adding a `type` column which is set to the relevant country:
 ```
-open ~/demo/airports.csv | each { insert type $it.city }
+open ~/demo/airports.csv | each { |it| insert type $it.city }
 ───┬────────────┬────────────┬─────────┬─────┬──────┬──────┬────────────┬────────────
  # │ airportnam │    city    │ country │ faa │ icao │  id  │     tz     │    type
    │     e      │            │         │     │      │      │            │

docs/recipes/importing-data.adoc

@@ -9,11 +9,15 @@ A good example here is migrating from an on-premise cluster to a Capella cluster
 
 To migrate scopes, except the `_default` scope:
 
-`scopes --clusters "On-Prem-Cluster" --bucket travel-sample | select scope | where scope != "_default" | each { scopes create $it.scope --clusters "Capella-Cluster" }`
+```
+scopes --clusters "On-Prem-Cluster" --bucket travel-sample | select scope | where scope != "_default" | each { |it| scopes create $it.scope --clusters "Capella-Cluster" }
+```
 
 To migrate all collections, except the `_default` collection:
 
-`collections --clusters "On-Prem-Cluster" --bucket "travel-sample" | select scope collection | where $it.scope != "_default" | where $it.collection != "_default" | each { collections create $it.collection --clusters "Capella-Cluster" --bucket "travel-sample-import" --scope $it.scope`
+```
+collections --clusters "On-Prem-Cluster" --bucket "travel-sample" | select scope collection | where $it.scope != "_default" | where $it.collection != "_default" | each { |it| collections create $it.collection --clusters "Capella-Cluster" --bucket "travel-sample-import" --scope $it.scope
+```
 
 These examples can easily be extended to filter out any other scopes and collections you do not want to migrate.
 For example to filter more scopes you would just add more `where` clauses: `... | where scope != "_default" | where scope != "inventory" | ...`
@@ -25,4 +29,6 @@ A good example here is migrating from an on-premise cluster to a Capella cluster
 
 To migrate all of your index definitions:
 
-`query indexes --definitions --clusters "On-Prem-Cluster" | get definition | each { query $it --clusters "Capella-Cluster" }`
+```
+query indexes --definitions --clusters "On-Prem-Cluster" | get definition | each { |it| query $it --clusters "Capella-Cluster" }
+```