0
# Configuration and Context
1

2
Application configuration and context threading for custom data and behavior control.
3

4
## Quick Reference
5

6
```typescript
7
// Basic configuration
8
const app = buildApplication(command, {
9
  name: "myapp",
10
  versionInfo: { currentVersion: "1.0.0" }
11
})
12

13
// With custom settings
14
const app = buildApplication(command, {
15
  name: "myapp",
16
  versionInfo: { currentVersion: "1.0.0" },
17
  scanner: { caseStyle: "allow-kebab-for-camel", allowArgumentEscapeSequence: true },
18
  documentation: { useAliasInUsageLine: true, disableAnsiColor: false },
19
  determineExitCode: (exc) => exc instanceof MyError ? exc.code : 1
20
})
21

22
// Custom context
23
interface MyContext extends CommandContext {
24
  database: Database;
25
  logger: Logger;
26
}
27

28
await run(app, inputs, {
29
  process,
30
  async forCommand(info) {
31
    return { process, database: await connectDB(), logger: createLogger() };
32
  }
33
})
34
```
35

36
## Configuration
37

38
### PartialApplicationConfiguration
39

40
```typescript { .api }
41
interface PartialApplicationConfiguration {
42
  name: string  // Required: application name
43
  versionInfo?: VersionInfo
44
  scanner?: Partial<ScannerConfiguration>
45
  documentation?: Partial<DocumentationConfiguration>
46
  completion?: Partial<CompletionConfiguration>
47
  localization?: Partial<LocalizationConfiguration>
48
  determineExitCode?: (exc: unknown) => number
49
}
50
```
51

52
### Scanner Configuration
53

54
Controls command/argument scanning behavior.
55

56
```typescript { .api }
57
scanner: {
58
  caseStyle: "original" | "allow-kebab-for-camel",  // default: "original"
59
  allowArgumentEscapeSequence: boolean,  // default: false (enables -- separator)
60
  distanceOptions: {  // "did you mean?" suggestions
61
    threshold: number,  // default: 7
62
    weights: {
63
      insertion: number,  // default: 1
64
      deletion: number,  // default: 3
65
      substitution: number,  // default: 2
66
      transposition: number  // default: 0
67
    }
68
  }
69
}
70
```
71

72
**caseStyle:**
73
- `"original"`: Exact match only (`--myFlag`)
74
- `"allow-kebab-for-camel"`: Accept both `--myFlag` and `--my-flag`
75

76
**allowArgumentEscapeSequence:** If true, `--` marks end of flags (all subsequent inputs treated as arguments).
77

78
### Documentation Configuration
79

80
Controls help text formatting.
81

82
```typescript { .api }
83
documentation: {
84
  alwaysShowHelpAllFlag: boolean,  // default: false
85
  useAliasInUsageLine: boolean,  // default: false
86
  onlyRequiredInUsageLine: boolean,  // default: false
87
  caseStyle: "original" | "convert-camel-to-kebab",  // default: derived from scanner
88
  disableAnsiColor: boolean  // default: false
89
}
90
```
91

92
### Version Info
93

94
```typescript { .api }
95
versionInfo: {
96
  currentVersion: "1.0.0",  // Static version
97
  // OR
98
  getCurrentVersion: async function() { return "1.0.0" },  // Dynamic version
99
  
100
  // Optional:
101
  getLatestVersion: async function(currentVersion) { /* check registry */ },
102
  upgradeCommand: "npm install -g myapp@latest"
103
}
104
```
105

106
### Custom Exit Codes
107

108
```typescript
109
determineExitCode: (exc) => {
110
  if (exc instanceof BusinessError) return exc.exitCode;
111
  if (exc instanceof Error && exc.message.includes("timeout")) return 124;
112
  return 1;
113
}
114
```
115

116
## Context
117

118
### CommandContext
119

120
Base context interface with process streams.
121

122
```typescript { .api }
123
interface CommandContext {
124
  process: {
125
    stdout: Writable;
126
    stderr: Writable;
127
  }
128
}
129
```
130

131
### Custom Context
132

133
Extend CommandContext for application-specific data.
134

135
```typescript
136
interface MyContext extends CommandContext {
137
  database: Database;
138
  logger: Logger;
139
  config: Config;
140
}
141

142
const command = buildCommand({
143
  func: async function(this: MyContext, flags) {
144
    await this.database.connect();
145
    this.logger.info("Connected");
146
    this.process.stdout.write("Done\n");
147
  },
148
  parameters: {},
149
  docs: { brief: "Command" }
150
});
151
```
152

153
### Context Builder
154

155
Dynamic context creation per command.
156

157
```typescript
158
await run(app, inputs, {
159
  process,
160
  locale: "en",
161
  async forCommand(info) {
162
    // info.prefix contains command route (e.g., ["myapp", "db", "migrate"])
163
    return {
164
      process,
165
      database: await connectDB(),
166
      logger: createLogger(info.prefix.join(" "))
167
    };
168
  }
169
});
170
```
171

172
## Complete Example
173

174
```typescript
175
import { buildApplication, run } from "@stricli/core";
176

177
interface AppContext extends CommandContext {
178
  database: Database;
179
  logger: Logger;
180
}
181

182
class AppError extends Error {
183
  constructor(message: string, public exitCode: number) {
184
    super(message);
185
  }
186
}
187

188
const app = buildApplication<AppContext>(command, {
189
  name: "myapp",
190
  versionInfo: {
191
    currentVersion: "2.1.0",
192
    async getLatestVersion() {
193
      const res = await fetch("https://api.example.com/version");
194
      return res.json().then(d => d.latest);
195
    },
196
    upgradeCommand: "npm install -g myapp@latest"
197
  },
198
  scanner: {
199
    caseStyle: "allow-kebab-for-camel",
200
    allowArgumentEscapeSequence: true
201
  },
202
  documentation: {
203
    useAliasInUsageLine: true,
204
    disableAnsiColor: false
205
  },
206
  determineExitCode: (exc) => {
207
    if (exc instanceof AppError) return exc.exitCode;
208
    return 1;
209
  }
210
});
211

212
await run(app, process.argv.slice(2), {
213
  process,
214
  locale: process.env.LANG,
215
  async forCommand(info) {
216
    return {
217
      process,
218
      database: await connectDB(),
219
      logger: createLogger(info.prefix.join(" "))
220
    };
221
  }
222
});
223
```
224

225
## Environment Variables
226

227
- `STRICLI_SKIP_VERSION_CHECK=1`: Skip automatic version checking
228
- `STRICLI_NO_COLOR=1`: Disable ANSI color output
229

230
## Related
231

232
- [Exit Codes](./exit-codes.md)
233
- [Text and Localization](./text-and-localization.md)
234