cli

Details #

A cli entry adds a command to the switchboard tool in the terminal. It runs as switchboard <short name> <command> .... The short name is the last part of the extension id, so com.example.notes is notes.

Declare it in switchboard.json under adds.cli. Every entry has an id (lowercase, digits and . _ -, up to 64 characters, starting with a letter; it is the command's name), a title (1 to 80 characters) and an optional description and params. Ids must be unique within the list.

{
  "adds": {
    "cli": [
      { "id": "sync", "title": "Sync notes", "params": { "type": "object", "properties": { "force": { "type": "boolean" } } } }
    ]
  }
}

cli('sync', async ({ args, params }, ctx) => (params.force ? 'synced everything' : 'synced changes'))

Then switchboard notes sync --force prints synced everything.

Gotchas #

• The handler has 30 seconds.

• The engine must be running; the command talks to it.

• An unknown command name lists the commands that exist.

• The manifest checks the entry's shape; the handler does the work. Without a matching handler the extension doesn't load.

• Unknown keys in an entry are refused.

Handler #

The handler gets { args, params }. The words after the command are turned into params using the entry's params schema:

• --name value or --name=value sets name. A number or integer property becomes a number.

• A boolean property can be given alone (--force) and becomes true.

• When the schema lists required properties, the first plain words fill them in order. A required one still missing stops the command with "missing --name".

• Plain words left over arrive in args.

It returns the text to print. Return a string to print it and exit 0. Return { stdout, stderr, exitCode } to print on both streams and choose the exit code. Any other JSON is printed as JSON.

Full example #

The Full example above is a working extension with two commands, tally and tallies. You can download it from the Full example section and edit it into your own.

See also #

• actions