CLI reference

phony trains N-gram models and generates synthetic data locally and deterministically. train / info / validate / stats work on .ngram models; generate runs any generator or PGDL definition reproducibly from a seed; the package commands (install, add, remove, update, list) manage the phony.json dependency closure.

phony <command> [options]

Exit codes

Code	Meaning
0	Success.
1	Any error — bad arguments, missing files, train/generate failures.
4	validate only: the model file failed format/integrity checks.

Commands at a glance

Command	Purpose
train	Train an N-gram model from input data.
generate	Generate values from a generator or PGDL definition.
info	Display model metadata.
validate	Validate a model file's format and integrity (exit 4 when invalid).
stats	Show model statistics.
install	Resolve + fetch the dependency closure into the store and write phony.lock.
add	Add a dependency to phony.json and lock it.
remove	Remove a dependency from phony.json and re-resolve the lock.
update	Re-resolve dependencies (all, or one) ignoring the lock.
list	List the resolved dependency closure.

---

phony train

Train an N-gram model from a text file and write a .ngram model.

phony train <INPUT> [-o model.ngram] [-n 3] [-t char] [--locale …] [--min-count 0] …

<INPUT> is a positional file argument: one item per line for char / word token types; the whole file is treated as prose for text. Blank lines are trimmed and skipped (a char/word file with no non-empty lines errors).

Flag	Alias	Type / values	Default	Description
<input>		path (positional)	—	Input file.
--output	-o	path	model.ngram	Output model file.
--ngram-order	-n	integer 2–5	3	N-gram order. Out-of-range errors.
--token-type	-t	char | word | text	char	char = words/names, word = phrases, text = prose (char n-grams + learned sentence lengths + positional openings).
--locale		string	none	Locale tag → tokenizer preset stored in the model (e.g. tr_TR).
--min-count		integer	0	Prune n-gram transitions seen fewer than N times (privacy + size; 0 keeps all).
--min-word-length		integer	preset	Tokenizer override: minimum word length to keep.
--lowercase		flag	off	Tokenizer override: lowercase input before training.
--word-filter		string (regex)	preset	Tokenizer override: regex of characters to drop from each word.

The tokenizer starts from the --locale preset (or the default when no locale is given), then applies the --min-word-length / --lowercase / --word-filter overrides on top. On success it prints the token type, order, item count, output path, and byte size.

Example

phony train first-names.txt -o names.ngram -n 3 -t char --locale tr_TR

---

phony generate

Generate values from a generator-definition file or a named registered generator.

phony generate [INPUT] [--use NAME] [--package DIR]… [--seed 0] [-n 1] [-f json] …

Provide either a positional INPUT file (a PGDL generator-definition JSON, either { "type": … } or { "use": … }) or --use NAME. Giving neither errors.

Flag	Alias	Type	Default	Description
<input>		path (positional, optional)	—	PGDL generator-definition JSON file. Omit when using --use.
--use		string (NAME)	none	Generate a registered generator by name (a built-in @phony/core:* or one from a package).
--package		path (repeatable)	none	Load a package directory (with phony.json); later packages extend/override earlier ones.
--seed		u64	0	Root seed — the same seed reproduces the same values.
--count	-n	integer	1	How many values to generate.
--format	-f	json | jsonl	json	Output format: a pretty JSON array, or one JSON value per line (NDJSON).
--locale		string	*	Locale chain for asset resolution, most specific first (e.g. tr_TR,*). Split on commas.
--reference-time		i64 (epoch seconds)	live	Freeze the reference clock for now()/today()/relative dates.
--manifest		path (DIR)	.	Project directory whose phony.json closure is auto-loaded.
--frozen		flag	off	Never fetch; use only what the lock + cache already provide.

Loading order (later layers can shadow earlier ones — "root wins"): the project's resolved dependency closure (leaves-first) is auto-loaded from --manifest, then the root project's own phony.json package, then each --package directory in order. Each loaded package prints a ✓ Loaded … line to stderr.

Examples

# A built-in generator by name, five reproducible values as NDJSON.
phony generate --use @phony/core:logic.uuid_v4 --seed 42 -n 5 -f jsonl

# A generator-definition file with a frozen clock.
phony generate person.json --seed 7 -n 100 --reference-time 1700000000

A minimal definition file:

{ "type": "logic", "algorithm": "int_between", "params": { "min": 1, "max": 100 } }

---

phony info

Print a model's metadata as a tree.

phony info <MODEL>

<MODEL> is a positional path. Reports token type, N-gram order, locale (when set), trained-item count, N-gram count, whether sentence/paragraph length stats and sentence/paragraph positions are present, and the file size.

phony validate

Validate a model file's format and integrity.

phony validate <MODEL>

Prints ✓ Valid — … and exits 0 when the model loads, or ✗ Invalid: … to stderr and exits 4 when it does not. This is the only command that uses a non-1 error code.

phony stats

Print model statistics (token type, order, trained items, N-gram count, and the same sentence/paragraph feature flags as info).

phony stats <MODEL>

---

Package commands

These operate on a project directory containing phony.json. All accept --manifest DIR (default .). The store is located at $PHONY_HOME/store, or ~/.phony/store. See phony.json for the manifest, lock, and store details and Packages for the model.

phony install

Resolve + fetch the dependency closure into the store and write phony.lock.

phony install [--manifest .] [--update] [--frozen]

Flag	Type	Default	Description
--manifest	path (DIR)	.	Project directory containing phony.json.
--update	flag	off	Re-resolve versions, ignoring an existing lock.
--frozen	flag	off	Never fetch; require an up-to-date lock and a warm cache.

Prints the installed package count and each package's name, version, and short (12-char) commit.

phony add

Fetch, verify the package name, record the dependency in phony.json, and re-lock.

phony add <SPEC> [--name NAME] [--manifest .]

Argument / flag	Type	Default	Description
<spec>	string (positional)	—	Shorthand <host>/<path>@<version-or-ref>.
--name	string	inferred	Expected package name; errors if the repo declares a different one.
--manifest	path (DIR)	.	Project directory.

phony remove

Drop a dependency by package name and re-resolve the lock.

phony remove <NAME> [--manifest .]

phony update

Re-resolve dependencies ignoring the lock. With a NAME, move only that dependency; others stay at their locked commit.

phony update [NAME] [--manifest .]

phony list

Print the resolved dependency closure.

phony list [--manifest .] [--json]

Flag	Type	Default	Description
--manifest	path (DIR)	.	Project directory.
--json	flag	off	Emit JSON (name, git, version, commit) instead of name version (short-commit) text.