Skip to content

Commit 8322bb9

Browse files
michaeltlombardimichaeltlombardi
committed
(DOCS) Update CLI reference for v3.0.0
1 parent 4a94c59 commit 8322bb9

File tree

16 files changed

+1244
-633
lines changed

16 files changed

+1244
-633
lines changed

Diff for: ‎docs/reference/cli/completer/command.md

+18-13
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
description: Command line reference for the 'dsc completer' command
3-
ms.date: 01/17/2024
3+
ms.date: 3/05/2025
44
ms.topic: reference
55
title: dsc completer
66
---
@@ -78,27 +78,32 @@ shell the application returns a completion script for:
7878
- `zsh` - [Z SHell (ZSH)][05]
7979

8080
```yaml
81-
Type: String
82-
Mandatory: true
83-
ValidValues: [
84-
bash,
85-
elvish,
86-
fish,
87-
powershell,
88-
zsh,
89-
]
81+
Type : string
82+
Mandatory : true
83+
ValidValues : [
84+
bash,
85+
elvish,
86+
fish,
87+
powershell,
88+
zsh,
89+
]
9090
```
9191
9292
## Options
9393
9494
### -h, --help
9595
96+
<a id="-h"></a>
97+
<a id="--help"></a>
98+
9699
Displays the help for the current command or subcommand. When you specify this option, the
97-
application ignores all options and arguments after this one.
100+
application ignores all other options and arguments.
98101
99102
```yaml
100-
Type: Boolean
101-
Mandatory: false
103+
Type : boolean
104+
Mandatory : false
105+
LongSyntax : --help
106+
ShortSyntax : -h
102107
```
103108
104109
[01]: https://www.gnu.org/software/bash/

Diff for: ‎docs/reference/cli/config/command.md

+50-12
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
description: Command line reference for the 'dsc config' command
3-
ms.date: 02/05/2024
3+
ms.date: 3/05/2025
44
ms.topic: reference
55
title: dsc config
66
---
@@ -64,6 +64,9 @@ information. For example, `dsc config --help` or `dsc config set --help`.
6464

6565
### -f, --parameters_file
6666

67+
<a id="-f"></a>
68+
<a id="--parameters-file"></a>
69+
6770
Specifies the path to a data file containing the parameters to pass to the configuration as JSON or
6871
YAML. When you specify this option, DSC interprets the keys in the data file as parameters and uses
6972
the specified values. The values in the data file override any defaults defined in the
@@ -73,39 +76,74 @@ The data file must contain an object with the `parameters` key. The value of the
7376
must be an object where each key is the name of a defined parameter and each value is a valid value
7477
for that parameter.
7578

76-
This option can't be used with the `--parameters` option. Choose whether to pass the parameters as
77-
a data string with the `--parameters` option or in a data file with the `--parameters_file` option.
79+
This option is mutually exclusive with the `--parameters` option.
7880

7981
For more information about defining parameters in a configuration document, see
8082
[DSC Configuration document parameter schema][06]. For more information about using parameters in
8183
configuration document, see the [parameters function reference][07].
8284

85+
```yaml
86+
Type : string
87+
Mandatory : false
88+
LongSyntax : --parameters-file <PARAMETERS_FILE>
89+
ShortSyntax : -f <PARAMETERS_FILE>
90+
```
91+
8392
### -p, --parameters
8493
85-
Specifies the parameters to pass to the configuration as a JSON or YAML string. When you specify
86-
this option, DSC interprets the keys in the data string as parameters and uses the specified
87-
values. The values in the data string override any defaults defined in the configuration itself.
94+
<a id="-p"></a>
95+
<a id="--parameters"></a>
96+
97+
Specifies the parameters to pass to the configuration document as a string of data formatted as
98+
JSON or YAML. When you specify this option, DSC interprets the keys in the data string as
99+
parameters and uses the specified values. The values in the data string override any defaults
100+
defined in the configuration document itself.
88101
89102
The data string must contain an object with the `parameters` key. The value of the `parameters` key
90103
must be an object where each key is the name of a defined parameter and each value is a valid value
91104
for that parameter.
92105

93-
This option can't be used with the `--parameters_file` option. Choose whether to pass the
94-
parameters as a data string with the `--parameters` option or in a data file with the
95-
`--parameters_file` option.
106+
This option is mutually exclusive with the `--parameters_file` option.
96107

97108
For more information about defining parameters in a configuration document, see
98109
[DSC Configuration document parameter schema][06]. For more information about using parameters in
99110
configuration document, see the [parameters function reference][07].
100111

112+
```yaml
113+
Type : string
114+
Mandatory : false
115+
LongSyntax : --parameters <PARAMETERS>
116+
ShortSyntax : -p <PARAMETERS>
117+
```
118+
119+
### -r, --system-root
120+
121+
<a id="-r"></a>
122+
<a id="--system-root"></a>
123+
124+
Use this option to specify the path to the operating system root when you aren't targeting the
125+
current running OS.
126+
127+
```yaml
128+
Type : string
129+
Mandatory : false
130+
LongSyntax : --system-root <SYSTEM_ROOT>
131+
ShortSyntax : -r <SYSTEM_ROOT>
132+
```
133+
101134
### -h, --help
102135

136+
<a id="-h"></a>
137+
<a id="--help"></a>
138+
103139
Displays the help for the current command or subcommand. When you specify this option, the
104-
application ignores all options and arguments after this one.
140+
application ignores all other options and arguments.
105141

106142
```yaml
107-
Type: Boolean
108-
Mandatory: false
143+
Type : boolean
144+
Mandatory : false
145+
LongSyntax : --help
146+
ShortSyntax : -h
109147
```
110148

111149
## Environment variables

Diff for: ‎docs/reference/cli/config/export.md

+134-41
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
description: Command line reference for the 'dsc config export' command
3-
ms.date: 09/06/2023
3+
ms.date: 3/05/2025
44
ms.topic: reference
55
title: dsc config export
66
---
@@ -13,33 +13,33 @@ Generates a configuration document that defines the existing instances of a set
1313

1414
## Syntax
1515

16-
### Configuration document from stdin
16+
### Configuration document from file
1717

1818
```sh
19-
<document-string> | dsc config export [Options]
19+
dsc config export [Options] --file <FILE>
2020
```
2121

2222
### Configuration document from option string
2323

2424
```sh
25-
dsc config export [Options] --document <document-string>
25+
dsc config export [Options] --input <INPUT>
2626
```
2727

28-
### Configuration document from file
28+
### Configuration document from stdin
2929

3030
```sh
31-
dsc config export [Options] --path <document-filepath>
31+
cat <FILE> | dsc config export [Options] --file -
3232
```
3333

3434
## Description
3535

3636
The `export` subcommand generates a configuration document that includes every instance of a set of
3737
resources.
3838

39-
The configuration document must be passed to this command as JSON or YAML over stdin, as a string
40-
with the **document** option, or from a file with the **path** option.
39+
The configuration document must be passed to this command as JSON or YAML with the `--input` or
40+
`--file` option.
4141

42-
The input configuration defines the resources to export. DSC ignores any properties specified for
42+
The input document defines the resources to export. DSC ignores any properties specified for
4343
the resources in the input configuration for the operation, but the input document and any
4444
properties for resource instances must still validate against the configuration document and
4545
resource instance schemas.
@@ -49,65 +49,158 @@ configuration. Only define each resource type once. If the configuration documen
4949
resource instance where the resource type isn't exportable or has already been declared in the
5050
configuration, DSC raises an error.
5151

52+
## Examples
53+
54+
### Example 1 - Test whether a configuration's resource instances are in the desired state
55+
56+
<a id="example-1"></a>
57+
58+
The command inspects the system to return a configuration document containing every discovered
59+
instance of the resources defined in the configuration document saved as `example.dsc.config.yaml`.
60+
It passes the configuration document to the command from stdin using the `--file` option.
61+
62+
```yaml
63+
# example.dsc.config.yaml
64+
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
65+
resources:
66+
- name: Operating system information
67+
type: Microsoft/OSInfo
68+
properties: {}
69+
- name: Processes
70+
type: Microsoft/Process
71+
properties: {}
72+
```
73+
74+
```sh
75+
cat ./example.dsc.config.yaml | dsc config export --file -
76+
```
77+
78+
### Example 2 - Passing a file to read as the configuration document
79+
80+
<a id="example-2"></a>
81+
82+
The command uses the `--file` option to export resources from the configuration defined in the
83+
`example.dsc.config.yaml` file.
84+
85+
```sh
86+
dsc config export --file ./example.dsc.config.yaml
87+
```
88+
89+
### Example 3 - Passing a configuration document as a variable
90+
91+
<a id="example-3"></a>
92+
93+
The command uses the `--input` option to exoirt resources from the configuration stored in the
94+
`$desired` variable.
95+
96+
```sh
97+
dsc config export --input $desired
98+
```
99+
52100
## Options
53101

54-
### -d, --document
102+
### -i, --input
103+
104+
<a id="-i"></a>
105+
<a id="--input"></a>
106+
107+
Specifies the configuration document to validate state for.
55108

56-
Specifies the configuration document to export from as a JSON or YAML object. DSC validates the
57-
document against the configuration document schema. If the validation fails, DSC raises an error.
109+
The document must be a string containing a JSON or YAML object. DSC validates the document against
110+
the configuration document schema. If the validation fails, DSC raises an error.
58111

59-
This option can't be used with configuration document over stdin or the `--path` option. Choose
60-
whether to pass the configuration document to the command over stdin, from a file with the `--path`
61-
option, or with the `--document` option.
112+
This option is mutually exclusive with the `--file` option.
62113

63114
```yaml
64-
Type: String
65-
Mandatory: false
115+
Type : string
116+
Mandatory : false
117+
LongSyntax : --input <INPUT>
118+
ShortSyntax : -i <INPUT>
66119
```
67120
68-
### -p, --path
121+
### -f, --file
122+
123+
<a id="-f"></a>
124+
<a id="--file"></a>
125+
126+
Defines the path to a configuration document to validate state for.
69127
70-
Defines the path to a configuration document to export instead of piping the document from stdin or
71-
passing it as a string with the `--document` option. The specified file must contain a
72-
configuration document as a JSON or YAML object. DSC validates the document against the
73-
configuration document schema. If the validation fails, or if the specified file doesn't exist, DSC
74-
raises an error.
128+
The specified file must contain a configuration document as a JSON or YAML object. DSC validates
129+
the document against the configuration document schema. If the validation fails, or if the
130+
specified file doesn't exist, DSC raises an error.
75131
76-
This option is mutually exclusive with the `--document` option. When you use this option, DSC
77-
ignores any input from stdin.
132+
You can also use this option to pass a configuration document from stdin, as shown in
133+
[Example 1](#example-1).
134+
135+
This option is mutually exclusive with the `--input` option.
78136

79137
```yaml
80-
Type: String
81-
Mandatory: false
138+
Type : string
139+
Mandatory : false
140+
LongSyntax : --file <FILE>
141+
ShortSyntax : -f <FILE>
82142
```
83143

84-
### -f, --format
144+
### -o, --output-format
145+
146+
<a id="-o"></a>
147+
<a id="--output-format"></a>
148+
149+
The `--output-format` option controls which format DSC uses for the data the command returns. The
150+
available formats are:
151+
152+
- `json` to emit the data as a [JSON Line][02].
153+
- `pretty-json` to emit the data as JSON with newlines, indentation, and spaces for readability.
154+
- `yaml` to emit the data as YAML.
155+
156+
The default output format depends on whether DSC detects that the output is being redirected or
157+
captured as a variable:
85158

86-
The `--format` option controls the console output format for the command. If the command output is
87-
redirected or captured as a variable, the output is always JSON.
159+
- If the command isn't being redirected or captured, DSC displays the output as the `yaml` format
160+
in the console.
161+
- If the command output is redirected or captured, DSC emits the data as the `json` format to
162+
stdout.
163+
164+
When you use this option, DSC uses the specified format regardless of whether the command is being
165+
redirected or captured.
166+
167+
When the command isn't redirected or captured, the output in the console is formatted for improved
168+
readability. When the command isn't redirected or captured, the output include terminal sequences
169+
for formatting.
88170

89171
```yaml
90-
Type: String
91-
Mandatory: false
92-
DefaultValue: yaml
93-
ValidValues: [json, pretty-json, yaml]
172+
Type : string
173+
Mandatory : false
174+
ValidValues : [json, pretty-json, yaml]
175+
LongSyntax : --output-format <OUTPUT_FORMAT>
176+
ShortSyntax : -o <OUTPUT_FORMAT>
94177
```
95178

96179
### -h, --help
97180

181+
<a id="-h"></a>
182+
<a id="--help"></a>
183+
98184
Displays the help for the current command or subcommand. When you specify this option, the
99-
application ignores all options and arguments after this one.
185+
application ignores all other options and arguments.
100186

101187
```yaml
102-
Type: Boolean
103-
Mandatory: false
188+
Type : boolean
189+
Mandatory : false
190+
LongSyntax : --help
191+
ShortSyntax : -h
104192
```
105193

106194
## Output
107195

108-
This command returns JSON output that defines a configuration document including every instance of
109-
the resources declared in the input configuration. For more information, see
110-
[DSC Configuration document schema reference][02].
196+
This command returns formatted data that defines a configuration document including every instance
197+
of the resources declared in the input configuration. For more information, see
198+
[DSC Configuration document schema reference][03].
199+
200+
For more information about the formatting of the output data, see the
201+
[--output-format option](#--output-format).
111202

203+
<!-- Link reference definitions -->
112204
[01]: ../../schemas/resource/manifest/export.md
113-
[02]: ../../schemas/config/document.md
205+
[02]: https://jsonlines.org/
206+
[03]: ../../schemas/config/document.md

0 commit comments

Comments
 (0)