0
# Console Commands
1

2
Development-time CLI commands for listing DevServices, viewing logs, and managing container lifecycle during development.
3

4
## Capabilities
5

6
### DevServicesCommand
7

8
Parent group command that provides the main entry point for DevServices CLI operations with subcommand management.
9

10
```java { .api }
11
/**
12
 * Group command definition for DevServices CLI operations
13
 */
14
@GroupCommandDefinition(name = "devservices", description = "Dev Service Commands")
15
public class DevServicesCommand implements GroupCommand {
16
    
17
    /**
18
     * Creates a DevServices command group with service descriptions
19
     * @param serviceDescriptions List of available dev service descriptions
20
     */
21
    public DevServicesCommand(List<DevServiceDescriptionBuildItem> serviceDescriptions);
22
    
23
    /**
24
     * Gets the list of available subcommands
25
     * @return List containing list and logs commands
26
     */
27
    @Override
28
    public List<Command> getCommands();
29
    
30
    /**
31
     * Executes the group command (shows help)
32
     * @param commandInvocation Command invocation context
33
     * @return SUCCESS status
34
     */
35
    @Override
36
    public CommandResult execute(CommandInvocation commandInvocation);
37
    
38
    /**
39
     * Finds a dev service by name
40
     * @param devServiceName Name of the service to find
41
     * @return Optional containing the service description if found
42
     */
43
    static Optional<DevServiceDescriptionBuildItem> findDevService(String devServiceName);
44
}
45
```
46

47
**Usage Examples:**
48

49
```java
50
// Creating DevServices command in build step
51
@BuildStep
52
public ConsoleCommandBuildItem createDevServicesCommand(
53
    List<DevServiceDescriptionBuildItem> serviceDescriptions) {
54
    
55
    DevServicesCommand devServicesCommand = new DevServicesCommand(serviceDescriptions);
56
    return new ConsoleCommandBuildItem(devServicesCommand);
57
}
58

59
// Using the command programmatically
60
List<DevServiceDescriptionBuildItem> services = getAvailableServices();
61
DevServicesCommand command = new DevServicesCommand(services);
62

63
// Get available subcommands
64
List<Command> subcommands = command.getCommands();
65
for (Command cmd : subcommands) {
66
    System.out.println("Available command: " + cmd.getClass().getSimpleName());
67
}
68

69
// Find specific service
70
Optional<DevServiceDescriptionBuildItem> postgres = 
71
    DevServicesCommand.findDevService("PostgreSQL Dev Service");
72
    
73
if (postgres.isPresent()) {
74
    DevServiceDescriptionBuildItem service = postgres.get();
75
    System.out.println("Found service: " + service.getName());
76
    System.out.println("Description: " + service.getDescription());
77
    
78
    if (service.hasContainerInfo()) {
79
        String containerId = service.getContainerInfo().id();
80
        System.out.println("Container ID: " + containerId);
81
    }
82
}
83
```
84

85
### DevServiceCompleter
86

87
Command completion support for DevService names, providing autocomplete functionality in the CLI.
88

89
```java { .api }
90
/**
91
 * Command completer for DevService names
92
 */
93
public static class DevServiceCompleter extends SetCompleter {
94
    
95
    /**
96
     * Provides completion options for DevService names
97
     * @param soFar Current input string
98
     * @return Set of matching service names
99
     */
100
    @Override
101
    protected Set<String> allOptions(String soFar);
102
}
103
```
104

105
### DevServicesListCommand
106

107
Command implementation that lists all running DevServices with their status and configuration information.
108

109
```java { .api }
110
/**
111
 * Command to list all running dev services
112
 */
113
@CommandDefinition(name = "list", description = "List of dev services")
114
public class DevServicesListCommand implements Command {
115
    
116
    /**
117
     * Executes the list command, displaying all dev services
118
     * @param commandInvocation Command invocation context
119
     * @return SUCCESS status
120
     */
121
    @Override
122
    public CommandResult execute(CommandInvocation commandInvocation);
123
}
124
```
125

126
**Usage Examples:**
127

128
```java
129
// Example output when running 'devservices list' command:
130
/*
131
PostgreSQL Dev Service
132
  Container: 1a2b3c4d5e6f  /postgres-dev  postgres:13
133
  Network: bridge - 0.0.0.0:5432->5432/tcp
134
  Exec command: docker exec -it 1a2b3c4d /bin/bash
135
  Injected config: - quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/quarkus
136

137
Redis Dev Service  
138
  Container: 9f8e7d6c5b4a  /redis-dev  redis:6-alpine
139
  Network: bridge - 0.0.0.0:6379->6379/tcp
140
  Exec command: docker exec -it 9f8e7d6c /bin/bash
141
  Injected config: - quarkus.redis.hosts=redis://localhost:6379
142

143
Compose Dev Services
144
  Project: my-app-devservices, Services: database, message-queue
145
  Injected config: - DATABASE_URL=postgresql://localhost:5433/mydb
146
                  - RABBITMQ_URL=amqp://localhost:5672
147
*/
148

149
// Programmatic usage
150
DevServicesListCommand listCommand = new DevServicesListCommand();
151
CommandInvocation mockInvocation = createMockInvocation();
152
CommandResult result = listCommand.execute(mockInvocation);
153

154
if (result == CommandResult.SUCCESS) {
155
    System.out.println("Successfully listed dev services");
156
}
157
```
158

159
### DevServicesLogsCommand
160

161
Command implementation that displays container logs for a specific DevService with optional following and tailing support.
162

163
```java { .api }
164
/**
165
 * Command to display container logs for a dev service
166
 */
167
@CommandDefinition(name = "logs", description = "Print container logs")
168
public class DevServicesLogsCommand implements Command {
169
    
170
    /**
171
     * Dev Service name (required argument with completion support)
172
     */
173
    @Argument(required = true, description = "Dev Service name", completer = DevServiceCompleter.class)
174
    private String devService;
175
    
176
    /**
177
     * Follow logs in real-time
178
     */
179
    @Option(name = "follow", shortName = 'f', description = "Follow container logs", hasValue = false, defaultValue = "false")
180
    private boolean follow;
181
    
182
    /**
183
     * Number of lines to tail (-1 for all)
184
     */
185
    @Option(name = "tail", shortName = 't', description = "Tail container logs", defaultValue = "-1")
186
    private int tail;
187
    
188
    /**
189
     * Executes the logs command
190
     * @param commandInvocation Command invocation context
191
     * @return SUCCESS if service found and logs displayed, FAILURE otherwise
192
     */
193
    @Override
194
    public CommandResult execute(CommandInvocation commandInvocation);
195
}
196
```
197

198
**Usage Examples:**
199

200
```java
201
// Command line usage examples:
202

203
// Show all logs for a service
204
// > devservices logs "PostgreSQL Dev Service"
205

206
// Follow logs in real-time
207
// > devservices logs -f "PostgreSQL Dev Service" 
208

209
// Show last 50 lines and follow
210
// > devservices logs -t 50 -f "Redis Dev Service"
211

212
// Just last 100 lines
213
// > devservices logs --tail 100 "Compose Dev Services"
214

215
// Programmatic usage
216
DevServicesLogsCommand logsCommand = new DevServicesLogsCommand();
217

218
// Set command arguments programmatically (normally done by CLI framework)
219
setCommandArgument(logsCommand, "devService", "PostgreSQL Dev Service");
220
setCommandOption(logsCommand, "follow", true);
221
setCommandOption(logsCommand, "tail", 50);
222

223
CommandInvocation invocation = createCommandInvocation();
224
CommandResult result = logsCommand.execute(invocation);
225

226
if (result == CommandResult.SUCCESS) {
227
    System.out.println("Successfully displayed logs");
228
} else {
229
    System.err.println("Failed to find service or display logs");
230
}
231

232
// Example log output:
233
/*
234
2024-01-15 10:30:25.123 UTC [1] LOG:  database system was shut down at 2024-01-15 10:30:20 UTC
235
2024-01-15 10:30:25.125 UTC [1] LOG:  database system is ready to accept connections
236
2024-01-15 10:30:25.126 UTC [7] LOG:  autovacuum launcher started
237
2024-01-15 10:30:30.445 UTC [8] LOG:  connection received: host=172.17.0.1 port=54321
238
2024-01-15 10:30:30.447 UTC [8] LOG:  connection authorized: user=quarkus database=quarkus
239
*/
240
```
241

242
### ContainerLogForwarder  
243

244
Manages log forwarding from containers to the application logging system with start/stop lifecycle control.
245

246
```java { .api }
247
/**
248
 * Forwards container logs to application logging system
249
 */
250
public class ContainerLogForwarder implements Closeable {
251
    
252
    /**
253
     * Creates a log forwarder for a dev service
254
     * @param devService Dev service description containing container info
255
     */
256
    public ContainerLogForwarder(DevServiceDescriptionBuildItem devService);
257
    
258
    /**
259
     * Gets the associated dev service
260
     * @return Dev service description
261
     */
262
    public DevServiceDescriptionBuildItem getDevService();
263
    
264
    /**
265
     * Checks if log forwarding is currently active
266
     * @return true if logs are being forwarded
267
     */
268
    public boolean isRunning();
269
    
270
    /**
271
     * Starts log forwarding from the container
272
     */
273
    public void start();
274
    
275
    /**
276
     * Stops log forwarding and cleans up resources
277
     */
278
    @Override
279
    public void close();
280
}
281
```
282

283
**Usage Examples:**
284

285
```java
286
// Managing log forwarders for dev services
287
Map<String, ContainerLogForwarder> logForwarders = new HashMap<>();
288

289
// Create log forwarders for all services with containers
290
for (DevServiceDescriptionBuildItem service : serviceDescriptions) {
291
    if (service.hasContainerInfo()) {
292
        String containerId = service.getContainerInfo().id();
293
        ContainerLogForwarder forwarder = new ContainerLogForwarder(service);
294
        logForwarders.put(containerId, forwarder);
295
    }
296
}
297

298
// Start log forwarding for all services
299
for (ContainerLogForwarder forwarder : logForwarders.values()) {
300
    if (!forwarder.isRunning()) {
301
        forwarder.start();
302
        System.out.println("Started log forwarding for: " + 
303
                          forwarder.getDevService().getName());
304
    }
305
}
306

307
// Toggle log forwarding based on user preference
308
boolean enableLogForwarding = getUserPreference();
309

310
for (ContainerLogForwarder forwarder : logForwarders.values()) {
311
    if (enableLogForwarding && !forwarder.isRunning()) {
312
        forwarder.start();
313
    } else if (!enableLogForwarding && forwarder.isRunning()) {
314
        forwarder.close();
315
    }
316
}
317

318
// Cleanup when shutting down
319
try {
320
    for (ContainerLogForwarder forwarder : logForwarders.values()) {
321
        if (forwarder.isRunning()) {
322
            forwarder.close();
323
        }
324
    }
325
} catch (Exception e) {
326
    System.err.println("Error during log forwarder cleanup: " + e.getMessage());
327
}
328

329
// Example logged output format:
330
/*
331
2024-01-15 10:30:25.123 INFO  [PostgreSQL Dev Service] [1a2b3c4d] 2024-01-15 10:30:25.123 UTC [1] LOG:  database system is ready to accept connections
332
2024-01-15 10:30:26.234 ERROR [Redis Dev Service] [9f8e7d6c] 1:M 15 Jan 2024 10:30:26.234 # Warning: no config file specified, using the default config
333
2024-01-15 10:30:27.345 INFO  [Message Queue] [5a6b7c8d] 2024-01-15 10:30:27.345 [info] <0.123.0> accepting AMQP connection <0.456.0> (127.0.0.1:54321 -> 127.0.0.1:5672)
334
*/
335

336
// Using with try-with-resources
337
try (ContainerLogForwarder forwarder = new ContainerLogForwarder(serviceDescription)) {
338
    forwarder.start();
339
    
340
    // Do work while logs are being forwarded
341
    performDevelopmentTasks();
342
    
343
    // Forwarder automatically closed when leaving try block
344
}
345
```
346

347
## Integration with Quarkus Console
348

349
These commands integrate with the Quarkus development console through build steps:
350

351
```java
352
@BuildStep(onlyIf = { IsDevelopment.class })
353
public void registerConsoleCommands(
354
    List<DevServiceDescriptionBuildItem> serviceDescriptions,
355
    BuildProducer<ConsoleCommandBuildItem> commandProducer) {
356
    
357
    // Register the DevServices command group
358
    DevServicesCommand devServicesCommand = new DevServicesCommand(serviceDescriptions);
359
    commandProducer.produce(new ConsoleCommandBuildItem(devServicesCommand));
360
}
361
```
362

363
### Console Integration Features
364

365
The commands are available in the Quarkus development console and provide:
366

367
- **Interactive Command Completion**: Service names auto-complete when typing commands
368
- **Real-time Log Streaming**: The logs command can follow container output in real-time
369
- **Container Inspection**: Easy access to container details and configurations
370
- **Development Workflow Integration**: Seamless integration with hot reload and continuous testing
371

372
### Usage in Development Mode
373

374
When running Quarkus in development mode (`mvn quarkus:dev`), the DevServices commands become available:
375

376
```
377
2024-01-15 10:30:25,123 INFO  [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.
378
2024-01-15 10:30:25,124 INFO  [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, devservices-deployment, ...]
379

380
Tests paused
381
Press [SPACE] to restart, [e] to edit command line args (currently ''), [r] to resume testing, [o] Toggle test output, [h] for more options>
382

383
# Available DevServices commands:
384
# devservices list - List all running dev services
385
# devservices logs <service-name> - Show logs for a specific service
386
```
387

388
The console provides immediate feedback and allows developers to inspect and manage their development services without leaving the development environment.