Gram

English

Français

English

Français

Appearance

Getting Started ​

This guide will help you install the Gram ecosystem and compile your first recipe.

1. Installation ​

Install the gram CLI globally with your package manager of choice — it runs on both Node.js (>=20) and Bun:

bash
npm install -g @gram-lang/cli
# or
bun add -g @gram-lang/cli

NOTE

Want to build the CLI from source instead (e.g. to contribute to the project)? See CONTRIBUTING.md.

2. Editor Setup ​

Because Gram treats recipes as code, having the right editor makes a huge difference.

Gram VS Code Extension

Installing the Gram VS Code Extension is highly recommended. It provides:

  • Syntax highlighting
  • Auto-completion
  • Inline diagnostics and error checking
  • Real-time compiler feedback

Search for "Gram - Recipe Language" in the Extensions view (Ctrl+Shift+X / Cmd+Shift+X) and install it, or grab it directly from the VS Code Marketplace.

Building from source instead
bash
git clone https://codeberg.org/abiwab/gram.git
cd gram
bun install

# Build the extension package (this generates a .vsix file)
cd packages/vscode-extension
bun run package

# Install the package in VS Code
code --install-extension gram-lang-*.vsix

3. Initializing a Project ​

Before writing any recipe, it's highly recommended to initialize a Gram workspace. Run this command in a new folder:

bash
gram init

This command scaffolds a .gram/ directory with a configuration file and a starter database.

Interactive Setup

The CLI will ask you a few questions to configure your AI provider (used later for advanced features like database enrichment or importing recipes). You don't need this for your first recipe! Feel free to just press Enter to skip or accept the defaults for now.

4. Writing Your First Recipe ​

Let's make some pancakes, shall we?

Create a new file named pancakes.gram, open it in the editor, and add the following basic recipe:

gram
---
title: Pancakes
portions: 2
---

## Batter ->&batter

In a #medium bowl{}, mix the @flour{160g}, @baking powder{1 tsp}, @sugar{1 tbsp} and @salt{1/4 tsp}. ->&dry mix{}

To the &dry mix{}, add the @buttermilk{1 cup}, @egg{1} and the @vanilla extract{1/2 tsp}.

## Cooking

Pour the &batter on a #griddle on ^{medium heat} and cook for ~{2min}.

5. Compiling the Recipe ​

Time to see the compiler in action!

Run the following command in the terminal to compile the recipe into a structured JSON format:

bash
gram build pancakes.gram

This command will parse the recipe and output its structured JSON representation. By default, it prints to the console, but you can save it to a file:

bash
gram build pancakes.gram -o pancakes.json

While the JSON output is incredibly useful for building applications around Gram, it is not the most readable format for humans!

To see your recipe rendered directly in your terminal, you can use the view command:

bash
gram view pancakes.gram

Alternatively, to see it come to life with a fully formatted visual interface, it is highly recommended to open the recipe using the VS Code Extension or the Web Playground.

Try the playground

If you don't want to install anything yet, you can try writing Gram directly in the web-based Playground.

Next Steps ​

Now that you have written your first recipe, it's time to dive deeper into the syntax: