tyc CLI Overview

The tyc binary is the compiler, formatter, language server, REPL, migrator, debugger launcher, and package manager. All subcommands share the same Salsa-backed engine, so incremental work is reused across invocations.

Subcommand index

tyc init

Scaffold a new project — typhon.toml, src/, tests/. Reference →

tyc check

Type-check without emitting .py. CI’s command. Reference →

tyc build

Full pipeline: parse → check → analyse → desugar → emit → format. Reference →

tyc fmt

Format .ty source in place. Reference →

tyc run

Execute a Typhon program in the in-process VM (default) or via --compile for CPython interop. Reference →

tyc lsp

Language Server on stdio. Diagnostics, hover, completion, code actions. Reference →

tyc repl

Interactive evaluator. Reference →

tyc debug

Build then launch the emitted Python under pdb; --break <ty>:<line> translates source-mapped breakpoints. Reference →

tyc trace

Map a Python traceback back to .ty source via .py.map. Reference →

tyc profile

Instrument top-level functions; write typhon-profile.json. Reference →

tyc migrate

Convert typed .py to .ty — Optional[T] → T?, add let/mut, drop @dataclass. Reference →

tyc ty

Build and run Astral’s ty checker over the emitted Python. Reference →

tyc stubtest

Runtime probe via python -m mypy.stubtest against emitted .pyi. Reference →

tyc explain

Print the diagnostic catalog entry for a tyc:: code. Mirrors rustc --explain. Reference →

tyc cheatsheet

Print the 30-second Typhon syntax refresher to stdout. Reference →

tyc add / remove / sync

Package-manager surface over uv. Reference →

tyc install skill

Write the embedded typhon Claude skill into a project’s .claude/skills/typhon/. Reference →

Typical workflow

# Once per project
tyc init myapp
cd myapp

# Daily loop
tyc fmt src/
tyc check src/      # ← fast feedback
tyc run             # ← in-process VM, no build dir
tyc build           # ← when you need emitted .py on disk

When your program imports a module the VM doesn’t model (numpy, requests, sqlite3, re, …), tyc run notices before it starts and takes the build-then-exec path itself, printing a note:; tyc run --compile forces that path, and --no-fallback forbids it. See tyc run.

In CI

tyc check is the recommended CI command. It runs everything up to the analyser without producing artefacts:

- name: Typhon type-check
  run: tyc check src/

For projects shipping .dty stubs, add tyc check --stubs to catch drift, and tyc stubtest for runtime introspection (requires mypy).

Global flags

Flag	Effect
`--help` / `-h`	Print help for a command.
`--version` / `-V`	Print `tyc` version (also accepted after any subcommand).

Those two are the only global flags. There is no --quiet / --verbose / --color switch — diagnostics always render through miette with its built-in ANSI heuristics — and no --manifest override: every command discovers typhon.toml by walking up from the path it was given (pass a project directory to target a different project). Per-command flags are documented on each command’s page; the one logging knob is tyc lsp --log-level.

Exit codes

Code	Meaning
0	Success.
1	Failure — at least one error-severity diagnostic, invalid input, a missing manifest or required tool, or a `tyc fmt --check` that would reformat.
2	Invocation error — bad arguments or an unknown subcommand (reported by the argument parser).
130	Interrupted (Ctrl-C).

tyc run propagates the child program’s exit code instead of overriding (the VM exits with the script’s terminating exit code; --compile mode propagates the child Python’s exit code).

See Exit Codes for the full table.

`tyc install skill`

tyc install skill [--dir DIR] [--force] [--list]

Writes the embedded typhon Claude skill — SKILL.md, its sibling reference files, and the references/ example programs — into <DIR>/.claude/skills/typhon/ (default: the current directory). The skill is compiled into the binary, so the command works offline and always matches the tyc you ran.

Flag	Effect
`--dir DIR` (`-d`)	Project root to install into. Default `.`.
`--force`	Overwrite an existing copy. Without it the command refuses when `.claude/skills/typhon/SKILL.md` already exists, so a customised copy is never clobbered.
`--list`	Print the files that would be written, then exit without touching disk.

Where next

tyc check — daily-loop type checking.
tyc build — full pipeline.
tyc run — build + exec.
tyc lsp — editor integration.