Set up the project with one prompt

The environment is a repository

Everything in this course lives in a folder on your machine, tracked by Git. There is a config file, a folder of assets, and a local database file. Nothing is hidden inside a web app, which is what lets you read and check every step.

This lesson is the longest setup you will do, and you do it once. By the end you have a terminal you can use, three tools installed, a project scaffolded, and 1,200 orders of sample data to query. The last step is also your first AI lesson: you give one prompt, the agent does the work, and then you read what happened. That order - delegate, then verify - is the whole course in miniature.

Open a terminal

A terminal is a window where you type a command, press Enter, and read the text that comes back. Every command in this course is copy-pasteable, one at a time.

macOS. Press Cmd+Space, type Terminal, press Enter.
Windows. Install Git for Windows first (next section - it is one installer), then open Git Bash from the Start menu. Use Git Bash for every command in this course. The regular Command Prompt and PowerShell will not run the install script below. WSL also works if you already use it.
Linux. Any shell you already have.

Two habits that prevent most beginner frustration: paste commands exactly, and read the output before running the next one. The output is the tool talking to you.

You also need two navigation commands, because a terminal is always "in" a folder and most commands only work from the right one. pwd prints the folder you are in. cd some-folder moves you into a folder (and cd .. moves you up one). If a command in this course ever fails with an error like "no git repository found" or "cannot find a pipeline", you are almost certainly in the wrong folder - run pwd, then cd back to the course folder.

Install the three tools

1. Git

Git tracks versions of files. Bruin needs it to create a project, and your agent will use it to keep your work safe. Check whether you already have it:

git --version

If a version prints, move on. If not: on macOS a dialog offers to install the command line developer tools - accept it and wait a few minutes. On Windows, Git for Windows gave you both Git and the Git Bash terminal in one installer. On Linux, install git with your package manager.

You do not need to know how to use Git. One prompt later in this lesson has the agent set it up while you watch.

2. An AI coding tool

You need one of these installed. Any of the three works with everything in this course, because they all do the same thing here: read the project's files and run terminal commands.

Claude Code - runs in the terminal. After installing, typing claude in a folder starts it there.
Cursor - a code editor with the agent built in. You open a folder, then open the chat panel.
Codex - runs in the terminal, like Claude Code. Start it with codex.

Follow the install steps on the tool's own page, then confirm it starts before continuing. If you already use one of them, keep it.

3. The Bruin CLI

Bruin is the command-line tool that runs your queries and builds the project. Install it, then confirm it runs:

curl -LsSf https://getbruin.com/install/cli | sh
bruin version

bruin version should print a version number. Two common hiccups:

bruin: command not found - the installer finished but your terminal has not picked it up yet. Close the terminal, open a new one, try again. A fresh terminal starts in your home folder, so cd back to wherever you were working.
Permission denied during install (macOS and Linux) - rerun the first command with sudo in front of sh: curl -LsSf https://getbruin.com/install/cli | sudo sh.

What about the database? Nothing to install. The DuckDB engine ships inside Bruin, so if bruin version works, your warehouse works.

Create the project

Create the course project from the template. Run this from your home folder, or wherever you keep projects - the folder you are in is where the project will land:

bruin init academy-sql-beginner

The command creates a bruin/ folder in the directory you ran it from. That folder is the project root: it holds the config file, a Git repository, and inside it, the course folder.

bruin/                        <- project root: config + Git live here
├─ .bruin.yml                 <- the connection config (already set up, no credentials needed)
├─ .gitignore
└─ academy-sql-beginner/      <- the course folder: everything you work with
   ├─ README.md
   ├─ AGENTS.md
   ├─ .gitignore
   ├─ docs/
   │  ├─ failure-modes.md
   │  ├─ schema.md
   │  ├─ writing-an-asset.md
   │  ├─ data-design.md
   │  └─ known-defects.md
   ├─ queries/
   │  ├─ 01-first-look.sql
   │  ├─ 02-aggregates.sql
   │  ├─ 03-joins.sql
   │  ├─ 04-cte.sql
   │  ├─ anchors.md
   │  ├─ audit-template.md
   │  └─ audit-lab/
   │     ├─ README.md
   │     ├─ q01.sql ... q10.sql
   │     └─ findings-template.md
   └─ pipeline/
      ├─ pipeline.yml
      └─ assets/
         ├─ dates.sql
         ├─ stores.sql
         ├─ products.sql
         ├─ customers.sql
         ├─ orders.sql
         └─ order_items.sql

Move into the course folder - this is where you will spend the entire course:

cd bruin/academy-sql-beginner

bruin init prints three "Next steps" when it finishes. Read them, but they do not quite apply to this template - now that you are inside the course folder, do this instead:

What init prints	What to do instead
"Add your connection credentials to `.bruin.yml`"	Nothing. This project needs no credentials - the DuckDB connection is a local file path and it is already configured.
"Run: `bruin validate bruin/academy-sql-beginner`"	That path only works from the folder you ran init in. From inside the course folder, run `bruin validate pipeline/pipeline.yml`.
"Run: `bruin run bruin/academy-sql-beginner`"	Wrong path - the pipeline lives one level deeper. From inside the course folder, run `bruin run pipeline/` as below.

Load the data

From inside bruin/academy-sql-beginner, generate the sample data:

bruin run pipeline/

The data is generated by SQL, not downloaded, so this finishes in well under a second and works offline. The output should end with all six assets succeeding and eleven quality checks passing. When it completes, orders holds 1,200 rows and order_items holds 2,880.

The database itself is a single file, academy.duckdb, written to the bruin/ project root. It is listed in .gitignore, so it never gets committed - generated data belongs in no one's version history.

Optional: use a cloud warehouse instead

The template ships an optional MotherDuck environment for anyone who wants a real cloud warehouse. MotherDuck is DuckDB-compatible, so the only change is one flag: bruin run pipeline/ --environment cloud, after setting a MOTHERDUCK_TOKEN. Everything in this course works the same on either path, and nothing later requires it.

Start your agent in the course folder

Where you start the agent matters: it works relative to the folder it is opened in, and this project's AGENTS.md file - the instructions that turn it into a SQL instructor - only takes effect when the agent is started inside the course folder.

From inside bruin/academy-sql-beginner:

Claude Code: type claude and press Enter.
Cursor: File, Open Folder, find the bruin folder wherever you ran init (your home folder, if you followed along), select academy-sql-beginner inside it, then open the chat panel.
Codex: type codex and press Enter.

Once the agent starts, your terminal changes: you are now typing to the agent, not to the shell. Everything in a prompt box below goes to the agent as one message. When you want the plain terminal back, quit the agent - /exit in Claude Code or Codex, or just open a second terminal window and keep the agent running in the first.

One expectation to set: the Git repository sits at bruin/, one level above the folder the agent is working in. Some agents ask for permission before touching anything outside their folder. That is the agent being careful, not broken - say yes.

Now give it your first prompt:

AI Prompt

Set up this project so I can start querying. Specifically:

Confirm bruin version runs and tell me the version.
Read the README in this folder and summarise in four bullets what this project contains.
Confirm the sample data is loaded by reporting the row count of every table. If any table is missing, run the pipeline to generate the data.
Tell me the name of the DuckDB connection I should use with bruin query.

Show me each command before you run it. Do not modify any SQL files. If a command fails, stop and explain the error instead of trying something else.

Then set up version control so your own work is tracked separately. bruin init already created a Git repository at the project root, but it has no history yet. One heads-up: on a machine where Git was just installed, Git asks once for your name and email before it accepts a first commit - the prompt below tells the agent to handle that with you rather than around you:

AI Prompt

This project sits inside a Git repository (one level up, at the project root) that has no commits yet. Make an initial commit of the project as it is now, then create a branch called my-first-queries and switch to it. If Git complains that it does not know who I am, show me the two git config commands that set my name and email, and let me confirm the values before you run them. Show me git status when you are done. Explain in two sentences what a commit is and what a branch is, and why I want this branch. Do not change any files.

Read what the agent does, not just its summary. It should show each command before running it - that is the deal you just set, and holding it to that deal is the skill this course teaches.

Checkpoint

Confirm all four before moving on. The first two you have already run. The last two you can check yourself, from inside bruin/academy-sql-beginner, without trusting the agent's word for it:

bruin version succeeds.
bruin validate pipeline/pipeline.yml succeeds from inside bruin/academy-sql-beginner.
orders contains 1,200 rows. Check: bruin query --connection duckdb-default --description "checkpoint" --query "SELECT COUNT(*) FROM orders;" - the next lesson explains this command in full.
You are on a branch called my-first-queries. Check: git branch --show-current.

Set up the project with one prompt

Sign up to our newsletter