0
# CLI Management
1
2
Core commands for creating, initializing, and maintaining oclif CLI projects, including project setup and documentation generation.
3
4
## Capabilities
5
6
### Generate New CLI Project
7
8
Creates a complete oclif CLI project from scratch with all necessary files and dependencies.
9
10
```bash { .api }
11
oclif generate [NAME]
12
```
13
14
**Arguments:**
15
- `NAME` (string, required) - Directory name of the new project
16
17
**Flags:**
18
- `--author` (string) - Author name for package.json
19
- `--bin` (string) - Binary name for the CLI
20
- `--description` (string) - Description for package.json
21
- `--license` (string) - License type (default: MIT)
22
- `--module-type` (esm|commonjs) - Module system to use
23
- `--name` (string) - Package name override
24
- `--owner` (string) - GitHub owner/organization
25
- `--package-manager` (npm|yarn|pnpm) - Package manager preference
26
- `--repository` (string) - GitHub repository URL
27
- `--dry-run`, `-n` (boolean) - Preview changes without creating files
28
- `--output-dir`, `-d` (string) - Output directory path
29
- `--yes`, `-y` (boolean) - Skip all prompts with default values
30
31
**Usage Examples:**
32
33
```bash
34
# Interactive generation
35
oclif generate my-awesome-cli
36
37
# Automated generation with options
38
oclif generate my-cli --author="John Doe" --module-type=esm --package-manager=npm --yes
39
40
# Preview without creating files
41
oclif generate my-cli --dry-run
42
```
43
44
### Initialize Existing Project
45
46
Converts an existing Node.js project into an oclif CLI by adding necessary configuration and dependencies.
47
48
```bash { .api }
49
oclif init
50
```
51
52
**Flags:**
53
- `--bin` (string) - Binary name for the CLI
54
- `--module-type` (esm|commonjs) - Module system to use
55
- `--package-manager` (npm|yarn|pnpm) - Package manager preference
56
- `--topic-separator` (colons|spaces) - Separator for nested commands (default: spaces)
57
- `--output-dir`, `-d` (string) - Output directory path
58
- `--yes`, `-y` (boolean) - Skip all prompts with default values
59
60
**Usage Examples:**
61
62
```bash
63
# Interactive initialization
64
oclif init
65
66
# Initialize with specific options
67
oclif init --bin=mycli --module-type=esm --yes
68
```
69
70
### Generate README Documentation
71
72
Automatically generates or updates README.md with comprehensive command documentation, including usage examples and command descriptions.
73
74
```bash { .api }
75
oclif readme
76
```
77
78
**Flags:**
79
- `--aliases` (boolean) - Include command aliases in documentation
80
- `--dry-run` (boolean) - Preview README changes without writing
81
- `--multi` (boolean) - Generate multi-command CLI documentation format
82
- `--nested-topics-depth` (number) - Maximum nesting depth for topics
83
- `--output-dir` (string) - Output directory for README.md
84
- `--plugin-directory` (string) - Directory containing plugins to document
85
- `--readme-path` (string) - Path to README.md file (default: ./README.md)
86
- `--repository-prefix` (string) - GitHub repository prefix for links
87
- `--tsconfig-path` (string) - Path to TypeScript config file
88
- `--version` (string) - Version string for documentation
89
90
**Usage Examples:**
91
92
```bash
93
# Generate README for current project
94
oclif readme
95
96
# Preview changes without writing
97
oclif readme --dry-run
98
99
# Generate with custom options
100
oclif readme --multi --aliases --nested-topics-depth=3
101
```
102
103
### Create Plugin Manifest
104
105
Generates oclif.manifest.json containing plugin metadata, command definitions, and configuration for efficient CLI loading.
106
107
```bash { .api }
108
oclif manifest [PATH]
109
```
110
111
**Arguments:**
112
- `PATH` (string, default: ".") - Path to plugin or CLI project
113
114
**Flags:**
115
- `--jit` (boolean) - Include JIT (Just-In-Time) plugin commands in manifest
116
117
**Usage Examples:**
118
119
```bash
120
# Generate manifest for current directory
121
oclif manifest
122
123
# Generate manifest for specific path
124
oclif manifest ./plugins/my-plugin
125
126
# Include JIT plugin commands
127
oclif manifest --jit
128
```
129
130
### Legacy Lock Command (Deprecated)
131
132
Copies yarn.lock to oclif.lock for plugin dependency locking. This command is deprecated and will be removed in future versions.
133
134
```bash { .api }
135
oclif lock
136
```
137
138
**Status**: Hidden and deprecated - use modern dependency management instead
139
140
**Usage Examples:**
141
142
```bash
143
# Create oclif.lock from yarn.lock (deprecated)
144
oclif lock
145
```
146
147
## Configuration
148
149
oclif projects are configured through package.json in the `oclif` section:
150
151
```json { .api }
152
{
153
"oclif": {
154
"commands": "./lib/commands",
155
"bin": "mycli",
156
"dirname": "mycli",
157
"plugins": [
158
"@oclif/plugin-help"
159
],
160
"topicSeparator": " ",
161
"topics": {
162
"pack": {
163
"description": "Package CLI for distribution"
164
}
165
}
166
}
167
}
168
```
169
170
### Configuration Options
171
172
```typescript { .api }
173
interface OclifConfig {
174
/** Directory containing command files */
175
commands?: string;
176
/** Binary name for the CLI */
177
bin?: string;
178
/** Directory name for CLI installation */
179
dirname?: string;
180
/** Array of oclif plugins to load */
181
plugins?: string[];
182
/** Separator for nested command topics */
183
topicSeparator?: string;
184
/** Topic definitions with descriptions */
185
topics?: Record<string, { description: string }>;
186
/** macOS-specific configuration */
187
macos?: { identifier: string };
188
/** Auto-update configuration */
189
update?: UpdateConfig;
190
}
191
192
interface UpdateConfig {
193
autoupdate?: {
194
rollout?: number;
195
debounce?: number;
196
};
197
node?: { version: string };
198
s3?: S3UpdateConfig;
199
}
200
201
interface S3UpdateConfig {
202
bucket: string;
203
indexVersionLimit?: number;
204
folder?: string;
205
acl?: string;
206
host?: string;
207
xz?: boolean;
208
}
209
```