1
>
/*---------------------------------------------------------------------------------------------
argv.ts
2
>
* Copyright (c) Microsoft Corporation. All rights reserved.
3
>
* Licensed under the MIT License. See License.txt in the project root for license information.
4
>
*--------------------------------------------------------------------------------------------*/
5
>
6
>
import minimist from 'minimist';
7
>
import { isWindows } from '../../../base/common/platform.js';
8
>
import { localize } from '../../../nls.js';
9
>
import { NativeParsedArgs } from '../common/argv.js';
10
>
11
>
/**
12
>
* This code is also used by standalone cli's. Avoid adding any other dependencies.
13
>
*/
14
>
const helpCategories = {
15
>
o: localize('optionsUpperCase', "Options"),
16
>
e: localize('extensionsManagement', "Extensions Management"),
17
>
t: localize('troubleshooting', "Troubleshooting"),
18
>
m: localize('mcp', "Model Context Protocol")
19
>
};
20
>
21
>
export interface Option<OptionType> {
22
>
type: OptionType;
23
>
alias?: string;
24
>
deprecates?: string[]; // old deprecated ids
25
>
args?: string | string[];
26
>
description?: string;
27
>
deprecationMessage?: string;
28
>
allowEmptyValue?: boolean;
29
>
cat?: keyof typeof helpCategories;
30
>
global?: boolean;
31
>
}
32
>
33
>
export interface Subcommand<T> {
34
>
type: 'subcommand';
35
>
description?: string;
36
>
deprecationMessage?: string;
37
>
options: OptionDescriptions<Required<T>>;
38
>
}
39
>
40
>
export type OptionDescriptions<T> = {
41
>
[P in keyof T]:
42
>
T[P] extends boolean | undefined ? Option<'boolean'> :
43
>
T[P] extends string | undefined ? Option<'string'> :
44
>
T[P] extends string[] | undefined ? Option<'string[]'> :
45
>
Subcommand<T[P]>
46
>
};
47
>
48
>
export const NATIVE_CLI_COMMANDS = ['tunnel', 'serve-web', 'agent'] as const;
49
>
50
>
export const OPTIONS: OptionDescriptions<Required<NativeParsedArgs>> = {
51
>
'chat': {
52
>
type: 'subcommand',
53
>
description: 'Pass in a prompt to run in a chat session in the current working directory.',
54
>
options: {
55
>
'_': { type: 'string[]', description: localize('prompt', "The prompt to use as chat.") },
56
>
'mode': { type: 'string', cat: 'o', alias: 'm', args: 'mode', description: localize('chatMode', "The mode to use for the chat session. Available options: 'ask', 'edit', 'agent', or the identifier of a custom mode. Defaults to 'agent'.") },
57
>
'add-file': { type: 'string[]', cat: 'o', alias: 'a', args: 'path', description: localize('addFile', "Add files as context to the chat session.") },
58
>
'maximize': { type: 'boolean', cat: 'o', description: localize('chatMaximize', "Maximize the chat session view.") },
59
>
'reuse-window': { type: 'boolean', cat: 'o', alias: 'r', description: localize('reuseWindowForChat', "Force to use the last active window for the chat session.") },
60
>
'new-window': { type: 'boolean', cat: 'o', alias: 'n', description: localize('newWindowForChat', "Force to open an empty window for the chat session.") },
61
>
'profile': { type: 'string', 'cat': 'o', args: 'profileName', description: localize('profileName', "Opens the provided folder or workspace with the given profile and associates the profile with the workspace. If the profile does not exist, a new empty one is created.") },
62
>
'help': { type: 'boolean', alias: 'h', description: localize('help', "Print usage.") }
63
>
}
64
>
},
65
>
'serve-web': {
66
>
type: 'subcommand',
67
>
description: 'Run a server that displays the editor UI in browsers.',
68
>
options: {
69
>
'cli-data-dir': { type: 'string', args: 'dir', description: localize('cliDataDir', "Directory where CLI metadata should be stored.") },
70
>
'disable-telemetry': { type: 'boolean' },
71
>
'telemetry-level': { type: 'string' },
72
>
}
73
>
},
74
>
'agent': {
75
>
type: 'subcommand',
76
>
description: 'Start and interact with AI agent hosts.',
77
>
options: {
78
>
'cli-data-dir': { type: 'string', args: 'dir', description: localize('cliDataDir', "Directory where CLI metadata should be stored.") },
79
>
'disable-telemetry': { type: 'boolean' },
80
>
'telemetry-level': { type: 'string' },
81
>
}
82
>
},
83
>
'tunnel': {
84
>
type: 'subcommand',
85
>
description: 'Make the current machine accessible from vscode.dev or other machines through a secure tunnel.',
86
>
options: {
87
>
'cli-data-dir': { type: 'string', args: 'dir', description: localize('cliDataDir', "Directory where CLI metadata should be stored.") },
88
>
'disable-telemetry': { type: 'boolean' },
89
>
'telemetry-level': { type: 'string' },
90
>
user: {
91
>
type: 'subcommand',
92
>
options: {
93
>
login: {
94
>
type: 'subcommand',
95
>
options: {
96
>
provider: { type: 'string' },
97
>
'access-token': { type: 'string' }
98
>
}
99
>
}
100
>
}
101
>
}
102
>
}
103
>
},
104
>
'diff': { type: 'boolean', cat: 'o', alias: 'd', args: ['file', 'file'], description: localize('diff', "Compare two files with each other.") },
105
>
'merge': { type: 'boolean', cat: 'o', alias: 'm', args: ['path1', 'path2', 'base', 'result'], description: localize('merge', "Perform a three-way merge by providing paths for two modified versions of a file, the common origin of both modified versions and the output file to save merge results.") },
106
>
'add': { type: 'boolean', cat: 'o', alias: 'a', args: 'folder', description: localize('add', "Add folder(s) to the last active window.") },
107
>
'remove': { type: 'boolean', cat: 'o', args: 'folder', description: localize('remove', "Remove folder(s) from the last active window.") },
108
>
'goto': { type: 'boolean', cat: 'o', alias: 'g', args: 'file:line[:character]', description: localize('goto', "Open a file at the path on the specified line and character position.") },
109
>
'new-window': { type: 'boolean', cat: 'o', alias: 'n', description: localize('newWindow', "Force to open a new window.") },
110
>
'reuse-window': { type: 'boolean', cat: 'o', alias: 'r', description: localize('reuseWindow', "Force to open a file or folder in an already opened window.") },
111
>
'agents': { type: 'boolean', cat: 'o', deprecates: ['sessions'], description: localize('agents', "Opens the agents window.") },
112
>
'wait': { type: 'boolean', cat: 'o', alias: 'w', description: localize('wait', "Wait for the files to be closed before returning.") },
113
>
'waitMarkerFilePath': { type: 'string' },
114
>
'locale': { type: 'string', cat: 'o', args: 'locale', description: localize('locale', "The locale to use (e.g. en-US or zh-TW).") },
115
>
'user-data-dir': { type: 'string', cat: 'o', args: 'dir', description: localize('userDataDir', "Specifies the directory that user data is kept in. Can be used to open multiple distinct instances of Code.") },
116
>
'profile': { type: 'string', 'cat': 'o', args: 'profileName', description: localize('profileName', "Opens the provided folder or workspace with the given profile and associates the profile with the workspace. If the profile does not exist, a new empty one is created.") },
117
>
'help': { type: 'boolean', cat: 'o', alias: 'h', description: localize('help', "Print usage.") },
118
>
119
>
'extensions-dir': { type: 'string', deprecates: ['extensionHomePath'], cat: 'e', args: 'dir', description: localize('extensionHomePath', "Set the root path for extensions.") },
120
>
'extensions-download-dir': { type: 'string' },
121
>
'builtin-extensions-dir': { type: 'string' },
122
>
'shared-data-dir': { type: 'string' },
123
>
'list-extensions': { type: 'boolean', cat: 'e', description: localize('listExtensions', "List the installed extensions.") },
124
>
'agent-plugins-dir': { type: 'string' },
125
>
'agents-user-data-dir': { type: 'string' },
126
>
'agents-extensions-dir': { type: 'string' },
127
>
'show-versions': { type: 'boolean', cat: 'e', description: localize('showVersions', "Show versions of installed extensions, when using --list-extensions.") },
128
>
'category': { type: 'string', allowEmptyValue: true, cat: 'e', description: localize('category', "Filters installed extensions by provided category, when using --list-extensions."), args: 'category' },
129
>
'install-extension': { type: 'string[]', cat: 'e', args: 'ext-id | path', description: localize('installExtension', "Installs or updates an extension. The argument is either an extension id or a path to a VSIX. The identifier of an extension is '${publisher}.${name}'. Use '--force' argument to update to latest version. To install a specific version provide '@${version}'. For example: '[email protected]'.") },
130
>
'pre-release': { type: 'boolean', cat: 'e', description: localize('install prerelease', "Installs the pre-release version of the extension, when using --install-extension") },
131
>
'uninstall-extension': { type: 'string[]', cat: 'e', args: 'ext-id', description: localize('uninstallExtension', "Uninstalls an extension.") },
132
>
'update-extensions': { type: 'boolean', cat: 'e', description: localize('updateExtensions', "Update the installed extensions.") },
133
>
'enable-proposed-api': { type: 'string[]', allowEmptyValue: true, cat: 'e', args: 'ext-id', description: localize('experimentalApis', "Enables proposed API features for extensions. Can receive one or more extension IDs to enable individually.") },
134
>
135
>
'add-mcp': { type: 'string[]', cat: 'm', args: 'json', description: localize('addMcp', "Adds a Model Context Protocol server definition to the user profile. Accepts JSON input in the form '{\"name\":\"server-name\",\"command\":...}'") },
136
>
137
>
'version': { type: 'boolean', cat: 't', alias: 'v', description: localize('version', "Print version.") },
138
>
'verbose': { type: 'boolean', cat: 't', global: true, description: localize('verbose', "Print verbose output (implies --wait).") },
139
>
'log': { type: 'string[]', cat: 't', args: 'level', global: true, description: localize('log', "Log level to use. Default is 'info'. Allowed values are 'critical', 'error', 'warn', 'info', 'debug', 'trace', 'off'. You can also configure the log level of an extension by passing extension id and log level in the following format: '${publisher}.${name}:${logLevel}'. For example: 'vscode.csharp:trace'. Can receive one or more such entries.") },
140
>
'status': { type: 'boolean', alias: 's', cat: 't', description: localize('status', "Print process usage and diagnostics information.") },
141
>
'prof-startup': { type: 'boolean', cat: 't', description: localize('prof-startup', "Run CPU profiler during startup.") },
142
>
'prof-append-timers': { type: 'string' },
143
>
'prof-duration-markers': { type: 'string[]' },
144
>
'prof-duration-markers-file': { type: 'string' },
145
>
'no-cached-data': { type: 'boolean' },
146
>
'prof-startup-prefix': { type: 'string' },
147
>
'prof-v8-extensions': { type: 'boolean' },
148
>
'disable-extensions': { type: 'boolean', deprecates: ['disableExtensions'], cat: 't', description: localize('disableExtensions', "Disable all installed extensions. This option is not persisted and is effective only when the command opens a new window.") },
149
>
'disable-extension': { type: 'string[]', cat: 't', args: 'ext-id', description: localize('disableExtension', "Disable the provided extension. This option is not persisted and is effective only when the command opens a new window.") },
150
>
'sync': { type: 'string', cat: 't', description: localize('turn sync', "Turn sync on or off."), args: ['on | off'] },
151
>
152
>
'inspect-extensions': { type: 'string', allowEmptyValue: true, deprecates: ['debugPluginHost'], args: 'port', cat: 't', description: localize('inspect-extensions', "Allow debugging and profiling of extensions. Check the developer tools for the connection URI.") },
153
>
'inspect-brk-extensions': { type: 'string', allowEmptyValue: true, deprecates: ['debugBrkPluginHost'], args: 'port', cat: 't', description: localize('inspect-brk-extensions', "Allow debugging and profiling of extensions with the extension host being paused after start. Check the developer tools for the connection URI.") },
154
>
'disable-lcd-text': { type: 'boolean', cat: 't', description: localize('disableLCDText', "Disable LCD font rendering.") },
155
>
'disable-gpu': { type: 'boolean', cat: 't', description: localize('disableGPU', "Disable GPU hardware acceleration.") },
156
>
'disable-chromium-sandbox': { type: 'boolean', cat: 't', description: localize('disableChromiumSandbox', "Use this option only when there is requirement to launch the application as sudo user on Linux or when running as an elevated user in an applocker environment on Windows.") },
157
>
'sandbox': { type: 'boolean' },
158
>
'locate-shell-integration-path': { type: 'string', cat: 't', args: ['shell'], description: localize('locateShellIntegrationPath', "Print the path to a terminal shell integration script. Allowed values are 'bash', 'pwsh', 'zsh' or 'fish'.") },
159
>
'telemetry': { type: 'boolean', cat: 't', description: localize('telemetry', "Shows all telemetry events which VS code collects.") },
160
>
161
>
'remote': { type: 'string', allowEmptyValue: true },
162
>
'folder-uri': { type: 'string[]', cat: 'o', args: 'uri' },
163
>
'file-uri': { type: 'string[]', cat: 'o', args: 'uri' },
164
>
165
>
'locate-extension': { type: 'string[]' },
166
>
'extensionDevelopmentPath': { type: 'string[]' },
167
>
'extensionDevelopmentKind': { type: 'string[]' },
168
>
'extensionTestsPath': { type: 'string' },
169
>
'extensionEnvironment': { type: 'string' },
170
>
'debugId': { type: 'string' },
171
>
'debugRenderer': { type: 'boolean' },
172
>
'inspect-ptyhost': { type: 'string', allowEmptyValue: true },
173
>
'inspect-brk-ptyhost': { type: 'string', allowEmptyValue: true },
174
>
'inspect-agenthost': { type: 'string', allowEmptyValue: true },
175
>
'inspect-brk-agenthost': { type: 'string', allowEmptyValue: true },
176
>
'inspect-sharedprocess': { type: 'string', allowEmptyValue: true },
177
>
'inspect-brk-sharedprocess': { type: 'string', allowEmptyValue: true },
178
>
'export-default-configuration': { type: 'string' },
179
>
'export-policy-data': { type: 'string', allowEmptyValue: true },
180
>
'export-default-keybindings': { type: 'string', allowEmptyValue: true },
181
>
'install-source': { type: 'string' },
182
>
'enable-smoke-test-driver': { type: 'boolean' },
183
>
'skip-sessions-welcome': { type: 'boolean' },
184
>
'logExtensionHostCommunication': { type: 'boolean' },
185
>
'skip-release-notes': { type: 'boolean' },
186
>
'skip-welcome': { type: 'boolean' },
187
>
'disable-telemetry': { type: 'boolean' },
188
>
'disable-updates': { type: 'boolean' },
189
>
'share-secrets-with-agents-app': { type: 'boolean' },
190
>
'transient': { type: 'boolean', cat: 't', description: localize('transient', "Run with temporary data and extension directories, as if launched for the first time.") },
191
>
'use-inmemory-secretstorage': { type: 'boolean', deprecates: ['disable-keytar'] },
192
>
'password-store': { type: 'string' },
193
>
'disable-workspace-trust': { type: 'boolean' },
194
>
'disable-crash-reporter': { type: 'boolean' },
195
>
'crash-reporter-directory': { type: 'string' },
196
>
'crash-reporter-id': { type: 'string' },
197
>
'skip-add-to-recently-opened': { type: 'boolean' },
198
>
'open-url': { type: 'boolean' },
199
>
'file-write': { type: 'boolean' },
200
>
'file-chmod': { type: 'boolean' },
201
>
'install-builtin-extension': { type: 'string[]' },
202
>
'force': { type: 'boolean' },
203
>
'do-not-sync': { type: 'boolean' },
204
>
'do-not-include-pack-dependencies': { type: 'boolean' },
205
>
'trace': { type: 'boolean' },
206
>
'trace-memory-infra': { type: 'boolean' },
207
>
'trace-category-filter': { type: 'string' },
208
>
'trace-options': { type: 'string' },
209
>
'preserve-env': { type: 'boolean' },
210
>
'force-user-env': { type: 'boolean' },
211
>
'force-disable-user-env': { type: 'boolean' },
212
>
'open-devtools': { type: 'boolean' },
213
>
'disable-gpu-sandbox': { type: 'boolean' },
214
>
'logsPath': { type: 'string' },
215
>
'__enable-file-policy': { type: 'boolean' },
216
>
'editSessionId': { type: 'string' },
217
>
'continueOn': { type: 'string' },
218
>
'enable-coi': { type: 'boolean' },
219
>
'unresponsive-sample-interval': { type: 'string' },
220
>
'unresponsive-sample-period': { type: 'string' },
221
>
'enable-rdp-display-tracking': { type: 'boolean' },
222
>
'disable-layout-restore': { type: 'boolean' },
223
>
'disable-experiments': { type: 'boolean' },
224
>
225
>
// chromium flags
226
>
'no-proxy-server': { type: 'boolean' },
227
>
// Minimist incorrectly parses keys that start with `--no`
228
>
// https://github.com/substack/minimist/blob/aeb3e27dae0412de5c0494e9563a5f10c82cc7a9/index.js#L118-L121
229
>
// If --no-sandbox is passed via cli wrapper it will be treated as --sandbox which is incorrect, we use
230
>
// the alias here to make sure --no-sandbox is always respected.
231
>
// For https://github.com/microsoft/vscode/issues/128279
232
>
'no-sandbox': { type: 'boolean', alias: 'sandbox' },
233
>
'proxy-server': { type: 'string' },
234
>
'proxy-bypass-list': { type: 'string' },
235
>
'proxy-pac-url': { type: 'string' },
236
>
'js-flags': { type: 'string' }, // chrome js flags
237
>
'inspect': { type: 'string', allowEmptyValue: true },
238
>
'inspect-brk': { type: 'string', allowEmptyValue: true },
239
>
'nolazy': { type: 'boolean' }, // node inspect
240
>
'force-device-scale-factor': { type: 'string' },
241
>
'force-renderer-accessibility': { type: 'boolean' },
242
>
'ignore-certificate-errors': { type: 'boolean' },
243
>
'allow-insecure-localhost': { type: 'boolean' },
244
>
'log-net-log': { type: 'string' },
245
>
'vmodule': { type: 'string' },
246
>
'_urls': { type: 'string[]' },
247
>
'disable-dev-shm-usage': { type: 'boolean' },
248
>
'profile-temp': { type: 'boolean' },
249
>
'ozone-platform': { type: 'string' },
250
>
'enable-tracing': { type: 'string' },
251
>
'trace-startup-format': { type: 'string' },
252
>
'trace-startup-file': { type: 'string' },
253
>
'trace-startup-duration': { type: 'string' },
254
>
'xdg-portal-required-version': { type: 'string' },
255
>
256
>
_: { type: 'string[]' } // main arguments
257
>
};
258
>
259
>
export interface ErrorReporter {
260
>
onUnknownOption(id: string): void;
261
>
onMultipleValues(id: string, usedValue: string): void;
262
>
onEmptyValue(id: string): void;
263
>
onDeprecatedOption(deprecatedId: string, message: string): void;
264
>
265
>
getSubcommandReporter?(command: string): ErrorReporter;
266
>
}
267
>
268
>
const ignoringReporter = {
269
>
onUnknownOption: () => { },
270
>
onMultipleValues: () => { },
271
>
onEmptyValue: () => { },
272
>
onDeprecatedOption: () => { }
273
>
};
274
>
275
>
export function parseArgs<T>(args: string[], options: OptionDescriptions<T>, errorReporter: ErrorReporter = ignoringReporter): T {
276
// Find the first non-option arg, which also isn't the value for a previous `--flag`
277
const firstPossibleCommand = args.find((a, i) => a.length > 0 && a[0] !== '-' && options.hasOwnProperty(a) && options[a as T].type === 'subcommand');