Command Line Interface

Yoshimi supplies a command line interface (CLI) that can perform any action that is available in the graphical interface (GUI). The CLI closely follows the GUi with respect to context levels. However, some control names are changed to enable shorter, unambiguous abbreviations to be used.

With Yoshimi installed, open a terminal window and type 'yoshimi' to start. Unless you have disabled the GUI it will also show, but the prompt you will see will be something like the following:

Yoshimi 2.3.0 is starting Using jack_audio for audio and alsa_midi for midi Alsa midi priority is 39 Yoshimi 2.3.0 Build Number 2220 Clientname: yoshimi Audio: jack -> 'default' Midi: alsa -> 'Hua Xing:0, Komplete Audio 6:0' Oscilsize: 512 Samplerate: 48000 Period size: 64 Yay! We're up and running :-) Found 7284 instruments in 201 banks Root 9. Bank set to 115 "The_Mysterious_Bank" GUI refreshed yoshimi>
A minor annoyance is that the GUI (if it is enabled) will take input focus as it opens, so you will have to click in the terminal window again to make further commands.

There are a number of commands that can be set at the time you start Yoshimi. Before starting you can view these with:
music@devuan:~$ yoshimi --help
This doesn't actually start Yoshimi itself, but as you can see there are a lot of options available.The full list of options is:
music@devuan:~$ yoshimi --help Yoshimi 2.3.0 is starting Usage: yoshimi [OPTION...] Yoshimi 2.3.0, a derivative of ZynAddSubFX - Copyright 2002-2009 Nasca Octavian Paul and others, Copyright 2009-2011 Alan Calvert, Copyright 2012-2013 Jeremy Jongepier and others, Copyright 2014-2023 Will Godfrey and others -a, --alsa-midi[=<device>] use alsa midi input -A, --alsa-audio[=<device>] use alsa audio output -b, --buffersize=<size> set internal buffer size -c, --no-cmdline disable command line interface -C, --cmdline enable command line interface -D, --define-root=<path> define path to new bank root -i, --no-gui disable gui -I, --gui enable gui -j, --jack-midi[=<device>] use jack midi input -J, --jack-audio[=<server>] use jack audio output -k, --autostart-jack auto start jack server -K, --auto-connect auto connect jack audio -l, --load=<file> load .xmz parameters file -L, --load-instrument=<file> [@part]; load .xiz instrument file(no space)@n to part 'n' -M, --load-midilearn=<file> load .xly file --null use Null-backend without audio/midi -N, --name-tag=<tag> add tag to clientname -o, --oscilsize=<size> set AddSynth oscillator size -R, --samplerate=<rate> set alsa audio sample rate -S, --state[=<file>] load .state complete machine setup file -S, --state[=] load .state complete machine setup file -u, --jack-session-file=<file> load named jack session file -U, --jack-session-uuid=<uuid> jack session uuid -?, --help Give this help list --usage Give a short usage message Mandatory or optional arguments to long options are also mandatory or optional for any corresponding short options. music@devuan:~$
Many of these options can be stacked when you do start, such as:
yoshimi -b=128 -i -j
In the above example we are setting the buffer size to 128 frames, disabling the GUI and setting MIDI input to Jack. These settings only apply to the current instance, and don't change the stored ones.

Once running in the CLI you will be at the top level. Entering 'help', or just a '?' will list all the available commands and also the names of the available contexts. If reporting is set for the CLI this will be paged as shown below.
yoshimi> ? Commands: ? Help show commands List list current settings STop all sound off RESet [s] return to start-up conditions, 'ALL' clear MIDI-learn (if 'y') EXit [s] tidy up and close Yoshimi (if 'y'), 'FOrce' instant exit regardless RUN <s> execute named command script forcing top level start RUNLocal <s> execute named command script from current context level WAIT <n> 1mS to 30,000mS delay, within script only .. step back one level / step back to top level Part [n1] ... - part operations VEctor [n1] ... - vector operations SCale ... - scale (microtonal) operations MLearn [n1] ... - MIDI learn operations COnfig ... - configuration settings q=quit /=search PgUp/PgDown=scroll (line 1 of 65)
Quitting this pager will return you to the prompt, and it now shows the current context level.
@ Top yoshimi>
Notice the odd capitalisation. This indicates the minimum abbreviation for the respective controls. Be aware that the same command doesn't always have the same minimum in other contexts.
Back to top

Examples

When entering the query on other context levels you will normally get the first few top level ones as a reminder these are available from any level. Other than that you will only see the commands (and deeper contexts) appropriate to that level. However, you can also specifically query a context from any point , in which case you will see the list for that one only, without changing your current position.
@ p1+, Sub yoshimi> ? vector Vector: <n> set current base channel [X/Y] CC <n> CC n is used for X or Y axis sweep [X/Y] Features <n> [s] sets X or Y features 1-4 (ON, Reverse, {other}) [X] PRogram <l/r> <n> X program change ID for LEFT or RIGHT part [Y] PRogram <d/u> <n> Y program change ID for DOWN or UP part [X/Y] Control <n1> <n2> sets n2 CC to use for X or Y feature n1 (2-4) OFF disable vector for this channel Name <s> text name for this complete vector @ p1+, Sub yoshimi>
Another very useful command is 'list' (or 'l'). The command by itself just shows what lists are available. A full example listing the current MIDI learned CCs is shown below.
@ Top yoshimi> l mlearn Midi learned: Line 1 CC 7 Chan 1 Part 1 Effect Send 1 Line 2 CC 81 Chan 1 Part 1 Kit 1 Add Voice 1 Harmonic 1 Amplitude Line 3 CC 82 Chan 1 Part 1 Kit 1 Add Voice 1 Harmonic 3 Amplitude Line 4 CC 83 Chan 1 Part 1 Kit 1 Add Voice 1 Harmonic 2 Amplitude Line 5 CC 84 Chan 1 Part 1 Kit 1 Add Voice 1 Harmonic 4 Amplitude Line 6 CC 85 Chan 1 Part 1 Kit 1 Add Voice 1 Harmonic 6 Amplitude Line 7 CC 86 Chan 1 Part 1 Kit 1 Add Voice 1 Harmonic 8 Amplitude Line 8 CC 87 Chan 1 Part 1 Kit 1 Add Voice 1 Harmonic 10 Amplitude Line 9 CC 88 Chan 1 Part 1 Kit 1 Add Voice 1 Harmonic 12 Amplitude Line 10 CC 94 Chan 1 Main Master Mono/Stereo @ Top yoshimi>
As a general rule '?' tells you what you can do and 'l' tells you what has been set.

Many context levels have defaults that kick in if you don't add additional information. The most obvious being the Part level with just:
@ Top yoshimi> set part @ Part 1+ yoshimi>
You not only see that it is on part 1 but the '+' indicates it's enabled. There are lots of hints like this. Also any context with numeric settings can be changed simply with the number:
@ Part 1+ yoshimi> set 5 @ Part 5 yoshimi>
Note that part 5 has no '+' so is not enabled.

Many actions will stack if all the required context levels are active:
@ Part 5 yoshimi> s 1 add voice wave @ p1+, A+, V1+ Sine yoshimi>
Here we used the minimum abbreviation for 'set'. You will also see that not only have we jumped right up into the waveform context of Addsynth Voice 1, but that the current waveform is 'Sine' and all the earlier labels are now compressed so that the line doesn't get ridiculously long.

Other useful commands are: Instead of 'Read' you can use 'Get' but we don't recommend that. When working quickly it's easy for the wrong muscle memory to kick in so you mix up 'Set' and 'Get'.

Here is another sequence of commands:
@ Top yoshimi> s sys ec System Effect 1 set to Echo @ Sys eff 1 ECho-1 yoshimi> r del System Effect 1 Echo Delay Value 35.000000 @ Sys eff 1 ECho-1 yoshimi> s del 40 System Effect 1 Echo Delay Value 40.000000 @ Sys eff 1 ECho-1? yoshimi> max del Max 127 - learnable @ Sys eff 1 ECho-1? yoshimi>
Notice the '?' when you change the delay value. This is a warning that although the effect started with preset 1, you have now changed it. If you change either the preset or the effect itself, that setting will be lost.

Calling for the maximum also gave you the information that the control could be MIDI-learned.

The prompt can become 'stale' if there is a lot of activity from the GUI or via MIDI, but can be refreshed simply by hitting the 'return' key, although it may be best to return to top level if you are not actively working.

Back to Examples Back to top