# CLI Reference

All commands support `-h` / `--help`.

---

## `fpy new`

Scaffold a new ForeignThon project.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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