unified-args
!Buildbuild-badgebuild
!Coveragecoverage-badgecoverage
!Downloadsdownloads-badgedownloads
!Sponsorssponsors-badgecollective
!Backersbackers-badgecollective
!Chatchat-badgechatunified engine to create a command line interface from a unified processor.
Contents
* [`args(options)`](#argsoptions)
* [`Options`](#options)
* [Files](#files)
* [`--color`](#--color)
* [`--config`](#--config)
* [`--ext <extensions>`](#--ext-extensions)
* [`--file-path <path>`](#--file-path-path)
* [`--frail`](#--frail)
* [`--help`](#--help)
* [`--ignore`](#--ignore)
* [`--ignore-path <path>`](#--ignore-path-path)
* [`--ignore-path-resolve-from cwd|dir`](#--ignore-path-resolve-from-cwddir)
* [`--ignore-pattern <globs>`](#--ignore-pattern-globs)
* [`--inspect`](#--inspect)
* [`--output [path]`](#--output-path)
* [`--quiet`](#--quiet)
* [`--rc-path <path>`](#--rc-path-path)
* [`--report <reporter>`](#--report-reporter)
* [`--setting <settings>`](#--setting-settings)
* [`--silent`](#--silent)
* [`--silently-ignore`](#--silently-ignore)
* [`--stdout`](#--stdout)
* [`--tree`](#--tree)
* [`--tree-in`](#--tree-in)
* [`--tree-out`](#--tree-out)
* [`--use <plugin>`](#--use-plugin)
* [`--verbose`](#--verbose)
* [`--version`](#--version)
* [`--watch`](#--watch)
What is this?
This package wrapsunified-engine
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
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 onlyesm. In Node.js (version 16+), install with npm:npm install unified-args
Use
The following example creates a CLI for remark, which will search for files in folders with a markdown extension, allows configurationconfig-file from.remarkrc
and package.json
files, ignoring filesignore-file from
.remarkignore
files, and more.Say our module
example.js
looks as follows:import {remark} from 'remark'
import {args} from 'unified-args'
args({
description:
'Command line interface to inspect and change markdown files with remark',
extensions: [
'md',
'markdown',
'mdown',
'mkdn',
'mkd',
'mdwn',
'mkdown',
'ron'
],
ignoreName: '.remarkignore',
name: 'remark',
packageField: 'remarkConfig',
pluginPrefix: 'remark',
processor: remark,
rcName: '.remarkrc',
version: '11.0.0'
})
β¦now running
node example.js --help
yields:Usage: remark [options] [path | glob ...]
Command line interface to inspect and change markdown files with remark
Options:
--[no-]color specify color in report (on by default)
--[no-]config search for configuration files (on by default)
-e --ext <extensions> specify extensions
β¦
API
This package exports the identifierargs
api-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
api-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][ignore-file] to load
(engine: `options.ignoreName`)
name
(string
, required)
β name of executable
packageField
(string
, required)
β field where [configuration][config-file] can be found in `package.json`s
(engine: `options.packageField`)
pluginPrefix
(string
, required)
β prefix to use when searching for plugins
(engine: `options.pluginPrefix`)
processor
(Processor
unified-processor, required)
β processor to use
(engine: `options.processor`)
rcName
(string
, required)
β name of [configuration files][config-file] to load
(engine: `options.rcName`)
version
(string
, required)
β version of executable
CLI
CLIs created withunified-args
, such as the example above, have an
interface similar to the below:Usage: remark [options] [path | glob ...]
Command line interface to inspect and change markdown files with remark
Options:
--[no-]color specify color in report (on by default)
--[no-]config search for configuration files (on by default)
-e --ext <extensions> specify extensions
--file-path <path> specify path to process as
-f --frail exit with 1 on warnings
-h --help output usage information
--[no-]ignore search for ignore files (on by default)
-i --ignore-path <path> specify ignore file
--ignore-path-resolve-from cwd|dir resolve patterns in `ignore-path` from its directory or cwd
--ignore-pattern <globs> specify ignore patterns
--inspect output formatted syntax tree
-o --output [path] specify output location
-q --quiet output only warnings and errors
-r --rc-path <path> specify configuration file
--report <reporter> specify reporter
-s --setting <settings> specify settings
-S --silent output only errors
--silently-ignore do not fail when given ignored files
--[no-]stdout specify writing to stdout (on by default)
-t --tree specify input and output as syntax tree
--tree-in specify input as syntax tree
--tree-out output syntax tree
-u --use <plugins> use plugins
--verbose report extra info for messages
-v --version output version number
-w --watch watch for changes and reprocess
Examples:
# Process `input.md`
$ remark input.md -o output.md
# Pipe
$ remark < input.md > output.md
# Rewrite all applicable files
$ remark . -o
Files
All non-options passed to the cli are seen as input and can be:- paths (
readme.txt
) and globsglob (*.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][ignore-file].
The default behavior is to exclude files in `node_modules/` unless
explicitly given
You can force things to be seen as input by using --
:cli -- globs/* and/files
- default: none
- engine:
options.files
--color
cli --no-color input.txt
Whether to output ANSI color codes in the report.
- default: whether the terminal supports colorsupports-color
- engine:
options.color
π Note: This option may not work depending on the reporter given in
--report
cli-report.
--config
cli --no-config input.txt
Whether to load configuration filesconfig-file.
Searches for files with the configuredapi-options
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>
cli --ext html .
cli --ext htm --ext html .
cli --ext htm,html .
Specify one or more extensions to include when searching for files.
- default: configuredapi-options
extensions
- alias:
-e
- engine:
options.extensions
--file-path <path>
cli --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
cli --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
cli --help
Output short usage information.
- default: off
- alias:
-h
--ignore
cli --no-ignore .
Whether to load ignore filesignore-file.
Searches for files named
$ignoreName
api-options.- default: on
- engine:
options.detectIgnore
--ignore-path <path>
cli --ignore-path .gitignore .
File path to an ignore fileignore-file to load, regardless of
--ignore
cli-ignore.- default: none
- alias:
-i
- engine:
options.ignorePath
--ignore-path-resolve-from cwd|dir
cli --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>
cli --ignore-pattern "docs/*.md" .
Additional patterns to use to ignore files.
- default: none
- engine:
options.ignorePatterns
--inspect
cli --inspect < input.txt
Output the transformed syntax tree, formatted with
unist-util-inspect
unist-util-inspect.
This does not run the compilation phaseoverview.- default: off
- engine:
options.inspect
--output [path]
cli --output -- .
cli --output doc .
cli --output doc/output.text input.txt
Whether to write successfully processed files, and where to. Can be set from configuration filesconfig-file.
- 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
cli --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
cli-report.
--rc-path <path>
cli --rc-path config.json .
File path to a configuration fileconfig-file to load, regardless of
--config
cli-config.- default: none
- alias:
-r
- engine:
options.rcPath
--report <reporter>
cli --report ./reporter.js input.txt
cli --report vfile-reporter-json input.txt
cli --report json input.txt
cli --report json=pretty:2 input.txt
cli --report 'json=pretty:"\t"' input.txt
# Only last one is used:
cli --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>
cli-setting.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
vfile-reporter - engine:
options.reporter
andoptions.reporterOptions
π Note: thequiet
cli-quiet,silent
cli-silent, andcolor
cli-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>
cli --setting alpha:true input.txt
cli --setting bravo:true --setting '"charlie": "delta"' input.txt
cli --setting echo-foxtrot:-2 input.txt
cli --setting 'golf: false, hotel-india: ["juliet", 1]' input.txt
Configuration for the parser and compiler of the processor. Can be set from configuration filesconfig-file.
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
cli --silent input.txt
Show only fatal errors in the report. Turns
--quiet
cli-quiet on.- default: off
- alias:
-S
- engine:
options.silent
π Note: this option may not work depending on the reporter given in
--report
cli-report.
--silently-ignore
cli --silently-ignore **/*.md
Skip given files which are ignored by ignore files, instead of warning about them.
- default: off
- engine:
options.silentlyIgnore
--stdout
cli --no-stdout input.txt
Whether to write a processed file to stdout(4).
- default: off if
--output
cli-output or--watch
cli-watch are
given, or if multiple files could be processed
- engine:
options.out
--tree
cli --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 phaseoverview.
- default: off
- alias:
-t
- engine:
options.tree
--tree-in
cli --tree-in < input.json > input.txt
Treat input as a syntax tree in JSON. This does not run the parsing phaseoverview.
- default: same as
--tree
- engine:
options.treeIn
--tree-out
cli --tree-out < input.txt > output.json
Output the transformed syntax tree. This does not run the compilation phaseoverview.
- default: same as
--tree
- engine:
options.treeOut
--use <plugin>
cli --use remark-man input.txt
cli --use man input.txt
cli --use 'toc=max-depth:3' input.txt
cli --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 filesconfig-file.
To pass options, follow the plugin by an equals sign (
=
) and settings, which
have the same in syntax as --setting <settings>
cli-setting.Plugins prefixed with the configuredapi-options
pluginPrefix
are
preferred over modules without prefix.- default: none
- alias:
-u
- engine:
options.plugins
--verbose
cli --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
cli-report.
--version
cli --version
Output version number.
- default: off
- alias:
-v
--watch
cli -qwo .
Yields:
Watching... (press CTRL+C to exit)
Note: 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
cli-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:Debugging
CLIs can be debugged by setting theDEBUG
debug environment variable to
*
, such as DEBUG="*" cli example.txt
.Types
This package is fully typed with TypeScript. It export the additional typeOptions
api-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
Seecontributing.md
contributing in unifiedjs/.github
health for ways
to get started.
See support.md
support for ways to get help.This project has a code of conductcoc. By interacting with this repository, organization, or community you agree to abide by its terms.