JSON-RPC

festival-cli's main purpose is to send and receive JSON-RPC 2.0 messages from/to a festivald.

The way to send a method to festival using festival-cli is always the same:

festival-cli [--OPTIONAL-FLAGS] <METHOD> [--PARAM <VALUE>]

The <METHOD> will always be a method name as documented in festivald, and parameters are represented by --param-name <value>. If a parameter is optional (maybe-null), then not passing the --flag would be the same as not including the parameter.

For example, to send the collection_new method to create a new Collection, you would run:

festival-cli collection_new

This method also has an optional parameter, paths, which can be specified like this:

festival-cli collection_new --paths /first/path --paths /second/path

Methods without parameters do not need (and don't have) any associated command flags:

festival-cli collection_full

Pre-flags

Before specifying a method, you can insert some --flags that alter various things.

For example, to connect to a different festivald:

festival-cli --festivald https://festivald.pm:18425 collection_full

To print the configuration that would have been used, but without connecting to anything:

festival-cli --dry-run collection_full

To set a connection timeout:

festival-cli --timeout 5 collection_full

These pre-flags must come before the method name, because every --flag that comes after <METHOD> will be assumed to be a --parameter.

Output

festival-cli splits output between STDOUT/STDERR.

The only output sent to STDOUT is the actual JSON-RPC method response, everything else is sent to STDERR.

This means you can do:

festival-cli --debug collection_full | jq

and the debug information will be printed, but jq (or any other program/redirection) will only see the JSON-RPC response.

Help

To list all available methods:

festival-cli --methods

To show the parameters/values needed for a specific method:

festival-cli <METHOD> -h

Detailed Help

Running:

festival-cli <METHOD> --help

will output markdown text equivalent to the festivald documentation for that method.

To view the festivald documentation proper:

  • View it at https://docs.festival.pm/daemon, or
  • View it locally with festivald --docs, or
  • Serve/view it yourself at http://localhost:18425 after starting festivald

All method documentation will include what inputs it needs, what output to expect, and examples.

Examples

Each method in festivald's documentation has a festival-cli example.