Skip to content

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

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