foreignthon-docs/docs/cli-reference.md

CLI Reference

All commands support -h / --help.

---

fpy new

Scaffold a new ForeignThon project.

fpy new <name> --lang <code>       # create in new directory
fpy new --lang <code>              # initialize current directory (must be empty)
fpy new <name> --lang <code> --no-git
fpy new <name> --lang custom       # scaffold a blank language pack

Flag	Description
--lang, -l	Language code — required
--no-git	Skip git init and initial commit

!!! note "Using --lang custom" Prompts for a language code, English name, and native name. Creates a custom.json with all Python keywords pre-filled as stubs and wires it up in .foreignthon.toml automatically.

---

fpy run

Transpile and run a source file.

fpy run script.es.py
fpy run script.py --lang es        # override language detection
fpy run script.es.py --keep        # also write the compiled .py to disk

Flag	Description
--lang, -l	Override language detection
--keep	Write .compiled.py alongside source after running

---

fpy compile

Transpile to standard Python without running.

fpy compile script.es.py                 # → script.compiled.py (same directory)
fpy compile script.es.py -o dist/        # → dist/script.compiled.py
fpy compile script.es.py -o output.py    # → output.py

Flag	Description
--output, -o	Output file or directory

---

fpy decompile

Convert standard Python back to a foreign language. Keywords and builtins are translated — variable names are untouched.

fpy decompile script.py --lang es
fpy decompile script.py --lang es --postfix
fpy decompile script.py --lang es -o out/

Flag	Description
--lang, -l	Target language — required
--postfix	Rewrite conditionals to @@ postfix style
--output, -o	Output file or directory

!!! note Decompile is lossy — variable names and comments are not translated back. It is useful for bootstrapping a foreign-language version of an existing Python file, not as a perfect round-trip.

---

fpy check

Validate syntax without running.

fpy check script.es.py
# ✓ script.es.py looks good.
# or
# ✗ Syntax error: invalid syntax (script.es.py, line 4)

Exits with code 1 on failure — useful in CI pipelines.

---

fpy pack

Validate a language pack JSON file against the required schema.

fpy pack mylang.json
# ✓ Pack 'Russian' is valid.
# or
# ✗ Missing sections: {'error_messages'}

---

Language detection order

When running a file, ForeignThon resolves the language in this order:

1. --lang flag (highest priority)
2. Shebang comment: # foreignthon: es
3. File extension: .es.py → es
4. .foreignthon.toml in the project root