Cloud Secrets Documentation

docs/cloud-tutorials/cicd.md

@@ -26,19 +26,6 @@ There's nothing special about the `-staging` and `-prod` suffixes—you can
 If you manually specify the application database name by setting `app_db_name` in `dbos_config.yaml`, you must ensure each environment uses a different value of `app_db_name`.
 :::
 
-## Secrets management
-To make secrets, such as API keys, available to your application running in DBOS Cloud, we recommend using environment variables.
-
-First, declare the environment variable in the `env` section of `dbos-config.yaml`:
-
-```yaml
-env:
-    API_KEY: ${API_KEY}
-```
-
-Then the value of `API_KEY` in your client environment will be submitted with your application and supplied to it as an environment variable on DBOS Cloud.
-Only environment variables declared in `dbos-config.yaml` are submitted and supplied like this.
-
 ## Authentication
 You should use [refresh tokens](account-management#authenticating-programatically) to programmatically authenticate your CI/CD user with DBOS Cloud.
 

docs/cloud-tutorials/cloud-cli.md

@@ -303,7 +303,7 @@ For each previous version of this application, emit:
 It retrieves an application's logs.
 
 **Parameters:**
-- `[application-name]`: The name of the application. By default we obtain the application name from package.json. This argument overrides the package name.
+- `[application-name]`: The name of the application.
 - `-l, --last <integer>`: How far back to query, in seconds from current time. By default, retrieve all data.
 ---
 
@@ -321,6 +321,43 @@ It is meant to be used with [`database restore`](#dbos-cloud-db-restore) during
 
 ---
 
+### `dbos-cloud app secrets create`
+
+**Description:**
+Create a new secret associated with an application, or update an existing secret.
+Secrets are made available to your application as environment variables.
+You must redeploy your application for a change in its secrets to take effect.
+
+**Parameters:**
+- `[application-name]`: The name of the application for which to create or update secrets.
+- `-s, --secretname <string>` The name of the secret to create or update.
+- `-v, --value`: The value of the secret.
+
+
+### `dbos-cloud app secrets import`
+
+**Description:**
+Import all environment variables defined in a `.env` file as secrets, updating them if they already exist.
+Allowed syntax for the `.env` file is described [here](https://dotenvx.com/docs/env-file), note that interpolation is supported but command substitution and encryption are currently not.
+Secrets are made available to your application as environment variables.
+You must redeploy your application for a change in its secrets to take effect.
+
+**Parameters:**
+- `[application-name]`: The name of the application for which to import secrets.
+- `-d, --dotenv <string>` Path to the `.env` file to import.
+
+---
+
+### `dbos-cloud app secrets list`
+
+**Description:**
+List all secrets associated with an application (only their names, not their values).
+
+**Parameters:**
+- `[application-name]`: The name of the application for which to list secrets.
+
+---
+
 ## Organization Management Commands
 
 ### `dbos-cloud org list`

docs/cloud-tutorials/secrets.md

@@ -0,0 +1,69 @@
+---
+sidebar_position: 9
+title: Secrets and Environment Variables
+---
+
+We recommend using secrets to manage your application environments in DBOS Cloud.
+Secrets are key-value pairs that are securely stored in DBOS Cloud and made available to your application as environment variables.
+
+## Managing and Using Secrets
+
+You can create or update a secret using the Cloud CLI:
+
+```
+dbos-cloud app secrets create -s <secret-name> -v <secret-value>
+```
+
+For example, to create a secret named `API_KEY` with value `abc123`, run:
+
+```
+dbos-cloud app secrets create -s API_KEY -v abc123
+```
+
+When you next redeploy your application, its environment will be updated to contain the `API_KEY` environment variable with value `abc123`.
+You can access it like any other environment variable:
+
+<Tabs groupId="language">
+<TabItem value="python" label="Python">
+
+```python
+key = os.environ['API_KEY'] # Value is abc123
+```
+</TabItem>
+
+<TabItem value="typescript" label="Typescript">
+
+```typescript
+const key = process.env.API_KEY; // Value is abc123
+```
+</TabItem>
+</Tabs>
+
+Additionally, you can manage your application's secrets from the secrets page of the [cloud console](https://console.dbos.dev).
+
+<img src={require('@site/static/img/secrets/secrets-page.png').default} alt="Secrets Page" width="1000" className="custom-img" />
+
+## Importing Secrets
+
+You can import the contents of a `.env` file as secrets.
+Allowed syntax for the `.env` file is described [here](https://dotenvx.com/docs/env-file). Note that interpolation is supported but command substitution and encryption are currently not.
+Import a `.env` file with the following command:
+
+```shell
+dbos-cloud app secrets import -d <path-to-dotenv-file>
+```
+
+For example:
+
+
+```shell
+dbos-cloud app secrets import -d .env
+```
+
+## Listing Secrets
+
+You can list the names of your application's secrets with:
+
+```
+dbos-cloud app secrets list
+```

docs/python/reference/cli.md

@@ -40,4 +40,10 @@ Initialize the local directory with a DBOS template application.
 - `--template, -t <str>`: Specify a template to use. Currently, we have a single "hello" template, which is used by default.
 - `--config, -c`: If this flag is set, only the `dbos-config.yaml` file is added from the template. Useful to add DBOS to an existing project.
 
+### dbos reset
 
+Reset your DBOS [system database](../../explanations/system-tables.md), deleting metadata about past workflows and steps.
+No application data is affected by this.
+
+**Parameters:**
+- `--yes, -y`: Skip confirmation prompt.