GET STARTED · 5 min read

Quickstart

Scaffold a wiscarch course, add an assignment, and run the autograder locally — end-to-end in about five minutes. Designed for instructors prepping a semester or students poking at a single exercise.

Note wiscarch is an academic project, not affiliated with the official University of Wisconsin–Madison. The CLI is MIT licensed and runs entirely on your machine.

Prerequisites

You'll need a recent Node runtime and a POSIX shell. For the FPGA flow, an additional toolchain install is required — covered separately in the FPGA toolchain guide.

Node.js	≥ 20.0	For the CLI and the static sims.
Git	≥ 2.30	The CLI scaffolds from a template repo.
Docker	optional	Required only for self-hosting the autograder.
Verilator	≥ 5.0 (opt.)	For local RTL simulation. Skip to grade in browser.

Install the CLI

The wiscarch CLI is a single npm package. Install it globally so the wiscarch command is on your PATH.

~/courses/ece-352 — zsh

$ npm install -g @wiscarch/cli

added 142 packages in 8s

$ wiscarch --version

1.0.2

Prefer not to install globally? Every command in this guide also works under npx @wiscarch/cli@latest.

Scaffold a course

The new command clones a template, wires up the autograder, and links the simulators. Templates exist for each of the supported themes.

~/courses

$ wiscarch new ece-352 --from-template digital-logic

✓ scaffolded into ./ece-352

✓ autograder configured (verilator backend)

✓ simulators linked (logic, riscv)

✓ initialized git repo

Available templates: digital-logic, verilog-hdl, architecture, fpga, capstone. Run wiscarch templates for the full list.

Add an assignment

Assignments are folders under ./assignments/ with a Verilog source, a testbench, and a small YAML manifest. The CLI generates the scaffolding from one of the assignment archetypes.

~/courses/ece-352 — zsh

$ cd ece-352

$ wiscarch add assignment hw1-adder --type combinational

created assignments/hw1-adder/

├── adder.v # student stub

├── adder_tb.v # graded testbench

└── manifest.yaml # grading rubric

Run it locally

wiscarch dev starts a local server that hosts the simulators and exposes the autograder over HTTP. Hot-reloads on edit.

~/courses/ece-352 — zsh

$ wiscarch dev

▸ wiscarch dev · 1.0.2

autograder http://localhost:4001

simulators http://localhost:4002

course site http://localhost:4000

watching ./assignments, ./content …

Visit localhost:4000 to see the course site, then submit your stub adder to the autograder to confirm everything is wired up.

Deploy

Two supported targets out of the box. Pick whichever your institution prefers — both produce the same student-facing experience.

Docker compose

wiscarch deploy docker

Self-host on a single VM. Includes the autograder, sims, and Postgres for course management.

Vercel

wiscarch deploy vercel

Static site + serverless autograder. Free tier covers small cohorts.

Next steps

You're set up. The pieces below are independent — read them in any order.

Quickstart guide ~/start 5 min → Browse all exercises /exercises Reference → Try a simulator /sim/riscv 2 min → Instructor handbook /handbook 20 min → GitHub: monorepo github.com/wiscarch External →

← Previous

Overview

Installation