> Markdown rendition of https://typeglish.dev/docs/quickstart ("Quickstart — TypeGlish docs"). Canonical page: https://typeglish.dev/docs/quickstart · All pages: https://typeglish.dev/docs/llms.txt Getting started # Quickstart Five minutes, no install: write a short prompt, read its review, watch the checker *prove* a contradiction, then pin the fix with a test and ship the build artifact. Every output below is captured from the real CLI and locked by a test. ### Run it (no install needed) TypeGlish is an npm package; `npx typeglish …` cold-starts it in seconds. Needs Node 20.19+; the Z3 proof tier comes with it. Two commands teach the whole language: shell ``` $ npx typeglish --help $ npx typeglish reference # the full language, one command: read its "Start here" first ``` `reference` is long (the whole language); its first section, *Start here*, is a copyable skeleton plus what counts as a rule — the part that covers the first hour. In a project, pin a version with `npm i -D typeglish`; every command below works the same way through `npx`. ### Write your first prompt Near-plain English. A prose `# Role` says who the agent is; the rules lead with a modal (`MUST` / `NEVER` / `SHOULD`) or a verb. Save as `hello.tg`: hello.tg ✓ compiles ```typeglish # Role You are a support agent for Acme, a SaaS analytics company. # Constraints - MUST keep every reply to at most 3 sentences. - ALWAYS escalate a refund request to a human. ``` Review it — one run says what the checker read, what it proved, and what would raise the grade: shell ``` $ npx typeglish review hello.tg hello.tg — B (87/100) → A (99) projected if every fix below lands check: 0 error, 0 warning, 0 info tiers: base+z3 FIXES ranked by projected gain +12 put a "@@ why" note above L2 L5 L6 — annotation 0 → 100 RULES 2 of 2 rule-shaped lines read TESTS no $TEST cases — add one beside a rule; `test --dry` validates it offline ``` Both rules were read as rules (the RULES line), nothing needs proving yet, and the one edit that would move the grade is named with its lines. `check`, `score`, and `test --dry` are the same three views, one per command. ### Break it, on purpose Add a rule that argues with one you already have, then compile again: shell ``` $ echo "- NEVER escalate a refund request to a human." >> hello.tg $ npx typeglish check hello.tg hello.tg:6:1 error logic/contradiction Conflicts with line 7. Logical conflict — "escalate a refund request to a human." is both required and forbidden. Keep one, or scope the two rules so they cannot both apply (IF THEN ...). ↳ line 7: - NEVER escalate a refund request to a human. hello.tg:7:1 error logic/contradiction Conflicts with line 6. … ↳ line 6: - ALWAYS escalate a refund request to a human. ✗ 1 file — 2 error, 0 warning, 0 info ``` That refusal is the product: the contradiction is *proven* at compile time (by Z3), not left for the model to resolve differently every conversation. Each end of the pair cites the other and quotes it. `npx typeglish --explain logic/contradiction hello.tg` spells out any code and, with the file, shows every place it fires. ### Fix it, annotate it, pin it, ship it Delete the conflicting line (or scope one with `IF` / `UNLESS`). Take the review's fix — a `@@ why` note above each rule: stripped before the model reads it, worth 12 points of the grade. Then pin the behavior with a `$TEST` so the agent can't drift: hello.tg — final ✓ 1 test ```typeglish # Role You are a support agent for Acme, a SaaS analytics company. # Constraints @@ brevity: three sentences keeps support replies scannable - MUST keep every reply to at most 3 sentences. @@ escalation: a refund is a human decision, not a chatbot one - ALWAYS escalate a refund request to a human. $TEST escalation - input:: I want a refund - can I talk to someone? - expect:: - offers to escalate the request to a human ``` shell ``` $ npx typeglish test hello.tg --dry ✓ hello.tg coverage: 1/2 rules exercised uncovered (no case shares the rule's wording): L6 keep every reply to at most 3 sentences. · escalation — "I want a refund - can I talk to someone?" (not run) · rubric — 1 prose expectation, judged on a live run (needs ANTHROPIC_API_KEY) ✓ 1 prompt — 0 failed $ npx typeglish score hello.tg hello.tg — A (96/100) proven errors: none tiers: base+z3 planes runtime 100 (what the model reads) · hygiene 84 (source only) facets … lever annotation 67/100 (up to +4 overall) — 1 statement without a @@ note (L2) — put a "@@ why" line directly above each rules 2 of 2 rule-shaped lines read · 1/2 covered by $TEST $ npx typeglish build hello.tg ✓ built .typeglish/dist/hello.txt ← hello.tg (42ac8712ae03, full) ``` `--dry` validates the suite offline and names the rule no case exercises yet; a live run sends each case to a model (`ANTHROPIC_API_KEY`). The remaining four points are the role line's missing `@@` note (the lever row). `build` writes the deployable prompt plus `.typeglish/build-manifest.json` (source and artifact hashes, the check that passed) — the artifact is the role and the two rules, with the `@@` notes and the `$TEST` stripped. Deploy that file, never the `.tg`. ✓ You compiled, broke, proved, annotated, tested, and built a prompt. The loop is `edit → review → build`; `review` is `check` + `score` + `test --dry` in one report, fixes ranked by what they are worth. ## The shapes the checker reads Enforceability — the biggest facet of the grade — is the share of your rule-shaped lines the checker can read and prove. Every line of `review`'s RULES table names its own edit; these are the patterns behind them: - **Read:** \ \ \ [bound] (`MUST keep every reply to at most 3 sentences.`); a bare catalog imperative heading a line (`Escalate to a human.`); IF / WHEN / UNLESS … THEN \ — the modal (or the bare catalog imperative) goes AFTER THEN (`IF the customer is angry THEN escalate to a human agent.`). - **Not read (reported as `prompt/unparsed-rule`):** a frequency word in the modal slot (`USUALLY offer a replacement before a refund.` → `SHOULD offer a replacement first.`); a statement about the agent with no modal — it describes, it does not require (`You reply politely.` → `You MUST reply politely.`); a THEN branch whose head is not a catalog verb (`IF the customer seems upset THEN be extra careful.` → `IF the customer seems upset THEN MUST apologize once.`). - **Read but not provable:** two objects joined by "or" — one object per line (`NEVER share internal notes or another customer's information.` → `NEVER share internal notes.`); an adverb between the modal and the verb — put it after the object (`MUST politely redirect the customer to lighting.` → `MUST redirect the customer to lighting politely.`); a trailing before / after / unless clause — make it the condition (`ALWAYS cite the order number before stating an order status.` → `WHEN stating an order status THEN MUST cite the order number.`). - **The agent's name is the agent:** after `You are Nova, …`, `Nova MUST …` is the addressee speaking, not a stray third party. ## Troubleshooting **typeglish: command not found** It's a dev dependency, not a global — run it through `npx typeglish …` (or add a script to `package.json`). Confirm it installed with `npx typeglish --version`. **A prompt that "worked fine yesterday" now fails to compile** It probably did — the model was resolving the conflict silently, a coin flip per conversation. The checker just made the coin flip visible. The error names the conflicting rule and the shared action; scope one rule with `IF` / `UNLESS`, or delete it. **A line I meant as a rule got `prompt/unparsed-rule`** The rule reader read it as prose, so it earns no Enforceability credit and no measurability check (the logic plane may still weigh it — a frequency word sits on the occasion square). The finding names the reason and the edit — usually a modal after `THEN`, a modal instead of a frequency word, or `You MUST …` instead of `You …`. `review` lists every such line under RULES. **Checking an existing prose prompt** `npx typeglish check prompt.md` reads plain English as-is. Ungraded imperatives and hedges come back as advisory findings — grade the ones that matter with a modal and leave the rest. `npx typeglish score prompt.md` gives you a number to improve against. ## Where next ### [⌘`npx typeglish reference`The whole language in one command — a copyable skeleton first, then statement shapes, every operator, every diagnostic code. Read its *Start here* first.](https://typeglish.dev/docs/cli#commands) ### [§The languageStatements, modality, control flow, types — how English becomes checkable clauses.](https://typeglish.dev/docs/statements) ### [✓TG scoreThe facets behind that grade, what each one measures, and the fixes `review` ranks to raise it.](https://typeglish.dev/docs/score) ### [⚑CLI flagsEvery flag by command — `--fix`, `--min`, `--vars`, `--explain [file]`, `--json` — with what each changes.](https://typeglish.dev/docs/cli#flags) [← Previous Introduction](https://typeglish.dev/docs/) [Next → Statements](https://typeglish.dev/docs/statements)