0
# Command Line Interface
1

2
Complete command-line tool for managing .env files with list, get, set, unset, and run commands supporting multiple output formats.
3

4
## Installation
5

6
```bash
7
pip install "python-dotenv[cli]"
8
```
9

10
## Global Options
11

12
All commands support these global options:
13

14
```bash { .api }
15
dotenv [OPTIONS] COMMAND [ARGS]...
16

17
Options:
18
  -f, --file PATH           Location of the .env file, defaults to .env file in current working directory
19
  -q, --quote [always|never|auto]  Whether to quote or not the variable values. Default mode is always
20
  -e, --export              Whether to write the dot file as an executable bash script
21
  --version                 Show the version and exit
22
  --help                    Show help message and exit
23
```
24

25
## Capabilities
26

27
### Listing Variables
28

29
Display all stored key/value pairs with support for multiple output formats.
30

31
```bash { .api }
32
dotenv list [OPTIONS]
33

34
Options:
35
  --format [simple|json|shell|export]  The format in which to display the list (default: simple)
36
```
37

38
Usage examples:
39

40
```bash
41
# List all variables in simple format
42
dotenv list
43

44
# List in JSON format
45
dotenv list --format=json
46

47
# List in shell format (with proper quoting)
48
dotenv list --format=shell
49

50
# List in export format (prefixed with 'export')
51
dotenv list --format=export
52

53
# List from custom file
54
dotenv -f /path/to/custom.env list
55
```
56

57
Output examples:
58

59
```bash
60
# Simple format
61
DATABASE_URL=postgresql://localhost/mydb
62
DEBUG=True
63
API_KEY=secret123
64

65
# JSON format
66
{
67
  "API_KEY": "secret123",
68
  "DATABASE_URL": "postgresql://localhost/mydb",
69
  "DEBUG": "True"
70
}
71

72
# Shell format (properly quoted)
73
DATABASE_URL='postgresql://localhost/mydb'
74
DEBUG=True
75
API_KEY=secret123
76

77
# Export format
78
export DATABASE_URL='postgresql://localhost/mydb'
79
export DEBUG=True
80
export API_KEY=secret123
81
```
82

83
### Getting Values
84

85
Retrieve the value for a specific key.
86

87
```bash { .api }
88
dotenv get KEY
89
```
90

91
Usage examples:
92

93
```bash
94
# Get a specific value
95
dotenv get DATABASE_URL
96

97
# Get from custom file
98
dotenv -f production.env get API_KEY
99

100
# Handle missing keys (exits with code 1)
101
dotenv get NONEXISTENT_KEY
102
echo $?  # Returns 1
103
```
104

105
### Setting Values
106

107
Store key/value pairs in the .env file.
108

109
```bash { .api }
110
dotenv set KEY VALUE
111
```
112

113
Usage examples:
114

115
```bash
116
# Set a basic key/value pair
117
dotenv set DATABASE_URL "postgresql://localhost/mydb"
118

119
# Set with different quote modes
120
dotenv -q never set SIMPLE_KEY simple_value
121
dotenv -q auto set SPACED_KEY "value with spaces"
122
dotenv -q always set QUOTED_KEY always_quoted
123

124
# Set with export prefix
125
dotenv -e set PATH_ADDITION "/usr/local/bin"
126

127
# Set in custom file
128
dotenv -f production.env set API_KEY "prod-secret-123"
129

130
# Set complex values
131
dotenv set JSON_CONFIG '{"host": "localhost", "port": 5432}'
132
dotenv set MULTILINE_VALUE "line1
133
line2
134
line3"
135
```
136

137
### Removing Values
138

139
Remove keys from the .env file.
140

141
```bash { .api }
142
dotenv unset KEY
143
```
144

145
Usage examples:
146

147
```bash
148
# Remove a key
149
dotenv unset OLD_CONFIG
150

151
# Remove from custom file
152
dotenv -f staging.env unset TEMP_KEY
153

154
# Handle missing keys (exits with code 1)
155
dotenv unset NONEXISTENT_KEY
156
echo $?  # Returns 1
157
```
158

159
### Running Commands
160

161
Execute commands with environment variables loaded from the .env file.
162

163
```bash { .api }
164
dotenv run [OPTIONS] COMMAND [ARGS]...
165

166
Options:
167
  --override/--no-override  Override variables from the environment file with those from the .env file (default: --override)
168
```
169

170
Usage examples:
171

172
```bash
173
# Run a Python script with .env variables
174
dotenv run python app.py
175

176
# Run with arguments
177
dotenv run python manage.py migrate
178

179
# Run from custom .env file
180
dotenv -f production.env run python app.py
181

182
# Don't override existing environment variables
183
dotenv run --no-override python app.py
184

185
# Run complex commands
186
dotenv run sh -c 'echo "Database: $DATABASE_URL"'
187

188
# Run commands that need specific environment
189
dotenv run pytest tests/
190
dotenv run npm start
191
dotenv run make build
192
```
193

194
The `run` command:
195
- Loads variables from the .env file
196
- Merges them with existing environment variables
197
- Executes the specified command with the combined environment
198
- **With `--override` (default)**: .env file variables take precedence over existing environment variables
199
- **With `--no-override`**: existing environment variables take precedence over .env file variables
200
- Variables that exist only in .env file or only in environment are always included
201

202
## File Selection
203

204
Use the `-f/--file` option to specify a custom .env file:
205

206
```bash
207
# Different .env files for different environments
208
dotenv -f .env.development list
209
dotenv -f .env.staging set API_URL "https://staging-api.example.com"
210
dotenv -f .env.production run python deploy.py
211

212
# Absolute paths
213
dotenv -f /etc/myapp/.env list
214

215
# Relative paths
216
dotenv -f ../shared.env get SHARED_KEY
217
```
218

219
## Quote Modes
220

221
Control how values are quoted using the `-q/--quote` option:
222

223
```bash
224
# Always quote (default)
225
dotenv -q always set KEY "value"  # KEY='value'
226

227
# Never quote
228
dotenv -q never set KEY value     # KEY=value
229

230
# Auto quote (quotes only when necessary)
231
dotenv -q auto set SIMPLE abc     # SIMPLE=abc
232
dotenv -q auto set COMPLEX "a b"  # COMPLEX='a b'
233
```
234

235
## Export Mode
236

237
Generate bash-compatible output using the `-e/--export` option:
238

239
```bash
240
# Set with export prefix
241
dotenv -e set PATH_VAR "/usr/local/bin"
242
# Results in: export PATH_VAR='/usr/local/bin'
243

244
# List with export format
245
dotenv -e list --format=export
246
# Shows all variables prefixed with 'export'
247

248
# Create sourceable .env file
249
dotenv -e -f bash-compatible.env set DATABASE_URL "postgresql://localhost/mydb"
250
# Now you can: source bash-compatible.env
251
```
252

253
## Exit Codes
254

255
The CLI tool uses standard exit codes:
256

257
- **0**: Success
258
- **1**: Command failed (key not found, file doesn't exist, etc.)
259
- **2**: File access error (permissions, file not readable, etc.)
260

261
## Examples
262

263
```bash
264
# Complete workflow example
265
cd myproject
266

267
# Initialize with some variables
268
dotenv set DATABASE_URL "postgresql://localhost/mydb"
269
dotenv set DEBUG "True"
270
dotenv set SECRET_KEY "dev-secret-key"
271

272
# List all variables
273
dotenv list
274

275
# Get specific value
276
echo "Database: $(dotenv get DATABASE_URL)"
277

278
# Run application with environment
279
dotenv run python app.py
280

281
# Export for bash sourcing
282
dotenv -e list --format=export > environment.sh
283
source environment.sh
284

285
# Clean up
286
dotenv unset SECRET_KEY
287
```