CLI Reference
Reference for the phony command-line interface.
Implementation status
The commands under Implemented Commands exist today in phony-cli (v0.0.x) and work fully offline. Everything under Planned Commands is cloud-platform target design — not built. Options and defaults below mirror the actual binary; phony --help is authoritative.
Installation
# Cargo (from source) — the only channel today
cargo install --path . # from a phony-cli checkout (path-deps on a sibling phony-core)
# Planned distribution channels (not live yet)
# brew install phonycloud/tap/phony
# curl -fsSL https://phony.cloud/install.sh | shCommand Overview
┌─────────────────────────────────────────────────────────────────────────┐
│ PHONY CLI COMMAND STRUCTURE │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ IMPLEMENTED (offline, MIT) │
│ ══════════════════════════ │
│ phony train Train an N-gram model from data │
│ phony generate Generate values from a PGDL definition (local) │
│ phony info Display model metadata │
│ phony validate Validate a .ngram model file │
│ phony stats Show model statistics │
│ phony install Resolve + fetch deps into the store, write phony.lock │
│ phony add Add a dependency to phony.json and lock it │
│ phony remove Remove a dependency and re-resolve the lock │
│ phony update Re-resolve dependencies (all, or one) │
│ phony list List the resolved dependency closure │
│ │
│ PLANNED (cloud control plane — target design) │
│ ═════════════════════════════════════════════ │
│ phony login / logout / whoami │
│ phony sync Local-first DB sync (data plane runs here) │
│ phony snapshot Snapshot create/restore (stored in YOUR storage) │
│ phony mock Local mock server + hosted deploy │
│ │
└─────────────────────────────────────────────────────────────────────────┘Implemented Commands
phony train
Train an N-gram model from input data (streaming; memory stays flat on large corpora).
phony train <input> [options]| Option | Default | Description |
|---|---|---|
-o, --output <file> | model.ngram | Output model file |
-n, --ngram-order <n> | 3 | N-gram order (2-5) |
-t, --token-type <type> | char | char, word, or text |
--locale <code> | - | Tokenizer preset (e.g. tr_TR, en_US) |
--min-count <n> | - | Prune n-grams seen fewer than n times (privacy/noise) |
--min-word-length <n> | preset | Tokenizer override |
--lowercase <bool> | preset | Tokenizer override |
--word-filter <regex> | preset | Tokenizer override |
# From a text file (one item per line)
phony train names.txt -o names.ngram
# Turkish names, order 4, with privacy pruning
phony train turkish_names.txt --locale tr_TR -n 4 --min-count 2 -o tr_names.ngram
# Word-level model for sentences
phony train sentences.txt --token-type word -o sentences.ngramCSV
--columnand JSON--pathinputs are on the roadmap; today the input is plain text.
phony generate
Generate values locally from a PGDL generator definition — deterministic per seed, no network.
phony generate [definition.json] [options]| Option | Default | Description |
|---|---|---|
--use <name> | - | Generate from a registered generator by name (instead of a definition file) |
--package <dir> | - | Load a package directory (repeatable) |
--seed <n> | 0 | Root seed for deterministic output |
-n, --count <n> | 1 | Number of values |
-f, --format <fmt> | json | json or jsonl |
--locale <chain> | - | Locale resolution chain |
--reference-time <epoch> | frozen default | Reference instant for all time-based generation |
--manifest <dir> | . | Project directory whose phony.json closure is auto-loaded |
--frozen | - | Never fetch; use only what phony.lock + the store already provide |
# Inline definition file
phony generate age.json --seed 42 --count 5
# A composition from a package, as NDJSON
phony generate --package ./tr-package --use "@phony/tr:tckn" --seed 7 -n 1000 -f jsonlPackage-load summaries go to stderr; stdout stays pipeable.
phony info / phony stats
Display model metadata (info = tree view, stats = flat view): order, token type, locale, vocab size, sample counts.
phony info names.ngram
phony stats names.ngramphony validate
Validate a .ngram file's format and integrity.
phony validate names.ngram
# ✓ valid → exit 0
# ✗ invalid → exit 4phony install / add / remove / update / list
The git-based package manager — MVS resolution over vX.Y.Z tags, a global content-addressed store (~/.phony/store), and a phony.lock pin. See Package Manager.
phony install # resolve + fetch the closure, write phony.lock
phony add github.com/acme/phony-demo@1.2.0 # add a dependency and lock it
phony remove "@acme/demo" # drop a dependency, re-resolve
phony update # re-resolve, ignoring the lock
phony list --json # print the resolved closureExit Codes
| Code | Meaning |
|---|---|
0 | Success |
1 | General error (I/O, bad arguments surfaced via error message) |
4 | Invalid model format (validate) |
Planned Commands (target design)
These belong to the cloud platform; none are built. The design intent:
phony sync— the local-first data plane: runs inside your network, connects to your databases directly, anonymizes/synthesizes locally, and reports only metadata to the control plane. See Database Sync.phony snapshot— snapshots created and restored locally, stored in your storage (disk/S3/GCS); the cloud tracks metadata. See Snapshots.phony mock start— local mock server (free, offline);phony mock deploypublishes hosted endpoints (paid tiers). See Mock API.phony login / logout / whoami— control-plane authentication for the above.
There is no cloud-executed phony generate: generation is always local and always free — the CLI you have is the fast path. Bulk parallel generation at cloud scale is a platform capability used by sync jobs, not a metered service.