CLI Reference

Complete reference for the phony command-line interface.

Installation

bash

# macOS / Linux
curl -fsSL https://phony.cloud/install.sh | sh

# Windows (PowerShell)
irm https://phony.cloud/install.ps1 | iex

# Homebrew (macOS)
brew install phonycloud/tap/phony

# Cargo (from source)
cargo install phony-cli

Verify Installation

bash

phony --version
# phony 1.0.0

phony --help

Command Overview

┌─────────────────────────────────────────────────────────────────────────┐
│                    PHONY CLI COMMAND STRUCTURE                          │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  OFFLINE COMMANDS (No authentication required, MIT licensed)            │
│  ════════════════════════════════════════════════════════               │
│  phony train      Train N-gram model from data                          │
│  phony info       Display model metadata                                │
│  phony validate   Validate model format                                 │
│  phony stats      Show N-gram statistics                                │
│                                                                          │
│  CLOUD COMMANDS (Requires: phony login)                                 │
│  ══════════════════════════════════════                                 │
│  phony login      Authenticate with Phony Cloud                         │
│  phony logout     End session                                           │
│  phony whoami     Show current user/organization                        │
│  phony models     Manage cloud models                                   │
│  phony sync       Database sync operations                              │
│  phony snapshot   Data snapshots                                        │
│  phony mock       Mock API management                                   │
│  phony generate   High-speed cloud generation (5M/sec)                  │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Offline Commands

phony train

Train an N-gram model from input data.

bash

phony train <input> [options]

Arguments:

Argument	Description
`<input>`	Input file (txt, csv, json) or directory

Options:

Option	Default	Description
`-o, --output <file>`	`model.phony`	Output model file
`-n, --ngram-order <n>`	`3`	N-gram order (2-5)
`-t, --token-type <type>`	`char`	Token type: `char` or `word`
`--column <name>`	-	CSV column to use
`--path <jsonpath>`	-	JSONPath expression for JSON input
`--locale <code>`	auto	Locale code (e.g., `tr_TR`, `en_US`)
`--min-frequency <n>`	`1`	Minimum n-gram frequency
`-v, --verbose`	-	Show detailed progress

Examples:

bash

# From text file (one item per line)
phony train names.txt -o names.phony

# From CSV column
phony train customers.csv --column first_name -o first_names.phony

# From JSON array
phony train data.json --path "$.users[*].name" -o names.phony

# With custom n-gram order
phony train names.txt -n 4 -o names.phony

# Word-level tokens (for sentences)
phony train sentences.txt --token-type word -o sentences.phony

# Specify locale
phony train turkish_names.txt --locale tr_TR -o tr_names.phony

phony info

Display model metadata and summary.

bash

phony info <model>

Examples:

bash

phony info names.phony

Output:

Model: names.phony
├── Version: 1
├── Locale: tr_TR
├── N-gram order: 3
├── Token type: character
├── Unique tokens: 29
├── Total n-grams: 1,245
├── Source hash: sha256:abc123...
├── CLI version: 1.0.0
└── Created: 2026-01-31T10:00:00Z

phony validate

Validate model format and integrity.

bash

phony validate <model> [options]

Options:

Option	Description
`--strict`	Enable strict validation
`--json`	Output as JSON

Examples:

bash

phony validate names.phony
# ✓ Model is valid

phony validate corrupted.phony
# ✗ Invalid: Missing required field 'metadata.locale'

phony stats

Show detailed N-gram statistics.

bash

phony stats <model> [options]

Options:

Option	Description
`--top <n>`	Show top N n-grams (default: 10)
`--json`	Output as JSON

Examples:

bash

phony stats names.phony --top 5

Output:

N-gram Statistics: names.phony
═══════════════════════════════

Token Distribution:
├── Most common: 'a' (15.2%), 'e' (12.8%), 'm' (8.4%)
└── Unique tokens: 29

N-gram Frequency (order=3):
├── "meh" → 245 occurrences
├── "ehm" → 238 occurrences
├── "hme" → 235 occurrences
├── "met" → 198 occurrences
└── "ays" → 156 occurrences

Graph Statistics:
├── Total nodes: 1,245
├── Average children: 3.2
├── Max depth: 12
└── End nodes: 89

Note: The CLI does not include local generation. Generation is done via:
Native libraries (PHP, Python, JS) - 10-50K records/sec
Cloud API (phony generate) - 5M records/sec
This architecture ensures the fastest generation is a paid Cloud feature.

Cloud Commands

Authenticate with Phony Cloud.

bash

phony login [options]

Options:

Option	Description
`--token <token>`	API token (non-interactive)
`--org <org>`	Organization to authenticate with

Examples:

bash

# Interactive login (opens browser)
phony login

# Token-based (CI/CD)
phony login --token $PHONY_API_TOKEN

# Specific organization
phony login --org acme-corp

phony logout

End the current session.

bash

phony logout

phony whoami

Show current authentication status.

bash

phony whoami

Output:

Logged in as: john@example.com
Organization: Acme Corp
Plan: Team ($79/mo)
API calls remaining: 9,847 / 10,000

phony models

Manage cloud models.

bash

phony models <command> [options]

Subcommands:

Command	Description
`list`	List available models
`push <file>`	Upload model to cloud
`pull <name>`	Download model from cloud
`delete <name>`	Delete model from cloud

Examples:

bash

# List all models (built-in + custom)
phony models list

# Upload custom model
phony models push names.phony --name custom/turkish-names

# Download built-in model
phony models pull en_US/first_names

# Download to specific path
phony models pull tr_TR/addresses -o models/addresses.phony

phony sync

Database synchronization operations.

bash

phony sync <command> [options]

Subcommands:

Command	Description
`run`	Execute sync job
`status`	Check sync status
`logs`	View sync logs

Examples:

bash

# Run sync job
phony sync run --job production-to-staging

# Check status
phony sync status

# View logs
phony sync logs --job production-to-staging --tail 100

phony snapshot

Data snapshot management.

bash

phony snapshot <command> [options]

Subcommands:

Command	Description
`create`	Create new snapshot
`list`	List snapshots
`restore`	Restore from snapshot
`delete`	Delete snapshot

Examples:

bash

# Create snapshot
phony snapshot create --name "pre-migration" --database staging

# List snapshots
phony snapshot list

# Restore
phony snapshot restore pre-migration --target staging

# Delete old snapshot
phony snapshot delete old-snapshot

phony mock

Mock API management.

bash

phony mock <command> [options]

Subcommands:

Command	Description
`start`	Start local mock server
`deploy`	Deploy to cloud
`list`	List deployed endpoints
`logs`	View request logs

Examples:

bash

# Start local mock server
phony mock start --schema api.pdl.json --port 3000

# Deploy to cloud
phony mock deploy --schema api.pdl.json

# List endpoints
phony mock list

# View logs
phony mock logs --endpoint /api/users

phony generate

High-speed cloud data generation (5M records/sec), triggered from CLI but executed on Cloud.

┌─────────────────────────────────────────────────────────────────────────┐
│                    CLOUD-POWERED GENERATION                              │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  LOCAL CLI                           PHONY CLOUD                        │
│  ═════════                           ═══════════                        │
│                                                                          │
│  $ phony generate ...                                                   │
│         │                                                                │
│         │  1. Upload schema/reference cloud model                       │
│         ▼                                                                │
│  ┌─────────────┐    API    ┌─────────────────────────────────┐         │
│  │  CLI        │──────────►│  Cloud Engine (Rust)            │         │
│  │  (trigger)  │           │  • 5M records/sec               │         │
│  │             │◄──────────│  • Advanced optimizations       │         │
│  └─────────────┘   Stream  │  • Not shared with OSS          │         │
│         │                   └─────────────────────────────────┘         │
│         ▼                                                                │
│  2. Stream results to local disk                                        │
│     (or stdout)                                                          │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Architecture Decision: There is NO local high-speed generation. Advanced optimizations (parallel processing, SIMD, memory-mapped I/O) are Cloud-exclusive and not shared. For local generation, use OSS libraries (PHP, Python, JS) which provide basic 10-50K/sec performance.

bash

phony generate [options]

Options:

Option	Default	Description
`--schema <file>`	-	Local PDL schema file (uploaded to Cloud)
`--model <name>`	-	Cloud model (e.g., `tr_TR/first_names`)
`--package <name>`	-	Package from registry
`--entity <name>`	-	Entity to generate
`-c, --count <n>`	`100`	Number of records
`-s, --seed <n>`	random	Random seed for determinism
`--format <fmt>`	`json`	Output: `json`, `csv`, `ndjson`, `sql`
`-o, --output <file>`	stdout	Output file
`--stream`	false	Stream results as they're generated

Examples:

bash

# Generate from local schema (executed on Cloud)
phony generate --schema ecommerce.pdl.json --entity User -c 10000

# Generate using Cloud model directly
phony generate --model tr_TR/first_names -c 10000 -o names.txt

# Generate from registry package
phony generate --package @phony/ecommerce-tr --entity Order -c 50000

# SQL output for database import
phony generate --schema users.pdl.json -c 100000 --format sql -o users.sql

# Stream large dataset to disk (memory-efficient)
phony generate --schema data.pdl.json -c 10000000 --stream -o huge.ndjson

# Deterministic output
phony generate --schema data.pdl.json -c 1000 --seed 12345

Performance (Cloud-powered):

Count	Network + Generation	Effective Speed
10,000	~50ms	200K/sec
100,000	~100ms	1M/sec
1,000,000	~500ms	2M/sec
10,000,000	~3s (streaming)	3M/sec

Note: Includes network latency. Pure Cloud generation is 5M/sec.

Why Cloud-Only?

Advanced Rust optimizations not shared with OSS
Parallel processing across Cloud infrastructure
Memory-mapped I/O and SIMD instructions
This is a key monetization lever

Environment Variables

Variable	Description
`PHONY_API_TOKEN`	API token for authentication
`PHONY_ORG`	Default organization
`PHONY_CONFIG`	Config file path (default: `~/.phony/config.toml`)
`PHONY_CACHE_DIR`	Cache directory (default: `~/.phony/cache`)
`NO_COLOR`	Disable colored output

Configuration File

Located at ~/.phony/config.toml:

toml

[auth]
token = "phony_xxx..."
org = "acme-corp"

[defaults]
locale = "tr_TR"
ngram_order = 3

[output]
format = "text"
color = true

Exit Codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Invalid arguments
`3`	File not found
`4`	Invalid model format
`5`	Authentication required
`6`	API error
`7`	Rate limit exceeded

CLI Reference ​

Installation ​

Verify Installation ​

Command Overview ​

Offline Commands ​

phony train ​

phony info ​

phony validate ​

phony stats ​

Cloud Commands ​

phony login ​

phony logout ​

phony whoami ​

phony models ​

phony sync ​

phony snapshot ​

phony mock ​

phony generate ​

Environment Variables ​

Configuration File ​

Exit Codes ​

CLI Reference

Installation

Verify Installation

Command Overview

Offline Commands

phony train

phony info

phony validate

phony stats

Cloud Commands

phony login

phony logout

phony whoami

phony models

phony sync

phony snapshot

phony mock

phony generate

Environment Variables

Configuration File

Exit Codes