ModalJazz

The mj tool

mj makes, reads, changes, and exports scores in Terminal. The app does not have to run.

To install mj, choose ModalJazz > Install Command Line Tool… in the app. See Install.

A first score

These commands make a short piano score, write four measures of music, and export the page:

mj new twinkle.mj piano
mj write twinkle.mj 1-4 - <<'END'
m1: time=4/4 tempo="Moderato",q=96
m1 P1.1: C4:q C4:q G4:q G4:q
m1 P1.2: C3:h E3+G3:h
m2 P1.1: A4:q A4:q G4:h
m2 P1.2: F3+A3:h E3+G3:h
m3 P1.1: F4:q F4:q E4:q E4:q
m3 P1.2: D3+F3:h C3+E3:h
m4 P1.1: D4:q D4:q C4:h
m4 P1.2: G2+G3:h C3:h
END
mj run twinkle.mj ":title Twinkle, Twinkle, Little Star" \
  ":4 barline |." ":5-8 bars delete"
mj export twinkle.mj --to svg
Twinkle, Twinkle, Little Star: four measures for piano

The page that mj export writes (cut to the music).

The commands of mj

mj new

Writes a new score with eight empty measures. The extension gives the format. mj new does not write over a file that exists.

mj new prelude.mj
mj new suite.mj string-orchestra

The templates are piano (the default), string-orchestra, full-orchestra, concert-band, jazz-band, choir, choir-piano, and woodwind-quintet.

mj info

Shows the title, the composer, the parts and their staves, the number of measures, the key, and the time. The part labels (P1, P1.2) are the labels of the score text.

$ mj info twinkle.mj
title:    Twinkle, Twinkle, Little Star
composer: -
parts:    P1 Piano (2 staves)
measures: 4
key:      C major (no sharps or flats)
time:     4/4

mj read

Shows measures as compact score text: one line for each measure and staff. With no measures, it shows all of them. --staves shows only some staves.

$ mj read twinkle.mj 1-2 --staves P1.1
m1: time=4/4 tempo="Moderato",q=96
m1 P1.1: !clef=treble !key=C C4:q C4:q G4:q G4:q
m2 P1.1: A4:q A4:q G4:h

mj write

Writes score text over measures, and saves the score. Each line of the text must be in the measures that you give. A staff with no line in the text does not change. A text of - comes from standard input.

mj write twinkle.mj 2 "m2 P1.1: A4:q A4:q G4:h{ferm}"
mj write twinkle.mj 1-4 - < music.txt
mj write twinkle.mj 1-4 - -o copy.mj < music.txt

A measure line (m1: ...) replaces all settings of the measure. So when you write a measure line for measure 1, keep the time signature in it. If the result is not a valid score, mj write tells you why and changes nothing.

mj run

Runs : commands on the score, one after the other, and saves it. Put each command in quotes. -o saves to another file.

mj run prelude.mj ":key Eb" ":title Prelude in E-flat"
mj run prelude.mj ":5-8 transpose +P8" -o prelude-high.mj

mj export

Writes the score in another format: pdf, svg, musicxml, mxl, or mj. PDF gives one file with all pages. SVG gives one file for each page: prelude-1.svg, prelude-2.svg, and so on.

mj export prelude.mj --to pdf
mj export prelude.mj --to musicxml
mj export prelude.musicxml --to mj -o prelude.mj
mj export prelude.mj --to svg -o pages/prelude.svg

mj replay

Runs a session history again. The app writes the history with :export session (or Help > Save Session History…), for example for a bug report. mj replay types the same key commands again, saves the score, and tells you if the result is the same as in the app.

$ mj replay prelude-session.json
prelude-session.mj
replayed 412 events: the score is the same as the score at the end of the session

mj help

Shows all commands and options:

Usage:
  mj run <file> <command>... [-o <out>]
      Runs each `:` command on the score and saves it (to <out>, or to
      <file>). A measure range can come first: ":5-8 transpose +P8".
      A staff label (see mj info) can come before it, for a command on
      that part or staff: ":P5 instrument brace off", ":P1.2 4 clef bass".
      With no label, a command acts on P1. The messages of the commands
      go to standard output: ":set staffsize" shows the staff size.
  mj export <file> --to pdf|svg|musicxml|mxl|mj [-o <out>]
      Writes the score in another format. PDF gives one file with all
      pages; SVG gives one file per page.
      The default <out> is <file> with the extension of the format.
  mj new <file> [<template>]
      Writes a new score from a template (the default is piano) to a new
      file. The templates: piano, string-orchestra, full-orchestra,
      concert-band, jazz-band, choir, choir-piano, woodwind-quintet.
  mj info <file> [--layout]
      Shows the title, the parts, the measures, the key, and the time.
      Then each text (title block, footer, credits, cover) and each page
      setting as the : command that sets it, to copy and run again.
      --layout also shows the measures of each system on each page, with
      "(break)" or "(page break)" after a break set with :break or
      :pagebreak: "p3: m37-40 (break), m41-44".
  mj check <file>
      Lists the marks that overlap notes or other marks, one line for
      each: the page, the measure, and the two objects with their staves.
      Exits with 1 when it finds any.
  mj replay <session> [-o <out>]
      Runs a session history from the app (:export session) again and
      saves the score (to <out>, or to <session> with the extension .mj).
      Tells if the score is the same as the score at the end of the session.
  mj read <file> [<measures>] [--staves P1,P2.1]
      Shows measures as compact score text: one line for each measure
      and staff. <measures> is 5 or 5-8; the default is all of them.
  mj write <file> <measures> <text> [-o <out>]
      Writes compact score text over the measures and saves the score
      (to <out>, or to <file>). Each line of the text must be in
      <measures>. A text of - comes from standard input.
  mj help
      Shows this text.

Files: .mj (native), .musicxml or .xml (MusicXML), .mxl (compressed
MusicXML).

: commands

mj run and the run_command tool of the MCP server take the commands of the command line of the app.

A measure range can come first. Then the command acts on these measures:

  • :5-8 transpose +P8 moves measures 5 to 8 up an octave.
  • :5 clef bass puts a bass clef at the start of measure 5.
  • :3-4 volta 1 puts a first ending over measures 3 and 4.

With no range, a command acts as in the app with the cursor at the start of the score and no selection. For example, :transpose +M2 moves all of the score up a major second. The app also takes the range.

CommandWhat it does
:timeTime signature from this measure: 3/4, 6/8, C, C|, 7/8 2+2+3
:pickupMake the first measure a pickup of this length: 1/4
:keyKey signature from this measure: Eb, Cm, F#m
:clefClef change at the cursor: treble, bass, alto, tenor
:barsMeasures: +4 (add at the end), insert 2 (before this measure), insert 2 after, delete
:barlineBarline after this measure: ||, |., |, dashed, none
:repeatRepeat barlines: start, end [times], or both around the selection; off, start off, end off remove them
:voltaEnding bracket over the selected measures: 1, 2, 1,2
:segnoSegno sign at this measure
:codaCoda sign at this measure
:tocoda"To Coda" at the end of this measure
:fine"Fine" at the end of this measure
:dcD.C. at the end of this measure: dc, dc al fine, dc al coda
:dsD.S. at the end of this measure: ds, ds al fine, ds al coda
:rehearsalBoxed rehearsal mark at this measure (the next letter if empty)
:sectionNew section at this measure: a new system, numbers from 1, an optional heading ("II."); off removes it
:breakSystem break after this measure: on, off (no argument switches it)
:pagebreakPage break after this measure: on, off (no argument switches it)
:numbersMeasure numbers: print none|line-start|all, hint none|all (hints show only on screen)
:hideHide the rest under the cursor, or the rests in the selection
:showShow hidden rests again (under the cursor, or in the selection)
:transposeTranspose the selection or the score: +M2, -P4
:tempoTempo mark: q=72, "Andante" q=72, "Swing" q=178 swing, straight, q=q.
:titleScore title (| starts a new line; {italic} or {small} styles a line)
:subtitleScore subtitle (| starts a new line; {italic} or {small} styles a line)
:composerComposer (| starts a new line; {italic} or {small} styles a line)
:lyricistLyricist (at the left, on the line of the composer; | starts a new line; {italic} styles a line)
:arrangerArranger (printed as "arr. ..."; | starts a new line; {italic} styles a line)
:copyrightCopyright footer, printed as typed with no prefix: type "© 2026 ..." (| starts a new, smaller line; {italic}, {small} or {full} styles a line)
:creditsText under the last system: left|right "Text: ...|Music: ..."; small lines above the title: top "..." (| starts a new line; {italic} styles a line)
:coverPage of text before the music, with no page number: add "<text>" [title|large|normal|small] [italic] [tight] (| starts a new line; tight: no blank line above), title (the score title), footer on|off (the copyright), clear
:newNew score from a template: piano, string-orchestra, full-orchestra, concert-band, jazz-band, choir, choir-piano, woodwind-quintet
:instrumentInstruments of the cursor's part (or :P3 instrument ... for part 3): add viola (below the part), remove, move up|down, rename "Violin I" "Vln. I" (| starts a new line: "S|A"), brace on|off, barlines split|join|auto, hideempty on|off (off: :set hideempty keeps this part), systemmarks on|off (tempo and rehearsal marks above this part too), group "Choir" "Ch." (name the bracket)
:setSettings: one setting and its value, from the table of settings (Tab lists them)
:notationNotation of this staff: slash (slashes with no stems), standard
:noteheadNotehead of the selection or this chord: slash (rhythm slashes), normal, x, diamond
:slurSide of the slurs that start at this chord or in the selection: above, below, auto
:articSide of the staccatos, tenutos, accents, and marcatos on this chord or in the selection: above, below, auto
:bowBow mark on this chord or on the chords in the selection: down, up, off
:ornamentMordent or turn on this chord or the selection: mord, imord (short trill), turn, iturn, dturn (after the note), none; then the small accidentals, above/below: :ornament turn #/b, :ornament mord /#
:tupletSide of the number and bracket of the tuplets on this chord or in the selection: above, below, auto
:cueMake the selection or this event cue notes: small, and not played; off makes them normal
:tremoloTremolo on this chord or on the chords in the selection: 1 to 4 (slashes), z (buzz roll), pair (with the next chord; pair 2 for two beams), off
:hairpinSide of the hairpins that start at this chord or in the selection: above (on the line of the dynamics above), below, auto
:textOrder of the texts at the cursor's time: up (the bottom line goes up one line), down (the top line goes down), up 3 or down 2 (line 1 is the top)

These commands need the app (files, windows, playback, and entry modes), so mj and the MCP server do not take them: :w, :e, :q, :wq, :export, :part, :score, :speed, :solo, :mute, :unmute, :loop, :chords, :lyrics, :tutor. mj run takes :w <file> to save to another file.

The unregistered version

Without a license, mj export adds the same line to PDF and SVG pages as the app adds to exported pages: Engraved with ModalJazz (unregistered, purchase at modaljazz.com). The other commands work the same with or without a license. mj reads the license of the app on the same Mac.