unified-args

unified engine to create a command line interface from a unified processor.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • args(options)
  • Options
• CLI
  • Files
  • --color
  • --config
  • --ext <extensions>
  • --file-path <path>
  • --frail
  • --help
  • --ignore
  • --ignore-path <path>
  • --ignore-path-resolve-from cwd|dir
  • --ignore-pattern <globs>
  • --inspect
  • --output [path]
  • --quiet
  • --rc-path <path>
  • --report <reporter>
  • --setting <settings>
  • --silent
  • --silently-ignore
  • --stdout
  • --tree
  • --tree-in
  • --tree-out
  • --use <plugin>
  • --verbose
  • --version
  • --watch
• Diagnostics
• Debugging
• Types
• Compatibility
• Security
• Contribute
• License

What is this?

This package wraps unified-engine so that it can be used to create a command line interface. It’s what you use underneath when you use remark-cli.

When should I use this?

You can use this to let users process multiple files from the command line, letting them configure from the file system.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

1npm install unified-args

Use

The following example creates a CLI for remark, which will search for files in folders with a markdown extension, allows configuration from .remarkrc and package.json files, ignoring files from .remarkignore files, and more.

Say our module example.js looks as follows:

1import {remark} from 'remark'
2import {args} from 'unified-args'
3
4args({
5  description:
6    'Command line interface to inspect and change markdown files with remark',
7  extensions: [
8    'md',
9    'markdown',
10    'mdown',
11    'mkdn',
12    'mkd',
13    'mdwn',
14    'mkdown',
15    'ron'
16  ],
17  ignoreName: '.remarkignore',
18  name: 'remark',
19  packageField: 'remarkConfig',
20  pluginPrefix: 'remark',
21  processor: remark,
22  rcName: '.remarkrc',
23  version: '11.0.0'
24})

…now running node example.js --help yields:

1Usage: remark [options] [path | glob ...]
2
3  Command line interface to inspect and change markdown files with remark
4
5Options:
6
7      --[no-]color                        specify color in report (on by default)
8      --[no-]config                       search for configuration files (on by default)
9  -e  --ext <extensions>                  specify extensions
10  …

API

This package exports the identifier args. There is no default export.

args(options)

Start the CLI.

👉 Note: this takes over the entire process. It parses process.argv, exits when its done, etc.

Parameters

• options (Options, required) — configuration

Returns

Nothing (undefined).

Options

Configuration (TypeScript type).

Fields

• description (string, required) — description of executable
• extensions (Array<string>, required) — default file extensions to include (engine: options.extensions)
• ignoreName (string, required) — name of ignore files to load (engine: options.ignoreName)
• name (string, required) — name of executable
• packageField (string, required) — field where configuration can be found in package.jsons (engine: options.packageField)
• pluginPrefix (string, required) — prefix to use when searching for plugins (engine: options.pluginPrefix)
• processor (Processor, required) — processor to use (engine: options.processor)
• rcName (string, required) — name of configuration files to load (engine: options.rcName)
• version (string, required) — version of executable

CLI

CLIs created with unified-args, such as the example above, have an interface similar to the below:

1Usage: remark [options] [path | glob ...]
2
3  Command line interface to inspect and change markdown files with remark
4
5Options:
6
7      --[no-]color                        specify color in report (on by default)
8      --[no-]config                       search for configuration files (on by default)
9  -e  --ext <extensions>                  specify extensions
10      --file-path <path>                  specify path to process as
11  -f  --frail                             exit with 1 on warnings
12  -h  --help                              output usage information
13      --[no-]ignore                       search for ignore files (on by default)
14  -i  --ignore-path <path>                specify ignore file
15      --ignore-path-resolve-from cwd|dir  resolve patterns in `ignore-path` from its directory or cwd
16      --ignore-pattern <globs>            specify ignore patterns
17      --inspect                           output formatted syntax tree
18  -o  --output [path]                     specify output location
19  -q  --quiet                             output only warnings and errors
20  -r  --rc-path <path>                    specify configuration file
21      --report <reporter>                 specify reporter
22  -s  --setting <settings>                specify settings
23  -S  --silent                            output only errors
24      --silently-ignore                   do not fail when given ignored files
25      --[no-]stdout                       specify writing to stdout (on by default)
26  -t  --tree                              specify input and output as syntax tree
27      --tree-in                           specify input as syntax tree
28      --tree-out                          output syntax tree
29  -u  --use <plugins>                     use plugins
30      --verbose                           report extra info for messages
31  -v  --version                           output version number
32  -w  --watch                             watch for changes and reprocess
33
34Examples:
35
36  # Process `input.md`
37  $ remark input.md -o output.md
38
39  # Pipe
40  $ remark < input.md > output.md
41
42  # Rewrite all applicable files
43  $ remark . -o

Files

All non-options passed to the cli are seen as input and can be:

• paths (readme.txt) and globs (*.txt) pointing to files to load
• paths (test) and globs (fixtures/{in,out}/) pointing to folders, which are searched for files with known extensions which are not ignored by patterns in ignore files. The default behavior is to exclude files in node_modules/ unless explicitly given

You can force things to be seen as input by using --:

1cli -- globs/* and/files

• default: none
• engine: options.files

--color

1cli --no-color input.txt

Whether to output ANSI color codes in the report.

• default: whether the terminal supports color
• engine: options.color

👉 Note: This option may not work depending on the reporter given in --report.

--config

1cli --no-config input.txt

Whether to load configuration files.

Searches for files with the configured rcName: $rcName and $rcName.json (JSON), $rcName.yml and $rcName.yaml (YAML), $rcName.js (JavaScript), $rcName.cjs (CommonJS), and $rcName.mjs (ESM); and looks for the configured packageField in package.json files.

• default: on
• engine: options.detectConfig

--ext <extensions>

1cli --ext html .
2cli --ext htm --ext html .
3cli --ext htm,html .

Specify one or more extensions to include when searching for files.

• default: configured extensions
• alias: -e
• engine: options.extensions

--file-path <path>

1cli --file-path input.txt < input.txt > doc/output.txt

File path to process the given file on stdin(4) as, if any.

• default: none
• engine: options.filePath

--frail

1cli --frail input.txt

Exit with a status code of 1 if warnings or errors occur. The default behavior is to exit with 1 on errors.

• default: off
• alias: -f
• engine: options.frail

--help

1cli --help

Output short usage information.

• default: off
• alias: -h

--ignore

1cli --no-ignore .

Whether to load ignore files.

Searches for files named $ignoreName.

• default: on
• engine: options.detectIgnore

--ignore-path <path>

1cli --ignore-path .gitignore .

File path to an ignore file to load, regardless of --ignore.

• default: none
• alias: -i
• engine: options.ignorePath

--ignore-path-resolve-from cwd|dir

1cli --ignore-path node_modules/my-config/my-ignore --ignore-path-resolve-from cwd .

Resolve patterns in the ignore file from its directory (dir, default) or the current working directory (cwd).

• default: 'dir'
• engine: options.ignorePathResolveFrom

--ignore-pattern <globs>

1cli --ignore-pattern "docs/*.md" .

Additional patterns to use to ignore files.

• default: none
• engine: options.ignorePatterns

--inspect

1cli --inspect < input.txt

Output the transformed syntax tree, formatted with unist-util-inspect. This does not run the compilation phase.

• default: off
• engine: options.inspect

--output [path]

1cli --output -- .
2cli --output doc .
3cli --output doc/output.text input.txt

Whether to write successfully processed files, and where to. Can be set from configuration files.

• if output is not given, files are not written to the file system
• otherwise, if path is not given, files are overwritten when successful
• otherwise, if path points to a folder, files are written there
• otherwise, if one file is processed, the file is written to path

👉 Note: intermediate folders are not created.

• default: off
• alias: -o
• engine: options.output

--quiet

1cli --quiet input.txt

Ignore files without any messages in the report. The default behavior is to show a success message.

• default: off
• alias: -q
• engine: options.quiet

👉 Note: this option may not work depending on the reporter given in --report.

--rc-path <path>

1cli --rc-path config.json .

File path to a configuration file to load, regardless of --config.

• default: none
• alias: -r
• engine: options.rcPath

--report <reporter>

1cli --report ./reporter.js input.txt
2cli --report vfile-reporter-json input.txt
3cli --report json input.txt
4cli --report json=pretty:2 input.txt
5cli --report 'json=pretty:"\t"' input.txt
6# Only last one is used:
7cli --report pretty --report json input.txt

Reporter to load by its name or path, optionally with options, and use to report metadata about every processed file.

To pass options, follow the name by an equals sign (=) and settings, which have the same in syntax as --setting <settings>.

The prefix vfile-reporter- can be omitted. Prefixed reporters are preferred over modules without prefix.

If multiple reporters are given, the last one is used.

• default: none, which uses vfile-reporter
• engine: options.reporter and options.reporterOptions

👉 Note: the quiet, silent, and color options may not work with the used reporter. If they are given, they are preferred over the same properties in reporter settings.

--setting <settings>

1cli --setting alpha:true input.txt
2cli --setting bravo:true --setting '"charlie": "delta"' input.txt
3cli --setting echo-foxtrot:-2 input.txt
4cli --setting 'golf: false, hotel-india: ["juliet", 1]' input.txt

Configuration for the parser and compiler of the processor. Can be set from configuration files.

The given settings are JSON5, with one exception: surrounding braces must not be used. Instead, use JSON syntax without braces, such as "foo": 1, "bar": "baz".

• default: none
• alias: -s
• engine: options.settings

--silent

1cli --silent input.txt

Show only fatal errors in the report. Turns --quiet on.

• default: off
• alias: -S
• engine: options.silent

👉 Note: this option may not work depending on the reporter given in --report.

--silently-ignore

1cli --silently-ignore **/*.md

Skip given files which are ignored by ignore files, instead of warning about them.

• default: off
• engine: options.silentlyIgnore

--stdout

1cli --no-stdout input.txt

Whether to write a processed file to stdout(4).

• default: off if --output or --watch are given, or if multiple files could be processed
• engine: options.out

--tree

1cli --tree < input.json > output.json

Treat input as a syntax tree in JSON and output the transformed syntax tree. This runs neither the parsing nor the compilation phase.

• default: off
• alias: -t
• engine: options.tree

--tree-in

1cli --tree-in < input.json > input.txt

Treat input as a syntax tree in JSON. This does not run the parsing phase.

• default: same as --tree
• engine: options.treeIn

--tree-out

1cli --tree-out < input.txt > output.json

Output the transformed syntax tree. This does not run the compilation phase.

• default: same as --tree
• engine: options.treeOut

--use <plugin>

1cli --use remark-man input.txt
2cli --use man input.txt
3cli --use 'toc=max-depth:3' input.txt
4cli --use ./plugin.js input.txt

Plugin to load by its name or path, optionally with options, and use on every processed file. Can be set from configuration files.

To pass options, follow the plugin by an equals sign (=) and settings, which have the same in syntax as --setting <settings>.

Plugins prefixed with the configured pluginPrefix are preferred over modules without prefix.

• default: none
• alias: -u
• engine: options.plugins

--verbose

1cli --verbose input.txt

Print more info for messages.

• default: off
• engine: options.verbose

👉 Note: this option may not work depending on the reporter given in --report.

--version

1cli --version

Output version number.

• default: off
• alias: -v

--watch

1cli -qwo .

Yields:

1Watching... (press CTRL+C to exit)
2Note: Ignoring `--output` until exit.

Process as normal, then watch found files and reprocess when they change. The watch is stopped when SIGINT is received (usually done by pressing CTRL-C).

If --output is given without path, it is not honored, to prevent an infinite loop. On operating systems other than Windows, when the watch closes, a final process runs including --output.

• default: off
• alias: -w

Diagnostics

CLIs created with unified-args exit with:

• 1 on fatal errors
• 1 on warnings in --frail mode, 0 on warnings otherwise
• 0 on success

Debugging

CLIs can be debugged by setting the DEBUG environment variable to *, such as DEBUG="*" cli example.txt.

Types

This package is fully typed with TypeScript. It export the additional type Options.

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, unified-engine@^11, compatible with Node.js 16.

Security

unified-args loads and evaluates configuration files, plugins, and presets from the file system (often from node_modules/). That means code that is on your file system runs. Make sure you trust the workspace where you run unified-args and be careful with packages from npm and changes made by contributors.

Contribute

See contributing.md in unifiedjs/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer