Command Line Interface

Mélodium is distributed as a program that have extensive and growing CLI, to see the exhaustive commands and options list:

melodium help

Run program

Launch a Mélodium program:

melodium <FILE>

or

melodium run <FILE>

or launch a specific command in Mélodium program:

melodium run <FILE> <CMD> [ARGS…]

To see specifics of a program entrypoints:

melodium run <FILE> <CMD> --help

Note: If Mélodium is installed on system, standalone .mel files and .jeu files are directly callable as-is through command line.

Secret arguments

Parameters of type Secret<T> take a locator, such as env:MELODIUM_SECRET_NAME or file:PATH, never a value (see Secrets):

melodium run <FILE> --password file:/run/secrets/db_password

--check-secrets resolves them before running, to fail right away when one cannot be resolved:

melodium run --check-secrets <FILE> --password env:MELODIUM_SECRET_DB_PASSWORD

Logs and debugging

--logs <PATH> writes logs to a file, and --debug <PATH> writes debug events.

--debug-level sets what debug events capture: none, basic, or detailed, which also captures every data transmitted, and is only meant for small-scale local debugging. It defaults to basic when debug events are written or reported, and to none otherwise.

Threads

Tracks run in parallel, on one thread per core. The MELODIUM_THREADS environment variable gives another number of threads, such as MELODIUM_THREADS=2.

Ending a run

A run ends once all its tracks are finished.

On Unix, SIGINT, SIGTERM and SIGHUP ask the run to end: running tracks get 10 seconds to finish, and a second signal or the end of this delay stops them, along with the commands they launched. Mélodium then exits with code 128 plus the signal number, such as 130 for SIGINT.

On Windows, as a best effort, Ctrl+C and Ctrl+Break do the same. Closing the console, logging off and shutting down also end the run, with only 2 seconds for running tracks, as Windows ends the process shortly after. Mélodium then exits with code 0xC000013A (STATUS_CONTROL_C_EXIT).

A program that cannot be launched, for example because a parameter is missing, exits with code 1.

Distribution engine

melodium dist makes the engine available to run treatments for a program running elsewhere:

melodium dist --ip <IP> --port <PORT> --certificate <CHAIN> --key <KEY> --recv-key-file <FILE> --send-key-file <FILE>

Both engines authenticate each other with keys, read from --recv-key-file and --send-key-file, or else from the MELODIUM_DIST_RECV_KEY and MELODIUM_DIST_SEND_KEY environment variables. --recv-key and --send-key still take them as arguments, but other local users can read process arguments.

Connections use TLS, and engines connecting only trust certificates issued by the Mélodium certificate authority. --localhost listens on localhost with the certificate embedded in Mélodium: as this certificate and its key are the same in every Mélodium binary, it only protects connections from other machines. --disable-tls sends everything readable, keys included, and is refused on addresses other than loopback ones unless --allow-plain-tcp is given.

Program information

See the commands and options of a program:

melodium info <FILE>

Check code

Check a Mélodium program validity:

melodium check <FILE>

Generates documentation

Generates documentation, as mdBook, for a Mélodium package:

melodium doc --file <FILE> <OUTPUT>

Build Jeu files

To build a Jeu file from a project:

melodium jeu build <PROJECT> <OUTPUT_FILE>