0
# Application Building and Execution
1

2
Build and run @stricli/core CLI applications. Supports both single-command and multi-command (route map) applications.
3

4
## Quick Reference
5

6
```typescript
7
// Single command
8
const app = buildApplication(command, { name: "myapp" })
9

10
// Multiple commands
11
const app = buildApplication(routeMap, { name: "myapp", versionInfo: { currentVersion: "1.0.0" } })
12

13
// Run
14
await run(app, process.argv.slice(2), { process })
15
```
16

17
## API
18

19
### buildApplication
20

21
Builds an application from a command or route map.
22

23
```typescript { .api }
24
function buildApplication<CONTEXT extends CommandContext>(
25
  root: Command<CONTEXT> | RouteMap<CONTEXT>,
26
  config: PartialApplicationConfiguration
27
): Application<CONTEXT>
28
```
29

30
**Parameters:**
31
- `root`: Command or RouteMap serving as entry point
32
- `config`: Application configuration (name required, rest optional with defaults)
33

34
**Returns:** Complete Application instance
35

36
**Example:**
37

38
```typescript
39
const app = buildApplication(
40
  buildCommand({
41
    func: async function(flags) {
42
      this.process.stdout.write(`Port: ${flags.port}\n`);
43
    },
44
    parameters: {
45
      flags: {
46
        port: { kind: "parsed", parse: numberParser, brief: "Server port", default: "3000" }
47
      }
48
    },
49
    docs: { brief: "Start server" }
50
  }),
51
  {
52
    name: "myapp",
53
    versionInfo: { currentVersion: "1.0.0" },
54
    scanner: { caseStyle: "allow-kebab-for-camel" }
55
  }
56
);
57
```
58

59
### run
60

61
Runs a CLI application with command-line inputs and context. Sets `process.exitCode` but doesn't call `process.exit()`.
62

63
```typescript { .api }
64
async function run<CONTEXT extends CommandContext>(
65
  app: Application<CONTEXT>,
66
  inputs: readonly string[],
67
  context: StricliDynamicCommandContext<CONTEXT>
68
): Promise<void>
69
```
70

71
**Parameters:**
72
- `app`: Application to run
73
- `inputs`: Command-line arguments (typically `process.argv.slice(2)`)
74
- `context`: Dynamic context with process info and optional command context builder
75

76
**Behavior:**
77
- Processes inputs to find and execute appropriate command
78
- Handles `--version` flag if configured
79
- Performs version check and displays warnings if newer version available
80
- Loads localized text based on context locale
81
- Displays help if requested or if route map is reached
82
- Sets `context.process.exitCode` (does not call `process.exit()`)
83

84
**Example:**
85

86
```typescript
87
await run(app, process.argv.slice(2), {
88
  process,
89
  locale: "en"
90
});
91

92
// Or with custom context builder
93
await run(app, process.argv.slice(2), {
94
  process,
95
  async forCommand(info) {
96
    return {
97
      process,
98
      database: await connectDB(),
99
      logger: createLogger(info.prefix.join(" "))
100
    };
101
  }
102
});
103
```
104

105
### Application Interface
106

107
```typescript { .api }
108
interface Application<CONTEXT extends CommandContext> {
109
  readonly root: Command<CONTEXT> | RouteMap<CONTEXT>
110
  readonly config: ApplicationConfiguration
111
  readonly defaultText: ApplicationText
112
}
113
```
114

115
## Complete Example
116

117
```typescript
118
import { buildApplication, buildRouteMap, buildCommand, run } from "@stricli/core";
119

120
interface MyContext extends CommandContext {
121
  database: Database;
122
}
123

124
const app = buildApplication(
125
  buildRouteMap({
126
    routes: {
127
      start: buildCommand({
128
        func: async function(this: MyContext) {
129
          await this.database.connect();
130
          this.process.stdout.write("Started\n");
131
        },
132
        parameters: {},
133
        docs: { brief: "Start service" }
134
      }),
135
      stop: buildCommand({
136
        func: async function(this: MyContext) {
137
          await this.database.disconnect();
138
          this.process.stdout.write("Stopped\n");
139
        },
140
        parameters: {},
141
        docs: { brief: "Stop service" }
142
      })
143
    },
144
    docs: { brief: "Service management" }
145
  }),
146
  {
147
    name: "service-cli",
148
    versionInfo: { currentVersion: "1.0.0" },
149
    scanner: { caseStyle: "allow-kebab-for-camel" }
150
  }
151
);
152

153
await run(app, process.argv.slice(2), {
154
  process,
155
  async forCommand() {
156
    return { process, database: createDatabase() };
157
  }
158
});
159
```
160

161
## Related
162

163
- [Commands and Routing](./commands-and-routing.md)
164
- [Configuration and Context](./configuration-and-context.md)
165
- [Exit Codes](./exit-codes.md)
166