0
# Command Line Interface
1

2
The dagster-graphql command-line interface provides scripted access to Dagster's GraphQL API for automation, debugging, and operational tasks. It supports both local workspace operations and remote server connectivity.
3

4
## Capabilities
5

6
### CLI Entry Point
7

8
Main command-line interface for executing GraphQL operations against Dagster workspaces and remote servers.
9

10
```python { .api }
11
def main():
12
    """
13
    Main CLI entry point for dagster-graphql command.
14
    
15
    Provides access to GraphQL query execution with various input methods
16
    and output options for automation and debugging workflows.
17
    """
18
```
19

20
Command-line usage:
21

22
```bash
23
# Install package with CLI
24
pip install dagster-graphql
25

26
# Basic GraphQL query execution
27
dagster-graphql -t "query { instance { info } }"
28

29
# Execute query from file
30
dagster-graphql -f query.graphql
31

32
# Use predefined query with variables
33
dagster-graphql -p launchPipelineExecution -v '{"executionParams": {...}}'
34

35
# Execute against remote server
36
dagster-graphql -r https://my-dagster.com -t "query { runs { runId } }"
37

38
# Save output to file
39
dagster-graphql -t "query { runs { runId status } }" -o results.json
40
```
41

42
### Query Input Methods
43

44
Multiple methods for providing GraphQL queries including text input, file input, and predefined queries.
45

46
```python { .api }
47
@click.command(name="ui")
48
@click.option("--text", "-t", type=click.STRING, help="GraphQL document as string")
49
@click.option("--file", "-f", type=click.File(), help="GraphQL document from file")  
50
@click.option("--predefined", "-p", type=click.Choice(list(PREDEFINED_QUERIES.keys())), help="Predefined GraphQL document")
51
@click.option("--variables", "-v", type=click.STRING, help="JSON encoded variables")
52
@click.option("--remote", "-r", type=click.STRING, help="Remote server URL")
53
@click.option("--output", "-o", type=click.STRING, help="Output file path")
54
@click.option("--ephemeral-instance", is_flag=True, help="Use ephemeral DagsterInstance")
55
def ui(text, file, predefined, variables, remote, output, ephemeral_instance, **other_opts):
56
    """
57
    Execute GraphQL queries against Dagster interface.
58
    
59
    Parameters:
60
    - text: GraphQL query as command-line string
61
    - file: GraphQL query from file
62
    - predefined: Use predefined query by name
63
    - variables: JSON-encoded GraphQL variables
64
    - remote: Remote Dagster server URL
65
    - output: File to save query results
66
    - ephemeral_instance: Use temporary instance instead of DAGSTER_HOME
67
    """
68
```
69

70
Usage examples:
71

72
```bash
73
# Text query with variables
74
dagster-graphql -t "query GetRuns(\$limit: Int) { runs(limit: \$limit) { runId } }" -v '{"limit": 5}'
75

76
# File-based query
77
echo 'query { instance { daemonHealth { id healthy } } }' > health.graphql
78
dagster-graphql -f health.graphql
79

80
# Predefined query for job execution
81
dagster-graphql -p launchPipelineExecution -v '{
82
  "executionParams": {
83
    "selector": {
84
      "repositoryLocationName": "analytics",
85
      "repositoryName": "data_repo", 
86
      "pipelineName": "daily_etl"
87
    }
88
  }
89
}'
90
```
91

92
### Remote Server Operations
93

94
Execute GraphQL operations against remote Dagster servers with automatic server validation and error handling.
95

96
```python { .api }
97
def execute_query_against_remote(host, query, variables):
98
    """
99
    Execute GraphQL query against remote Dagster server.
100

101
    Parameters:
102
    - host (str): Host URL for remote Dagster server (must include scheme)
103
    - query (str): GraphQL query string to execute  
104
    - variables: Variables for GraphQL execution
105

106
    Returns:
107
    - dict: JSON response from remote server
108

109
    Raises:
110
    - click.UsageError: If host URL is invalid or server fails sanity check
111
    
112
    Note: Performs automatic sanity check by verifying /server_info endpoint
113
    contains 'dagster_webserver' to ensure target is a Dagster server.
114
    """
115
```
116

117
Usage examples:
118

119
```bash
120
# Query remote Dagster server
121
dagster-graphql -r https://dagster.mycompany.com -t "query { runs(limit: 10) { runId status } }"
122

123
# Remote query with authentication headers (use environment variables for tokens)
124
export DAGSTER_CLOUD_API_TOKEN="your-token-here"
125
dagster-graphql -r https://myorg.dagster.cloud -t "query { instance { info } }"
126

127
# Remote job execution
128
dagster-graphql -r https://dagster.mycompany.com -p launchPipelineExecution -v '{
129
  "executionParams": {
130
    "selector": {
131
      "repositoryLocationName": "production",
132
      "repositoryName": "main_repo",
133
      "pipelineName": "critical_pipeline" 
134
    },
135
    "runConfigData": {"ops": {"extract": {"config": {"date": "2023-10-01"}}}}
136
  }
137
}'
138
```
139

140
### Workspace Integration
141

142
Integration with Dagster workspace configuration for local development and testing environments.
143

144
```bash
145
# Use specific workspace file
146
dagster-graphql -y workspace.yaml -t "query { repositoriesOrError { ... } }"
147

148
# Python file with repository definition
149
dagster-graphql -f my_repo.py -a my_repository -t "query { runs { runId } }"
150

151
# Module-based repository
152
dagster-graphql -m my_package.repository -a get_repo -t "query { jobs { name } }"
153

154
# Ephemeral instance for testing
155
dagster-graphql --ephemeral-instance -t "query { instance { info } }"
156
```
157

158
### Output Management
159

160
Flexible output handling for automation workflows including file output and structured JSON responses.
161

162
```bash
163
# Save query results to file (useful for large responses)
164
dagster-graphql -t "query { runs { runId status logs { level message } } }" -o run_details.json
165

166
# Pipe output to other tools
167
dagster-graphql -t "query { runs { runId } }" | jq '.data.runs[].runId'
168

169
# Combine with shell scripting
170
RUN_IDS=$(dagster-graphql -t "query { runs(filter: {status: STARTED}) { runId } }" | jq -r '.data.runs[].runId')
171
for run_id in $RUN_IDS; do
172
  echo "Processing run: $run_id"
173
done
174
```
175

176
## Error Handling and Debugging
177

178
The CLI provides comprehensive error handling with detailed stack traces and debugging information:
179

180
```bash
181
# Server connectivity issues
182
dagster-graphql -r https://invalid-server.com -t "query { runs }"
183
# Output: Error when connecting to url... Did you specify hostname correctly?
184

185
# GraphQL syntax errors  
186
dagster-graphql -t "query { invalid syntax }"
187
# Output: GraphQL syntax error with position information
188

189
# Query execution errors with stack traces
190
dagster-graphql -t "query { nonexistentField }"
191
# Output: Field resolution error with full stack trace if available
192
```
193

194
## Predefined Operations
195

196
Available predefined queries for common operations:
197

198
- **launchPipelineExecution**: Execute jobs/pipelines with full configuration
199
- Additional predefined queries can be added for common operational tasks
200

201
```bash
202
# List available predefined queries
203
dagster-graphql --help  # Shows available options for -p/--predefined
204

205
# Use predefined query
206
dagster-graphql -p launchPipelineExecution -v '{
207
  "executionParams": {
208
    "selector": {"repositoryLocationName": "main", "repositoryName": "repo", "pipelineName": "job"},
209
    "runConfigData": {}
210
  }
211
}'
212
```
213

214
## Integration Examples
215

216
### CI/CD Pipeline Integration
217

218
```bash
219
#!/bin/bash
220
# Deploy and verify pipeline
221
echo "Executing data validation job..."
222
RESULT=$(dagster-graphql -r $DAGSTER_SERVER -p launchPipelineExecution -v '{
223
  "executionParams": {
224
    "selector": {
225
      "repositoryLocationName": "production",
226
      "repositoryName": "data_validation", 
227
      "pipelineName": "daily_validation"
228
    }
229
  }
230
}')
231

232
RUN_ID=$(echo $RESULT | jq -r '.data.launchPipelineExecution.run.runId')
233
echo "Started validation run: $RUN_ID"
234

235
# Monitor run status
236
while true; do
237
  STATUS=$(dagster-graphql -r $DAGSTER_SERVER -t "query { runOrError(runId: \"$RUN_ID\") { ... on Run { status } } }" | jq -r '.data.runOrError.status')
238
  if [[ "$STATUS" == "SUCCESS" ]]; then
239
    echo "Validation completed successfully"
240
    break
241
  elif [[ "$STATUS" == "FAILURE" ]]; then
242
    echo "Validation failed"
243
    exit 1
244
  fi
245
  sleep 30
246
done
247
```
248

249
### Monitoring and Alerting
250

251
```bash
252
#!/bin/bash
253
# Check for failed runs in last hour
254
FAILED_RUNS=$(dagster-graphql -r $DAGSTER_SERVER -t '
255
  query {
256
    runs(filter: {status: FAILURE, createdAfter: "'$(date -d '1 hour ago' -Iseconds)'"}) {
257
      runId
258
      pipelineName
259
      status
260
      startTime
261
    }
262
  }
263
' | jq '.data.runs')
264

265
if [[ $(echo $FAILED_RUNS | jq 'length') -gt 0 ]]; then
266
  echo "Alert: Failed runs detected in last hour"
267
  echo $FAILED_RUNS | jq '.'
268
  # Send to alerting system
269
fi
270
```