Usage

Input Modes

Glossia accepts payload words in three ways:

For --from-ascii, use - to read from stdin:

echo "my secret" | glossia --from-ascii -

Decoding

Use --decode to convert payload words back to bytes (inverse of --from-ascii):

glossia --decode word1 word2 word3

Words can be provided as positional arguments or piped via stdin.

Dialect Modes

The --dialect flag selects the sentence generation style. It can include the language: --dialect latin-body, --dialect cs-nip04.

Poetry

The verse dialects render the same payload as metrical lines. Feed in a mnemonic, get a poem:

$ glossia --dialect haiku --seed 42 legal winner thank yellow zoo zebra youth wrist wrap world work word

The legal winner
thank yellow. Zoo get zebra
to a youth wrist to
wrap via its world
work. Word may row.

(Every example here passes --seed so it reproduces; without one, each run picks fresh cover words and you get a different poem from the same payload.)

The same twelve words in the other forms:

$ glossia --dialect syllabic ...        $ glossia --dialect iambic ...

The legal winner thank yellow. Zoo get  A legal winner thank rub. Yellow see
zebra to a youth wrist to wrap via      zoo via zebra. Its youth wrist wrap world.
its world work. Word may row.           The work may word out.

$ glossia --dialect dactyl ...

Tire is legal to winner. Thank yellow zoo
via pop. Zebra are youth to wrist. Wrap is world
per work. Word set lip.

Two flags behave differently for a verse dialect, both automatically:

• Output breaks on the meter, so --width is ignored.
• --best-of defaults to 4 rather than 1, because whether the lines come out whole is the tie-break among equally dense candidates. An explicit --best-of always wins. Raising it to 8–12 buys a better poem; beyond that the CLI's memory use grows sharply (a pre-existing limit of --best-of, not specific to verse).

Poetry is not a separate encoding. Payload words and their order are untouched, so a poem decodes with exactly the command that decodes prose:

$ glossia --from-ascii "meet me at dawn" --dialect haiku --seed 11
Ability hope
clinic to fringe. Dolphin stone
tea. Mother set our
magic lottery.
Good may arm to swear.

$ glossia --from-ascii "meet me at dawn" --dialect haiku | glossia --decode
meet me at dawn

Not every rendering scans — a payload word that will not fit its line is placed anyway rather than dropped, since the payload always wins. See Verse Dialects for what each form costs in density, how to declare your own, and why the meter is built rather than filtered for.

Length Modes

The --length-mode flag controls how sentence length is chosen:

• compact: Try lengths from k_min to k_max, shortest first. Produces the most concise output.
• natural: Sample length from the grammar's probability distribution. Produces more varied, natural-sounding text.

If not specified, the default depends on the dialect: body uses natural, subject uses compact.

Highlighting

Payload Highlighting

--highlight-payload <mode> marks payload words in the output:

Merkle Highlighting

--highlight-merkle <mode> highlights Merkle proof words separately (only with --merkle). Same options as --highlight-payload.

Mad-lib Mode

--madlib replaces payload words with [POS] placeholders:

$ glossia --random 6 --seed 0 --madlib

This shows the grammatical structure without revealing the payload.

Merkle Trees

--merkle wraps N payload words in a Merkle proof structure, expanding them to 2N-1 words:

$ glossia --random 6 --merkle --seed 0

--demerkle extracts the original payload from a merkleized sequence:

$ glossia --demerkle word1 word2 word3 ...

Variations

--variations <N> generates N different embeddings and selects the most compact one. Prints statistics showing compactness scores:

$ glossia --random 12 --variations 3 --seed 0

Language and Wordlist

• --language, -l <lang>: Language for grammar and wordlists. Default: english.
• --wordlist <name>: Wordlist to use. Options: bip39 (default), ngram, hp.

Tuning Parameters

Other Flags

Complete Command Reference

glossia [OPTIONS] [<word1> <word2> ... <wordN>]

Options:
  --random <N>              Generate N random payload words
  --from-ascii <text>       Encode ASCII text (use '-' for stdin)
  --decode                  Decode words back to bytes
  --dialect <dialect>       body (default), subject, or payload_only
                          Can include language: latin-body, english-subject, cs-nip04
                          Verse (English): syllabic, haiku, iambic, dactyl, anapest
  --length-mode <mode>      compact or natural
  --highlight-payload <mode>  none, bars, or color name/code
  --highlight-merkle <mode>   Merkle word highlighting
  --merkle                  Wrap payload in Merkle proof
  --demerkle                Extract payload from merkleized sequence
  --madlib                  Replace payload with [POS] placeholders
  --seed <N>                Deterministic seed
  --variations <N>          Generate N variations, pick most compact
  --language, -l <lang>     Language (default: english)
  --wordlist <name>         Wordlist: bip39, ngram, hp
  --k-min <N>               Min sentence length (default: 3)
  --k-max <N>               Max sentence length (default: 20)
  --width <N>               Line wrap width (default: 80)
  --delimiter <str>         Delimiter for payload_only mode
  --show-grammar            Display grammar rules
  --verbose, -v             Debug output
  --help                    Show help