0
# Positional Parameters
1

2
Type-safe positional argument definitions. Supports tuple (fixed named args) and array (variadic args) forms.
3

4
## Quick Reference
5

6
```typescript
7
// Tuple (fixed arguments)
8
positional: {
9
  kind: "tuple",
10
  parameters: [
11
    { brief: "Source", parse: String },
12
    { brief: "Dest", parse: String, optional: true }
13
  ]
14
}
15

16
// Array (variadic arguments)
17
positional: {
18
  kind: "array",
19
  parameter: { brief: "Files", parse: String },
20
  minimum: 1,  // optional
21
  maximum: 10  // optional
22
}
23
```
24

25
## Tuple Form
26

27
Fixed number of named arguments in order.
28

29
```typescript { .api }
30
positional: {
31
  kind: "tuple",
32
  parameters: [
33
    {
34
      brief: "Source file path",
35
      parse: String,
36
      placeholder: "source"  // optional, defaults to arg1, arg2, ...
37
    },
38
    {
39
      brief: "Destination file path",
40
      parse: String,
41
      placeholder: "dest",
42
      optional: true  // optional argument
43
    }
44
  ]
45
}
46
```
47

48
**Example:**
49

50
```typescript
51
const copyCmd = buildCommand({
52
  func: async function(flags, source, dest) {
53
    this.process.stdout.write(`Copying ${source} to ${dest || "current directory"}\n`);
54
  },
55
  parameters: {
56
    positional: {
57
      kind: "tuple",
58
      parameters: [
59
        { brief: "Source path", parse: String },
60
        { brief: "Destination path", parse: String, optional: true }
61
      ]
62
    }
63
  },
64
  docs: { brief: "Copy file" }
65
});
66

67
// Usage: myapp source.txt dest.txt
68
// Usage: myapp source.txt
69
```
70

71
## Array Form
72

73
Variable number of similar arguments.
74

75
```typescript { .api }
76
positional: {
77
  kind: "array",
78
  parameter: {
79
    brief: "Files to process",
80
    parse: String,
81
    placeholder: "files",
82
    proposeCompletions: async () => await readdir(".")  // optional
83
  },
84
  minimum: 1,  // optional: minimum required args
85
  maximum: 10  // optional: maximum allowed args
86
}
87
```
88

89
**Example:**
90

91
```typescript
92
const processCmd = buildCommand({
93
  func: async function(flags, ...files) {
94
    this.process.stdout.write(`Processing ${files.length} files\n`);
95
    for (const file of files) {
96
      this.process.stdout.write(`  - ${file}\n`);
97
    }
98
  },
99
  parameters: {
100
    positional: {
101
      kind: "array",
102
      parameter: { brief: "Files to process", parse: String },
103
      minimum: 1
104
    }
105
  },
106
  docs: { brief: "Process files" }
107
});
108

109
// Usage: myapp file1.txt file2.txt file3.txt
110
```
111

112
## Parameter Properties
113

114
**Common:**
115
- `brief`: string (description)
116
- `parse`: InputParser<T, CONTEXT>
117
- `optional`: boolean (tuple only - makes parameter optional)
118
- `placeholder`: string (custom placeholder in usage line)
119
- `default`: string (default input value if not provided)
120
- `proposeCompletions`: (partial: string) => string[] | Promise<string[]>
121

122
## Combining with Flags
123

124
```typescript
125
const command = buildCommand({
126
  func: async function(flags, source, dest) {
127
    if (flags.recursive) {
128
      this.process.stdout.write("Recursive copy enabled\n");
129
    }
130
    this.process.stdout.write(`Copying ${source} to ${dest}\n`);
131
  },
132
  parameters: {
133
    flags: {
134
      recursive: { kind: "boolean", brief: "Recursive copy", default: false },
135
      verbose: { kind: "boolean", brief: "Verbose output", optional: true }
136
    },
137
    positional: {
138
      kind: "tuple",
139
      parameters: [
140
        { brief: "Source path", parse: String },
141
        { brief: "Destination path", parse: String }
142
      ]
143
    },
144
    aliases: { r: "recursive", v: "verbose" }
145
  },
146
  docs: { brief: "Copy files" }
147
});
148

149
// Usage: myapp --recursive source/ dest/
150
// Usage: myapp -r source/ dest/
151
// Usage: myapp source.txt dest.txt --verbose
152
```
153

154
## Related
155

156
- [Parameter Parsers](./parameter-parsers.md)
157
- [Flag Parameters](./flag-parameters.md)
158