0
# CLI Commands
1
2
Command-line interface for starting and configuring the dagster webserver. Provides both production-ready server functionality and debugging capabilities for development and troubleshooting.
3
4
## Capabilities
5
6
### Main Webserver Command
7
8
Primary command for starting the dagster webserver with comprehensive configuration options for production and development environments.
9
10
```python { .api }
11
@click.command(name="dagster-webserver")
12
@click.option("--host", "-h", type=click.STRING, default="127.0.0.1", help="Host to run server on")
13
@click.option("--port", "-p", type=click.INT, default=None, help="Port to run server on")
14
@click.option("--path-prefix", "-l", type=click.STRING, default="", help="Path prefix where server will be hosted")
15
@click.option("--db-statement-timeout", type=click.INT, default=15000, help="Database statement timeout in ms")
16
@click.option("--db-pool-recycle", type=click.INT, default=3600, help="Max age of connection before recycling")
17
@click.option("--db-pool-max-overflow", type=click.INT, default=20, help="Max overflow size of sqlalchemy pool")
18
@click.option("--read-only", is_flag=True, help="Start server in read-only mode")
19
@click.option("--suppress-warnings", is_flag=True, help="Filter all warnings when hosting server")
20
@click.option("--uvicorn-log-level", default="warning", type=click.Choice(["critical", "error", "warning", "info", "debug", "trace"]))
21
@click.option("--dagster-log-level", default="info", type=click.Choice(["critical", "error", "warning", "info", "debug"]))
22
@click.option("--log-format", default="colored", type=click.Choice(["colored", "json", "rich"]))
23
@click.option("--code-server-log-level", default="info", type=click.Choice(["critical", "error", "warning", "info", "debug"]))
24
@click.option("--live-data-poll-rate", type=click.INT, default=2000, help="Rate at which UI polls for asset data in ms")
25
@click.option("--instance-ref", type=click.STRING, help="Internal instance reference", hidden=True)
26
@click.option("--shutdown-pipe", type=click.INT, help="Internal shutdown pipe", hidden=True)
27
@click.option("--version", is_flag=True, help="Show version information")
28
@workspace_options
29
def dagster_webserver(
30
host: str,
31
port: int,
32
path_prefix: str,
33
db_statement_timeout: int,
34
db_pool_recycle: int,
35
db_pool_max_overflow: int,
36
read_only: bool,
37
suppress_warnings: bool,
38
uvicorn_log_level: str,
39
dagster_log_level: str,
40
log_format: str,
41
code_server_log_level: str,
42
live_data_poll_rate: int,
43
instance_ref: Optional[str],
44
shutdown_pipe: Optional[int],
45
**other_opts: object
46
): ...
47
```
48
49
**Usage Examples:**
50
51
```bash
52
# Basic usage (requires workspace.yaml in current directory)
53
dagster-webserver
54
55
# Specify workspace file
56
dagster-webserver -w path/to/workspace.yaml
57
58
# Custom host and port
59
dagster-webserver --host 0.0.0.0 --port 8080
60
61
# With path prefix for reverse proxy setup
62
dagster-webserver --path-prefix /dagster-ui
63
64
# Read-only mode for production monitoring
65
dagster-webserver --read-only --host 0.0.0.0 --port 3000
66
67
# Development with debug logging
68
dagster-webserver --dagster-log-level debug --uvicorn-log-level info
69
70
# With custom database settings
71
dagster-webserver --db-statement-timeout 30000 --db-pool-recycle 7200
72
```
73
74
### Debug Webserver Command
75
76
Specialized command for loading webserver with ephemeral instance from debug export files, enabling detailed troubleshooting and development workflows.
77
78
```python { .api }
79
@click.command(name="debug")
80
@click.argument("input_files", nargs=-1, type=click.Path(exists=True))
81
@click.option("--port", "-p", type=click.INT, default=3000, help="Port to run server on")
82
def webserver_debug_command(input_files, port): ...
83
```
84
85
**Usage Examples:**
86
87
```bash
88
# Load single debug file
89
dagster-webserver-debug /path/to/debug_export.gz
90
91
# Load multiple debug files
92
dagster-webserver-debug debug1.gz debug2.gz debug3.gz
93
94
# Custom port
95
dagster-webserver-debug --port 8080 /path/to/debug_export.gz
96
```
97
98
### Programmatic CLI Access
99
100
Functions for accessing CLI functionality programmatically or embedding in other applications.
101
102
```python { .api }
103
def create_dagster_webserver_cli() -> click.Command:
104
"""
105
Create the Click command object for dagster-webserver CLI.
106
Useful for embedding the webserver CLI in other applications.
107
108
Returns:
109
click.Command: The CLI command object with all options and functionality
110
"""
111
112
def main():
113
"""
114
Main entry point for dagster-webserver CLI.
115
Handles backward compatibility with dagit command.
116
"""
117
118
def host_dagster_ui_with_workspace_process_context(
119
workspace_process_context: IWorkspaceProcessContext,
120
host: Optional[str],
121
port: Optional[int],
122
path_prefix: str,
123
log_level: str,
124
live_data_poll_rate: Optional[int] = None
125
):
126
"""
127
Host the Dagster UI with a given workspace process context.
128
129
Args:
130
workspace_process_context: The workspace context to use
131
host: Host to bind server to (defaults to 127.0.0.1)
132
port: Port to bind server to (auto-selected if None)
133
path_prefix: URL path prefix for hosting
134
log_level: Uvicorn log level
135
live_data_poll_rate: UI polling rate in milliseconds
136
"""
137
```
138
139
**Usage Example for CLI Factory:**
140
141
```python
142
from dagster_webserver.cli import create_dagster_webserver_cli
143
import click
144
145
# Get the webserver CLI command
146
webserver_cmd = create_dagster_webserver_cli()
147
148
# Embed in a larger CLI application
149
@click.group()
150
def main_cli():
151
"""My application with embedded Dagster webserver."""
152
pass
153
154
# Add webserver as a subcommand
155
main_cli.add_command(webserver_cmd, name="webserver")
156
157
# Usage: python my_app.py webserver --host 0.0.0.0 --port 3000
158
```
159
160
### Environment Variables
161
162
The CLI supports environment variable configuration with `DAGSTER_WEBSERVER_` prefix:
163
164
```bash
165
# Environment variable examples
166
export DAGSTER_WEBSERVER_HOST=0.0.0.0
167
export DAGSTER_WEBSERVER_PORT=8080
168
export DAGSTER_WEBSERVER_LOG_LEVEL=debug
169
export DAGSTER_WEBSERVER_READ_ONLY=true
170
171
# Then run without options
172
dagster-webserver
173
```
174
175
### Workspace Options
176
177
The CLI accepts standard Dagster workspace options for specifying code locations via the `@workspace_options` decorator:
178
179
```bash
180
# Workspace file
181
dagster-webserver -w workspace.yaml
182
dagster-webserver --workspace-file workspace.yaml
183
184
# Python file
185
dagster-webserver -f path/to/definitions.py
186
dagster-webserver --python-file path/to/definitions.py
187
188
# Python module
189
dagster-webserver -m my_package.definitions
190
dagster-webserver --module-name my_package.definitions
191
192
# Working directory
193
dagster-webserver -f definitions.py -d /working/directory
194
dagster-webserver --python-file definitions.py --working-directory /working/directory
195
196
# Specific attribute/variable
197
dagster-webserver -f definitions.py -a my_definitions_variable
198
dagster-webserver --python-file definitions.py --attribute my_definitions_variable
199
200
# Multiple code locations
201
dagster-webserver -f file1.py -f file2.py -m module1 -m module2
202
203
# Package data directory (for installed packages)
204
dagster-webserver --package-name my_package --workspace-file workspace.yaml
205
```
206
207
**Workspace Option Details:**
208
- `-w/--workspace-file`: YAML file defining code locations and configuration
209
- `-f/--python-file`: Python file containing Dagster definitions
210
- `-m/--module-name`: Python module containing Dagster definitions
211
- `-d/--working-directory`: Working directory for relative paths
212
- `-a/--attribute`: Specific variable name containing definitions
213
- `--package-name`: Python package name for loading workspace files
214
- `--empty-workspace`: Start with empty workspace (for debugging)
215
216
## Constants
217
218
```python { .api }
219
# Default values used by CLI
220
DEFAULT_WEBSERVER_HOST = "127.0.0.1"
221
DEFAULT_WEBSERVER_PORT = 3000
222
DEFAULT_DB_STATEMENT_TIMEOUT = 15000 # milliseconds
223
DEFAULT_POOL_RECYCLE = 3600 # seconds
224
DEFAULT_POOL_MAX_OVERFLOW = 20
225
WEBSERVER_LOGGER_NAME = "dagster-webserver"
226
```
227
228
## Error Handling
229
230
The CLI handles common error scenarios:
231
232
- **Port in use**: Automatically finds free port if default is occupied
233
- **Invalid workspace**: Clear error messages for workspace configuration issues
234
- **Permission errors**: Informative messages for host/port binding failures
235
- **Configuration conflicts**: Validation of incompatible option combinations
236
237
## Backward Compatibility
238
239
The package maintains backward compatibility with the deprecated `dagit` command:
240
241
- `dagit` command still works but shows deprecation warning
242
- `DAGIT_*` environment variables are automatically converted to `DAGSTER_WEBSERVER_*`
243
- All functionality available through both command names until Dagster 2.0
244
245
```bash
246
# Deprecated but still supported
247
dagit --host 0.0.0.0 --port 3000 # Shows deprecation warning
248
249
# Environment variable conversion
250
export DAGIT_HOST=0.0.0.0
251
export DAGIT_PORT=3000
252
dagster-webserver # Uses converted DAGSTER_WEBSERVER_* variables
253
```