A route is an address in your CLI, such as / or /pr/list. A method is what the user asks to do at that address: help, version, or execute. This guide shows how to declare routes and choose the methods each one supports.
route(name(...), ...) declares an address that supports help only.
command(name(...), ...) declares an address that supports help and execute.
A child route is passed straight to its parent, next to the parent’s options and other elements. To reuse a group of routes, bundle them with extend(). Before 0.8.0, child routes went inside a routes() wrapper, which no longer exists.
command() is exactly a route() with executable() added, so these two definitions are equivalent:
The root name identifies the executable. Route IDs start below it, so gh pr list selects /pr/list.
An option belongs to the route that declares it, and it must come after that route’s name. If --repo were declared on the pr route, gh pr --repo bombshell-dev/docs list would work and gh pr list --repo bombshell-dev/docs would fail. Declare options on the command that uses them, so users can put them at the end, as they expect.
Every route supports help. The other two methods exist only where you add them:
Element
Adds
Request it with
Built in
help
--help or -h
executable()
execute
the route words alone
version("x.y.z")
version
--version or -v
version() does not inherit. In the tree above, only / and /copilot declare a version, so gh copilot --version returns VERSION /copilot, while gh pr list --version fails with method-not-allowed.
--help and --version request a method. They do not stop parsing, and they always target the deepest route on the command line, wherever they appear. All three of these return HELP /pr/list:
When the user asks for a method a route does not support, parse() returns a failure with the code method-not-allowed. The failure names the method that was requested and the methods the route allows:
The process.argv property returns an array containing the command-line
arguments passed when the Node.js process was launched. The first element will
be
execPath
. See process.argv0 if access to the original value
of argv[0] is needed. The second element will be the path to the JavaScript
file being executed. The remaining elements will be any additional command-line
arguments.
For example, assuming the following script for process-args.js:
Returns a copy of a section of an array.
For both start and end, a negative index can be used to indicate an offset from the end of the array.
For example, -2 refers to the second to last element of the array.
@param ― start The beginning index of the specified portion of the array.
If start is undefined, then the slice begins at index 0.
@param ― end The end index of the specified portion of the array. This is exclusive of the element at the index 'end'.
If end is undefined, then the slice extends to the end of the array.
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:
A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.
Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s','world');
// Prints: hello world, to stdout
console.error(newError('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
// Error: Whoops, something bad happened
// at [eval]:5:15
// at Script.runInThisContext (node:vm:132:18)
// at Object.runInThisContext (node:vm:309:38)
// at node:internal/process/execution:77:19
// at [eval]-wrapper:6:22
// at evalScript (node:internal/process/execution:76:60)
// at node:internal/main/eval_string:23:3
constname='Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
constout=getStreamSomehow();
consterr=getStreamSomehow();
constmyConsole=new console.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s','world');
// Prints: hello world, to out
myConsole.error(newError('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
Prints to stderr with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
constcode=5;
console.error('error #%d', code);
// Prints: error #5, to stderr
console.error('error', code);
// Prints: error 5, to stderr
If formatting elements (e.g. %d) are not found in the first string then
util.inspect() is called on each argument and the
resulting string values are concatenated. See util.format()
for more information.
A word that matches no route is not a “route not found” error. The router treats it as input that nothing claimed, so gh bogus fails with unprocessable-content at / and the message unexpected: `bogus` .
Nothing after -- takes part in routing, methods, or options. gh pr list -- --limit 5 returns EXECUTE /pr/list with the default { limit: 30 }.