Document how to load secrets (#164)

Add 3 new guides:
- Read secrets references (/personal/secrets/read)
- Load secrets into environment variables (personal/secrets/exec)
- Load secrets into templated files (/personal/secrets/inject)

documentation/package.json

@@ -2,9 +2,9 @@
     "name": "@dashlane/cli-documentation",
     "packageManager": "[email protected]",
     "dependencies": {
-        "next": "^13.4.8",
-        "nextra": "^2.8.0",
-        "nextra-theme-docs": "^2.8.0",
+        "next": "^13.4.13",
+        "nextra": "^2.10.0",
+        "nextra-theme-docs": "^2.10.0",
         "react": "^18.2.0",
         "react-dom": "^18.2.0"
     }

documentation/pages/personal/_meta.json

@@ -2,5 +2,6 @@
     "index": "Get Started",
     "authentication": "Authentication",
     "devices": "Managing your Devices",
-    "vault": "Accessing your Vault"
+    "vault": "Accessing your Vault",
+    "secrets": "Load secrets"
 }

documentation/pages/personal/secrets/_meta.json

@@ -0,0 +1,5 @@
+{
+    "read": "Read secrets references",
+    "exec": "Load secrets into environment variables",
+    "inject": "Load secrets into templated files"
+}

documentation/pages/personal/secrets/exec.mdx

@@ -0,0 +1,43 @@
+import { Steps } from 'nextra/components';
+
+# Load secrets into environment variables
+
+The Dashlane CLI allows you to load secrets into environment variables. This is useful for example when you want to use secrets in your applications in development.
+
+By using secret references in your environment variables, you can load secrets from your Dashlane account into your environment variables and avoid having to store them in plain text in your code.
+
+<Steps>
+### Get your secret reference
+
+Follow the guide in [Read secrets references](/personal/secrets/read) to learn how to get your secret reference.
+
+It should look like this: `dl://<secret_identifier>/<field>?<transformer>`
+
+### Export environment variables
+
+You can now export your secret reference into an environment variable :
+
+```sh copy
+export GITLAB_TOKEN='dl://mygitlabtoken/password'
+```
+
+### Use your secret in your application
+
+In your code you can for instance read the variable from the env:
+
+```js filename="app.js"
+const token = process.env.GITLAB_TOKEN;
+
+console.log(token);
+```
+
+Finally, you can use the `dcli exec` command to run your application with the environment variables loaded from your Dashlane account.
+
+```sh copy
+dcli exec -- node app.js
+```
+
+The stdin and stdout of your application will be piped to the terminal.
+Every environment variable that starts with `dl://` will be replaced by the secret value from your Dashlane account.
+
+</Steps>

documentation/pages/personal/secrets/inject.mdx

@@ -0,0 +1,44 @@
+import { Steps, Callout } from 'nextra/components';
+
+# Load secrets into templated files
+
+Using Dashlane CLI you can inject secrets into templated files.
+This is useful for example to inject secrets into configuration files and avoid storing secrets in your repository.
+
+<Steps>
+### Get your secret reference
+
+Follow the guide in [Read secrets references](/personal/secrets/read) to learn how to get your secret reference.
+
+It should look like this: `dl://<secret_identifier>/<field>?<transformer>`
+
+### Use secret references in your config file
+
+In your template config file, use the secret reference as a placeholder for the value you want to inject.
+
+The secret reference must be enclosed in double curly braces `{{ }}`.
+
+For instance, let's create a template config file for a fictive API:
+
+```yaml filename="config.yaml.template"
+api:
+    url: https://api.example.com
+    port: 443
+    access_token: '{{ dl://<secret_identifier>/<field> }}'
+```
+
+### Inject secrets into your config file
+
+Use the `dcli inject` command to inject secrets into your config file.
+
+```sh filename="Inject secrets into config file" copy
+dcli inject --in config.yaml.template --out config.yaml
+```
+
+In output file, the secret reference is replaced by the plaintext secret value.
+
+<Callout type="error" emoji="️🚫">
+    Make sure to delete the resolved config file if you no longer need it.
+</Callout>
+
+</Steps>

documentation/pages/personal/secrets/read.mdx

@@ -0,0 +1,68 @@
+# Read secrets references
+
+A secret reference is an URI starting by `dl://` that points to a secret stored in your vault.
+
+You can use a secret reference to securely load a secret from your vault into environment variables, scripts or configuration files.
+
+## Structure of secret references
+
+The URI is composed of 4 parts:
+
+1.  The **scheme** `dl://`
+1.  The **identifier** of the secret (or its title)
+1.  (optionally) the **field** of the secret to load
+1.  (optionally) a **transformer** to apply to the secret
+
+```text
+dl://<secret_identifier>[/<field>][?<transformer>]
+```
+
+### Secret identifier
+
+The secret identifier is the unique identifier of the secret in your vault (it can be either a password or a secure note).
+You can get this identifier by displaying the full json of a secret with the command `dcli password <title> -o json`.
+
+```sh
+# You will find them in the "id" field of the json
+{
+  "creationDatetime": "1691073205",
+  "id": "{QD145B53-B987-4CFE-9408-F25803DC47A4}",
+  ...
+}
+```
+
+**Note:** Make sure to remove the `{}` around the identifier before using it in the path. In this example it is `QD145B53-B987-4CFE-9408-F25803DC47A4`.
+
+Alternatively, you can use the title of the secret instead of its identifier. In this case, the secret will be loaded by searching for its title in your vault.
+If multiple secrets have the same title, the first one will be loaded.
+
+### Field
+
+The field is the name of the field of the secret to load. If not specified, the whole secret will be loaded in a JSON format.
+
+### Transformer
+
+The transformer is a function that will be applied to the secret field before loading it. It can be used to format the secret in a specific way.
+
+Available transformers:
+
+-   `?otp` to generate a one-time password from a secret key
+-   `?json=<JSONPathQuery>` to extract a value from a JSON object
+    (please refer to [JSONPath documentation](https://github.com/JSONPath-Plus/JSONPath#syntax-through-examples) for more information)
+
+## Read a secret reference
+
+You can simply use the `dcli read <path>` command to read a secret reference.
+
+```sh
+# Read the whole secret
+dcli read dl://<secret_identifier>
+
+# Read a specific field of the secret
+dcli read dl://<secret_identifier>/<field>
+
+# Read a specific field of the secret and apply a transformer
+dcli read dl://<secret_identifier>/<field>?<transformer>
+```
+
+**Note:** Accessing a secret with the secret identifier is faster than using the title of the secret as it does not require to decrypt the whole vault.