0
# Program Creation
1

2
Core factory function for creating CLI program instances with support for both multi-command and single-command modes.
3

4
## Capabilities
5

6
### Factory Function
7

8
Creates a new Sade CLI program instance with optional single-command mode configuration.
9

10
```javascript { .api }
11
/**
12
 * Creates a new Sade CLI program instance
13
 * @param {string} name - The name/usage pattern of the CLI program
14
 * @param {boolean} [isSingle] - Enable single-command mode (auto-detected if name includes arguments)
15
 * @returns {Sade} Chainable Sade instance
16
 */
17
function sade(name, isSingle);
18
```
19

20
**Parameters:**
21

22
- `name` (string, required): The name of your CLI program or complete usage pattern
23
- `isSingle` (boolean, optional): Forces single-command mode when `true`. Auto-detected if `name` includes arguments like `[dir]` or `<file>`
24

25
**Returns:** A chainable `Sade` instance for method chaining
26

27
**Usage Examples:**
28

29
```javascript
30
const sade = require('sade');
31

32
// Multi-command CLI (like git, npm)
33
const prog = sade('my-cli');
34

35
// Single-command CLI with explicit flag
36
const prog = sade('my-tool', true);
37

38
// Single-command CLI with usage pattern (auto-detected)
39
const prog = sade('sirv [dir]');
40
// isSingle is automatically true because name includes arguments
41
```
42

43
### Single Command Mode
44

45
When enabled, single-command mode simplifies the CLI for applications that perform only one primary function.
46

47
**Characteristics:**
48
- No subcommands allowed (calling `command()` throws an error)
49
- Simplified help output without "Available Commands" section
50
- The entire program operates as one command
51
- Usage pattern can be specified directly in the `name` parameter
52

53
**Usage Examples:**
54

55
```javascript
56
// Single-command mode for a file server
57
const prog = sade('sirv [dir]', true)
58
  .version('1.0.0')
59
  .describe('Run a static file server')
60
  .option('-p, --port', 'Port to bind', 5000)
61
  .option('-H, --host', 'Hostname to bind', 'localhost')
62
  .action((dir, opts) => {
63
    console.log(`Starting server on ${opts.host}:${opts.port}`);
64
    // Server logic here
65
  });
66

67
prog.parse(process.argv);
68
```
69

70
**Help Output Example:**
71
```
72
  Description
73
    Run a static file server
74

75
  Usage
76
    $ sirv [dir] [options]
77

78
  Options
79
    -p, --port       Port to bind  (default 5000)
80
    -H, --host       Hostname to bind  (default localhost)
81
    -v, --version    Displays current version
82
    -h, --help       Displays this message
83
```
84

85
### Multi-Command Mode
86

87
Default mode for CLIs with multiple subcommands, like git or npm.
88

89
**Usage Examples:**
90

91
```javascript
92
// Multi-command CLI
93
const prog = sade('git');
94

95
prog
96
  .command('add <files..>')
97
  .describe('Add file contents to the index')
98
  .option('-A, --all', 'Add all files')
99
  .action((files, opts) => {
100
    // Add logic here
101
  });
102

103
prog
104
  .command('commit')
105
  .describe('Record changes to the repository')
106
  .option('-m, --message', 'Commit message')
107
  .action((opts) => {
108
    // Commit logic here
109
  });
110

111
prog.parse(process.argv);
112
```
113

114
### Error Handling
115

116
The factory function and subsequent operations can throw errors in various scenarios:
117

118
- **Single-mode violations**: Calling `command()` when `isSingle` is true
119
- **Invalid usage**: Malformed command patterns or conflicting configurations
120

121
```javascript
122
try {
123
  const prog = sade('my-tool', true);
124
  prog.command('invalid'); // Throws: "Disable 'single' mode to add commands"
125
} catch (error) {
126
  console.error(error.message);
127
}
128
```