0
# Documentation and Help
1

2
Generate help text and shell completions for commands.
3

4
## Quick Reference
5

6
```typescript
7
// Generate help for all commands
8
const docs = generateHelpTextForAllCommands(app);
9
for (const [route, helpText] of docs) {
10
  console.log(`${route}:\n${helpText}\n`);
11
}
12

13
// Shell completions
14
const completions = await proposeCompletions(app, ["myapp", "deploy", "--e"], { process });
15
// Returns: [{ kind: "argument:flag", completion: "--env", brief: "Environment" }]
16
```
17

18
## Generate Help Text
19

20
```typescript { .api }
21
function generateHelpTextForAllCommands(
22
  app: Application<CommandContext>,
23
  locale?: string
24
): readonly [route: string, helpText: string][]
25
```
26

27
**Example:**
28

29
```typescript
30
const app = buildApplication(routeMap, { name: "myapp" });
31
const docs = generateHelpTextForAllCommands(app);
32

33
// docs = [
34
//   ["myapp deploy", "USAGE\n  myapp deploy [OPTIONS]\n\n..."],
35
//   ["myapp status", "USAGE\n  myapp status\n\n..."]
36
// ]
37

38
// Write to files
39
for (const [route, helpText] of docs) {
40
  const filename = route.replace(/ /g, "-") + ".txt";
41
  await writeFile(filename, helpText);
42
}
43
```
44

45
## Propose Completions
46

47
```typescript { .api }
48
async function proposeCompletions<CONTEXT>(
49
  app: Application<CONTEXT>,
50
  rawInputs: readonly string[],
51
  context: StricliDynamicCommandContext<CONTEXT>
52
): Promise<readonly InputCompletion[]>
53
```
54

55
**InputCompletion:**
56

57
```typescript
58
type InputCompletion = ArgumentCompletion | RoutingTargetCompletion
59

60
interface ArgumentCompletion {
61
  kind: "argument:flag" | "argument:value"
62
  completion: string
63
  brief: string
64
}
65

66
interface RoutingTargetCompletion {
67
  kind: "routing-target:command" | "routing-target:route-map"
68
  completion: string
69
  brief: string
70
}
71
```
72

73
**Examples:**
74

75
```typescript
76
// Complete command names
77
await proposeCompletions(app, ["myapp", "de"], { process })
78
// Returns: [{ kind: "routing-target:command", completion: "deploy", brief: "Deploy application" }]
79

80
// Complete flag names
81
await proposeCompletions(app, ["myapp", "deploy", "--e"], { process })
82
// Returns: [{ kind: "argument:flag", completion: "--env", brief: "Environment" }]
83

84
// Complete flag values
85
await proposeCompletions(app, ["myapp", "deploy", "--env", "st"], { process })
86
// Returns: [{ kind: "argument:value", completion: "staging", brief: "Environment" }]
87

88
// Complete aliases
89
await proposeCompletions(app, ["myapp", "deploy", "-"], { process })
90
// Returns: [
91
//   { kind: "argument:flag", completion: "-e", brief: "Environment" },
92
//   { kind: "argument:flag", completion: "-f", brief: "Force deployment" }
93
// ]
94
```
95

96
## Shell Completion Command
97

98
```typescript
99
const completeCmd = buildCommand({
100
  func: async function(flags, ...inputs) {
101
    const completions = await proposeCompletions(app, inputs, { process });
102
    for (const completion of completions) {
103
      this.process.stdout.write(completion.completion + "\n");
104
    }
105
  },
106
  parameters: {
107
    positional: {
108
      kind: "array",
109
      parameter: { brief: "Input words", parse: String }
110
    }
111
  },
112
  docs: { brief: "Shell completion", hideRoute: { __complete: true } }
113
});
114

115
const app = buildApplication(
116
  buildRouteMap({
117
    routes: {
118
      ...mainRoutes,
119
      __complete: completeCmd  // Hidden completion command
120
    },
121
    docs: { brief: "My CLI" }
122
  }),
123
  { name: "myapp" }
124
);
125
```
126

127
### Bash Completion Script
128

129
```bash
130
_myapp_completions() {
131
  local completions=$(myapp __complete "${COMP_WORDS[@]:1}")
132
  COMPREPLY=($(compgen -W "$completions" -- "${COMP_WORDS[COMP_CWORD]}"))
133
}
134
complete -F _myapp_completions myapp
135
```
136

137
### Zsh Completion Script
138

139
```zsh
140
#compdef myapp
141

142
_myapp() {
143
  local completions=(${(f)"$(myapp __complete ${words[@]:1})"})
144
  _describe 'command' completions
145
}
146

147
_myapp
148
```
149

150
## Custom Completions
151

152
Add `proposeCompletions` to parameter definitions for dynamic completions.
153

154
```typescript
155
// File path completions
156
positional: {
157
  kind: "tuple",
158
  parameters: [
159
    {
160
      brief: "File to process",
161
      parse: String,
162
      proposeCompletions: async () => {
163
        const files = await readdir(".");
164
        return files.filter(f => f.endsWith(".txt"));
165
      }
166
    }
167
  ]
168
}
169

170
// API completions with context
171
interface MyContext extends CommandContext {
172
  api: { listUsers: () => Promise<string[]> };
173
}
174

175
positional: {
176
  kind: "tuple",
177
  parameters: [
178
    {
179
      brief: "User ID",
180
      parse: String,
181
      proposeCompletions: async function(this: MyContext) {
182
        return await this.api.listUsers();
183
      }
184
    }
185
  ]
186
}
187
```
188

189
## Related
190

191
- [Configuration and Context](./configuration-and-context.md)
192
- [Text and Localization](./text-and-localization.md)
193