Skip to content

Commit eecf995

Browse files
lukegalbraithrussellzimeg
lukegalbraithrussell
and
zimeg
authored
docs: updates environment variables page to be CLI-focused, not Deno-focused (#498)
* go * go * go * go * Apply suggestions from code review Co-authored-by: Eden Zimbelman <zim@o526.net> * go --------- Co-authored-by: Eden Zimbelman <zim@o526.net>
1 parent df07c75 commit eecf995

1 file changed

Lines changed: 23 additions & 171 deletions

File tree

‎docs/guides/using-environment-variables-with-the-slack-cli.md‎

Lines changed: 23 additions & 171 deletions
Original file line numberDiff line numberDiff line change
@@ -5,194 +5,46 @@ slug: /tools/slack-cli/guides/using-environment-variables-with-the-slack-cli
55

66
# Using environment variables with the Slack CLI
77

8-
Storing and using environment variables in an application allows for certain variables to be maintained outside of the code of the application. You can use environment variables from within Slack [functions](/tools/deno-slack-sdk/guides/creating-custom-functions), [triggers](/tools/deno-slack-sdk/guides/using-triggers), and [manifests](/tools/deno-slack-sdk/guides/using-the-app-manifest).
8+
You can store and use environment variables with your Slack app by using a collection of Slack CLI commands and features. You can even access some pre-set environment variables!
99

10-
## Using environment variables with a custom function {#custom-function}
10+
:::note[You may be looking for the [_Using environment variables with the Deno Slack SDK_](/tools/deno-slack-sdk/guides/using-environment-variables) guide.]
11+
:::
12+
13+
## Using the Slack CLI `env` commands
1114

12-
When accessing environment variables from within a [custom function](/tools/deno-slack-sdk/guides/creating-custom-functions), where you store them differs when the app is local versus deployed.
15+
There are three Slack CLI subcommands that can be used to modify environment variables which are saved to the project's `.env` file.
1316

14-
### Storing local environment variables {#local-env-vars}
17+
### `slack env set`
1518

16-
Local environment variables are stored in a `.env` file at the root of the project and made available for use in [custom functions](/tools/deno-slack-sdk/guides/creating-custom-functions) via the `env` [context property](/tools/deno-slack-sdk/guides/creating-custom-functions#context).
19+
Use this to set an environment variable for the project. You can set the environment variable within the command, or run `slack env set` alone to go through an interactive interface.
1720

18-
A local `.env` file might look like this:
19-
```env
20-
MY_ENV_VAR=asdf1234
2121
```
22-
23-
Note that changes to your `.env` file will be reflected when you restart your local development server.
24-
25-
While the `.env` file should **never** be committed to source control for security reasons, you can see a sample `.env` file we've included in the [Timesheet approval sample app](https://github.com/slack-samples/deno-timesheet-approval) and the [Incident management sample app](https://github.com/slack-samples/deno-incident-management).
26-
27-
### Storing deployed environment variables {#deployed-env-vars}
28-
29-
When your app is [deployed](/tools/deno-slack-sdk/guides/deploying-to-slack), it will no longer use the `.env` file. Instead, you will have to add the environment variables using the [`env set`](/tools/slack-cli/reference/commands/slack_env_set) command. Environment variables added with `env set` will be made available to your deployed app's [custom functions](/tools/deno-slack-sdk/guides/creating-custom-functions) just as they are locally; see examples in the next section.
30-
31-
For the above example, we could run the following command before deploying our app:
32-
33-
```zsh
34-
slack env set MY_ENV_VAR asdf1234
22+
slack env set MAGIC_PASSWORD abracadbra
3523
```
3624

37-
If your token contains non-alphanumeric characters, wrap it in quotes like this:
38-
39-
```zsh
40-
slack env set SLACK_API_URL "https://dev<yournumber>.slack.com/api/"
41-
```
42-
43-
Your environment variables are always encrypted before being stored on our servers and will be automatically decrypted when you use them&mdash;including when listing environment variables with `slack env list`.
44-
45-
### Access variables from within function {#access-function}
25+
### `slack env unset`
4626

47-
We can retrieve the `MY_ENV_VAR` environment variable from within a [custom Slack function](/tools/deno-slack-sdk/guides/creating-custom-functions) via the `env` [context property](/tools/deno-slack-sdk/guides/creating-custom-functions#context) like this:
27+
Use this to remove variables for the project. You can unset environment variables within the command, or run `slack env unset` alone to view all environment variables and select which one to unset.
4828

49-
```javascript
50-
// functions/my_function.ts
51-
52-
import { DefineFunction, SlackFunction } from "deno-slack-sdk/mod.ts";
53-
import { MyFunctionDefinition } from "functions/myfunction.ts"
54-
55-
56-
export default SlackFunction(MyFunctionDefinition, ({ env }) => {
57-
const myEnvVar = env["MY_ENV_VAR"];
58-
// ...
59-
return { outputs: {} };
60-
});
6129
```
62-
63-
Environment variables also play an important part in making calls to a third-party API. Learn more about how to do that in the [FAQ](https://docs.slack.dev/faq#third-party).
64-
65-
## Using environment variables with a trigger or manifest {#using-trigger-manifest}
66-
67-
Accessing environment variables from within a [trigger](/tools/deno-slack-sdk/guides/using-triggers) definition or when constructing the [manifest](/tools/deno-slack-sdk/guides/using-the-app-manifest) differs slightly from custom functions.
68-
69-
Whether your app is being run locally or already deployed, constructing these definitions happens entirely on your machine and so the environment variables stored on your machine are used.
70-
71-
### Storing environment variables {#trigger-manifest-env-vars}
72-
73-
Environment variables used in trigger or manifest definitions should be saved in the local `.env` file for your project [as shown above](#local-env-vars). The values from this file are collected and used when generating these definitions.
74-
75-
Regardless of whether you're working with a local or deployed app, the same values from this file will be used. Read on to learn how to access these stored variables in code.
76-
77-
### Accessing variables from a trigger or manifest {#accessing-trigger-manifest}
78-
79-
The Deno runtime provides a helpful `load` function to autoload environment variables as part of the `dotenv` module of the standard library. We'll leverage this to easily access our environment variables.
80-
81-
Including this module in code will automatically import local environment variables for immediate use! Start by adding [the latest version](https://deno.land/std/dotenv/mod.ts) of this module to your `import_map.json`:
82-
83-
```json title="test"
84-
{
85-
"imports": {
86-
"deno-slack-sdk/": "https://deno.land/x/deno_slack_sdk@a.b.c/",
87-
"deno-slack-api/": "https://deno.land/x/deno_slack_api@x.y.z/",
88-
"std/": "https://deno.land/std@0.202.0/"
89-
}
90-
}
91-
```
92-
93-
Then, you can import the module into any file that makes use of environment variables and start accessing the environment with [`Deno.env.get("VARIABLE_NAME")`](https://examples.deno.land/environment-variables) like so:
94-
95-
```javascript
96-
// manifest.ts
97-
import { Manifest } from "deno-slack-sdk/mod.ts";
98-
import ExampleWorkflow from "./workflows/example_workflow.ts";
99-
100-
import "std/dotenv/load.ts";
101-
102-
export default Manifest({
103-
name: "Chatbot4000",
104-
displayName: Deno.env.get("CHATBOT_DISPLAY_NAME"),
105-
description: "Workflows for communicating with an imagined chatbot",
106-
icon: "assets/icon.png",
107-
workflows: [ExampleWorkflow],
108-
outgoingDomains: [
109-
Deno.env.get("CHATBOT_API_URL")!,
110-
],
111-
botScopes: ["commands", "chat:write"],
112-
});
30+
slack env unset MAGIC_PASSWORD
11331
```
11432

115-
After including this new module, you may have to run [`deno cache manifest.ts`](https://docs.deno.com/runtime/manual/getting_started/command_line_interface#cache-and-compilation-flags) to refresh your local dependency cache.
116-
117-
Variable values such as these are commonly used to specify [outgoing domains](/tools/deno-slack-sdk/guides/using-the-app-manifest#manifest-properties) used by functions, channel IDs for [event triggers](/tools/deno-slack-sdk/guides/creating-event-triggers#event-object), or client IDs of an [external authentication](/tools/deno-slack-sdk/guides/integrating-with-services-requiring-external-authentication#define) provider. But, don't let that limit you — environment variables can be used in so many other places!
118-
119-
#### Requiring environment variables values {#required-manifest-variable-values}
120-
121-
Setting values for environment variables can sometimes be forgotten, which can cause problems at runtime. Catching errors for these missing values early is often better than waiting for that runtime problem.
122-
123-
Including a `!` with your call to `Deno.env.get()` will ensure this value is defined at the time of building a definition and will throw an error otherwise.
33+
### `slack env list`
12434

125-
The previous example uses this pattern to ensure an outgoing domain is always set:
35+
Use this to view the variables set for this project
12636

127-
```javascript
128-
outgoingDomains: [
129-
Deno.env.get("CHATBOT_API_URL")!,
130-
],
13137
```
132-
133-
With this addition, running `slack deploy` without defining a value for `CHATBOT_API_URL` in the `.env` file will throw an error to give you a chance to set it before actually deploying!
134-
135-
## Enabling debug mode {#debug}
136-
137-
The included environment variable `SLACK_DEBUG` can enable a basic debug mode. Set `SLACK_DEBUG` to `true` to have all function-related payloads logged.
138-
139-
For local apps, add the following to your `.env` file:
140-
141-
```
142-
SLACK_DEBUG=true
38+
slack env list
14339
```
14440

145-
For deployed apps, run the following command before deployment:
41+
## Using CLI-provided variables
14642

147-
```
148-
slack env set SLACK_DEBUG true
149-
```
43+
The Slack CLI provides an envelope of environment variables set automatically if these aren't available beforehand.
15044

151-
## Included local and deployed variables {#included}
152-
153-
Slack provides two environment variables by default, `SLACK_WORKSPACE` and `SLACK_ENV`. The workspace name is specified by `SLACK_WORKSPACE` and `SLACK_ENV` provides a distinction between the `local` and `deployed` app. Use these values if you want to have different values based on the workspace or environment that the app is installed in.
154-
155-
These variables are automatically included when generating the manifest or triggers only. For access from within a custom function, these variables can be set from the `.env` file or with the [`env set`](/tools/slack-cli/reference/commands/slack_env_set) command.
156-
157-
A custom `WorkspaceMapSchema` can be created and used with these variables to decide which values to use for certain instances of an app. This can be used as an alternative to a local `.env` file or in conjunction with it. The following snippet works well for inclusion in your app manifest, or for triggers (for example, to change event trigger channel IDs):
158-
159-
```javascript
160-
// Custom schemas can be defined for workspace values
161-
type WorkspaceSchema = { channel_id: string };
162-
type WorkspaceMapSchema = {
163-
[workspace: string]: {
164-
[environment: string]: WorkspaceSchema;
165-
};
166-
};
167-
168-
// Custom values can be set for each known workspace
169-
export const workspaceValues: WorkspaceMapSchema = {
170-
beagoodhost: {
171-
deployed: {
172-
channel_id: "C123ABC456",
173-
},
174-
local: {
175-
channel_id: "C123ABC456",
176-
},
177-
},
178-
sandbox: {
179-
deployed: {
180-
channel_id: "C222BBB222",
181-
},
182-
local: {
183-
channel_id: "C222BBB222",
184-
},
185-
},
186-
};
187-
188-
// Fallback options can also be defined
189-
export const defaultValues: WorkspaceSchema = {
190-
channel_id: "{{data.channel_id}}",
191-
};
192-
193-
// Included environment variables will determine which value is used
194-
const environment = Deno.env.get("SLACK_ENV") || "";
195-
const workspace = Deno.env.get("SLACK_WORKSPACE") || "";
196-
const { channel_id } = workspaceValues[workspace]?.[environment] ??
197-
defaultValues;
198-
```
45+
| Variable | Origin | Use |
46+
|----------|--------|-----|
47+
| `SLACK_APP_TOKEN` | Set after a successful app installation when using Socket Mode. | Authenticate with Slack API as the app. Required for Socket Mode connections and API calls.
48+
| `SLACK_BOT_TOKEN` | Set after a successful app installation that requested bot scopes. | Authenticate with Slack API as the bot user. Used for making API calls on behalf of the app.
49+
| `SLACK_APP_PATH` | Set when a custom start path is provided via `slack run` | Used to run from a non-root directory.
50+
| `SLACK_CLI_CUSTOM_FILE_PATH` | Set to the same value as `SLACK_APP_PATH` when a custom start path is provided via `slack run` | Used to run from a non-root directory.

0 commit comments

Comments
 (0)