Adds JSON output mode for the `spfx list-templates` command. Closes #235 by Adam-it · Pull Request #253 · SharePoint/spfx

Adam-it · 2026-04-25T19:56:07Z

Description

The aim is to:

introduce output option for the list-templates command that supports JSON (which will be the default mode) and TEXT.
added --verbose flag and moved some of the information command outputs to be part of the verbose, so that they are not part of stdout but instead are present in stderr

How was this tested?

added new unit tests for the new functionality
checked locally, see the result below with description

Result

Help now also has new --output and --verbose flag

The default output mode of the list-templates command is now JSON, or you may use the --output json as well

text works as before but --output text needs to be used

Command output is part of stdout, and all other messages go to stderr

To see additional info the --verbose option needs to be used

Type of change

Bug fix
New feature / enhancement -> Closes Introduce JSON output mode for the spfx list-templates command #235
Template change
Documentation / CI / governance

Copilot

Pull request overview

Adds a JSON output mode (now the default) for spfx list-templates, and refactors command output so structured results go to stdout while informational output is routed to stderr.

Changes:

Added --output/-o {json,text} to list-templates, defaulting to json
Implemented JSON serialization for template collections (toJsonString()) and updated CLI action to write JSON to stdout
Introduced StderrTerminalProvider and added/updated unit tests + docs/snapshots accordingly

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
common/changes/@microsoft/spfx-cli/json-output-mode_2026-04-25.json	Adds a change record for the CLI package.
apps/spfx-cli/src/utilities/StderrTerminalProvider.ts	New terminal provider intended to route CLI messages to stderr for JSON output scenarios.
apps/spfx-cli/src/utilities/tests/StderrTerminalProvider.test.ts	Unit tests validating stderr routing behavior.
apps/spfx-cli/src/cli/actions/ListTemplatesAction.ts	Adds `--output` option; writes JSON to stdout by default and table output for text mode.
apps/spfx-cli/src/cli/actions/SPFxActionBase.ts	Makes `_terminal` mutable so actions can temporarily swap terminal behavior.
apps/spfx-cli/src/cli/actions/tests/ListTemplatesAction.test.ts	Updates existing tests to force text output; adds JSON-output tests using stdout spying.
apps/spfx-cli/src/cli/test/snapshots/CommandLineHelp.test.ts.snap	Updates help snapshot to include the new `--output` parameter and its description.
apps/spfx-cli/README.md	Documents `--output` and provides examples for JSON (default) and text.
api/spfx-template-api/src/repositories/SPFxTemplateCollection.ts	Adds `toJsonString()` for structured template list serialization.
api/spfx-template-api/src/repositories/test/SPFxTemplateCollection.test.ts	Adds unit tests for `toJsonString()`.
api/spfx-template-api/src/repositories/test/snapshots/SPFxTemplateCollection.test.ts.snap	Snapshot for JSON serialization formatting.
api/spfx-template-api/etc/spfx-template-api.api.md	API report update to include `toJsonString()`.
api/spfx-template-api/README.md	Updates docs to mention JSON/table output helpers.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

apps/spfx-cli/README.md:81

The spfx list-templates docs list the new --output option, but the command also now supports --verbose (and help output advertises it). The README’s optional flags table should include --verbose and clarify that verbose/info messages are written to stderr (especially important with JSON output).

### Optional flags

| Flag | Default | Description |
|------|---------|-------------|
| `-o`, `--output {json,text}` | `json` | Output format. `json` writes machine-readable JSON to stdout (informational messages go to stderr). `text` writes a human-readable table |
| `--spfx-version VERSION` | `version/latest` branch | Branch/tag in the default template repo to use (e.g. `1.22`, `1.23-rc.0`) |
| `--template-url URL` | `https://github.com/SharePoint/spfx` | Custom GitHub template repository (default source) |
| `--local-source PATH` | — | Path to a local template folder to include (repeatable) |
| `--remote-source URL` | — | Additional public GitHub repo to include as a template source (repeatable) |

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

iclanton · 2026-06-03T22:34:32Z

 Array [
-  "[    log] Using GitHub template source: https://github.com/SharePoint/spfx[n]",
-  "[    log] Adding local template source: /path/to/templates[n]",
+  "[verbose] Using GitHub template source: https://github.com/SharePoint/spfx[n]",


Unrelated change?

Those are related. Please check the changes done in apps/spfx-cli/src/cli/actions/SPFxActionBase.ts. Those two messages are now output using writeVerboseLine

iclanton · 2026-06-03T22:37:30Z

+        'Output format. "json" writes machine-readable JSON to stdout (informational ' +
+        'messages go to stderr). "text" writes a human-readable table.',


Generally avoid printing non-erroneous data to stderr. In JSON mode, why not just not output anything that can't be JSON-parsed?

but if we avoid any other output (like verbose or debug or other) in the stderr then for json output mode it will be really hard to debug what the CLI is doing when using --verbose option, right?

iclanton · 2026-06-03T22:37:56Z

      terminal
    );
+
+    this._outputParameter = this.defineChoiceParameter({


Consider making this a --json flag instead.

I would strongly recommend adding a universal --output option in which we may specify the output type of the command we want to use. For example, what if in the near future we would like to add a --csv output mode with is better for reporting and for LLMs when used for very large collections. Or maybe we could like to add an md output mode to be even more friendly for humans.
What do you think?

Adam-it · 2026-06-07T21:18:55Z

@iclanton thanks for the review 👍. You Rock 🤩
I added a few replies and clarifications for your feedback. Please recheck my comments before I make any unnecessary changes in code 🙂, I think some are really worth reconsidering

Adam-it · 2026-06-12T22:52:44Z

@iclanton did you have a chance to take a look at my responses? I think it would be cool to start moving this PR forward

Copilot

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

apps/spfx-cli/README.md:80

The CLI now exposes a --verbose flag (shown in the generated --help output), but the spfx list-templates README section doesn’t document it in the Optional flags table. This makes the README inconsistent with the actual CLI surface area.

### Optional flags

| Flag | Default | Description |
|------|---------|-------------|
| `-o`, `--output {json,text}` | `json` | Output format. `json` writes machine-readable JSON to stdout (informational messages go to stderr). `text` writes a human-readable table |
| `--spfx-version VERSION` | `version/latest` branch | Branch/tag in the default template repo to use (e.g. `1.22`, `1.23-rc.0`) |
| `--template-url URL` | `https://github.com/SharePoint/spfx` | Custom GitHub template repository (default source) |
| `--local-source PATH` | — | Path to a local template folder to include (repeatable) |
| `--remote-source URL` | — | Additional public GitHub repo to include as a template source (repeatable) |

Copilot

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

apps/spfx-cli/README.md:80

--verbose is now supported (and shown in --help), but it isn’t documented in the spfx list-templates optional flags table. This makes it easy to miss how to surface the source-registration messages when needed.

| Flag | Default | Description |
|------|---------|-------------|
| `-o`, `--output {json,text}` | `json` | Output format. `json` writes machine-readable JSON to stdout (informational messages go to stderr). `text` writes a human-readable table |
| `--spfx-version VERSION` | `version/latest` branch | Branch/tag in the default template repo to use (e.g. `1.22`, `1.23-rc.0`) |
| `--template-url URL` | `https://github.com/SharePoint/spfx` | Custom GitHub template repository (default source) |
| `--local-source PATH` | — | Path to a local template folder to include (repeatable) |
| `--remote-source URL` | — | Additional public GitHub repo to include as a template source (repeatable) |

+const verboseEnabled: boolean = process.argv.includes('--verbose');
+const terminal: Terminal = new Terminal(new ConsoleTerminalProvider({ verboseEnabled }));


Adam-it · 2026-06-26T22:03:29Z

@iclanton I fixed up the review comments to which I did not have any response. Please recheck also some of my comments to your feedback

Copilot AI review requested due to automatic review settings April 25, 2026 19:56

Copilot started reviewing on behalf of Adam-it April 25, 2026 19:56 View session

Copilot AI reviewed Apr 25, 2026

View reviewed changes

Comment thread apps/spfx-cli/src/cli/actions/ListTemplatesAction.ts Outdated

Comment thread apps/spfx-cli/src/utilities/StderrTerminalProvider.ts Outdated

Comment thread apps/spfx-cli/src/cli/actions/tests/ListTemplatesAction.test.ts Outdated

Adam-it marked this pull request as draft April 25, 2026 20:48

Adam-it force-pushed the adds-json-output-mode branch from 26860dd to 65b297d Compare April 25, 2026 21:37

Adam-it marked this pull request as ready for review April 25, 2026 21:38

Copilot AI review requested due to automatic review settings April 25, 2026 21:38

Copilot started reviewing on behalf of Adam-it April 25, 2026 21:39 View session

Copilot AI reviewed Apr 25, 2026

View reviewed changes

Comment thread apps/spfx-cli/src/cli/actions/ListTemplatesAction.ts Outdated

Adam-it force-pushed the adds-json-output-mode branch from 9e88690 to 77d8b1c Compare April 25, 2026 21:57

iclanton reviewed Jun 3, 2026

View reviewed changes

Adam-it mentioned this pull request Jun 12, 2026

Refactor the /new chat command to a dedicated SPFx new project LM tool pnp/vscode-viva#707

Open

Copilot AI review requested due to automatic review settings June 26, 2026 21:26

Adam-it force-pushed the adds-json-output-mode branch from 77d8b1c to 1d11338 Compare June 26, 2026 21:26

Copilot started reviewing on behalf of Adam-it June 26, 2026 21:27 View session

Adds json output mode for list templates command

377b7d7

Adam-it force-pushed the adds-json-output-mode branch from 1d11338 to 377b7d7 Compare June 26, 2026 21:31

Copilot AI reviewed Jun 26, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings June 26, 2026 21:31

Copilot started reviewing on behalf of Adam-it June 26, 2026 21:32 View session

Copilot AI reviewed Jun 26, 2026

View reviewed changes

Comment thread apps/spfx-cli/src/start.ts

Comment on lines +8 to +9

const verboseEnabled: boolean = process.argv.includes('--verbose');

const terminal: Terminal = new Terminal(new ConsoleTerminalProvider({ verboseEnabled }));

Addresses review comments

cc66e0b

		'Output format. "json" writes machine-readable JSON to stdout (informational ' +
		'messages go to stderr). "text" writes a human-readable table.',

		const verboseEnabled: boolean = process.argv.includes('--verbose');
		const terminal: Terminal = new Terminal(new ConsoleTerminalProvider({ verboseEnabled }));

Uh oh!

Conversation

Adam-it commented Apr 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

How was this tested?

Result

Type of change

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

iclanton Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

Adam-it Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

iclanton Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

Adam-it Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

iclanton Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

Adam-it Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

Adam-it commented Jun 7, 2026

Uh oh!

Adam-it commented Jun 12, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Adam-it commented Jun 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Adam-it commented Apr 25, 2026 •

edited

Loading