Get started

Install the Super CLI and check your first supertest. Use your own code or try the example project from Welcome to Super CLI.

Using an AI agent?

Give your agent the Super CLI skill to handle setup, write supertests, and run checks for you.

Language support#

Schematic supports the following languages:

Choose your language (currently Python) to see the relevant instructions and examples throughout the docs. You can change this anytime using the language selector in the navigation menu or a code snippet.

Install the Super CLI#

Run commands with super (or sup for short).

Run the Super CLI installer:

$ curl -fsSL https://get.schematic.tech/cli.sh | sh

Follow the installer’s instructions, including restarting your terminal if requested. Then check the installed version:

$ super --version
  super 0.9.1

Log in to Schematic#

Sign in to platform.schematic.tech and generate an API key. Then run super login and enter the key when prompted:

$ super login
  ? Schematic API key › [hidden]
  ✓ Logged in as you@example.com

Prepare your project#

Use your own project by adding supertest support below, or set up the example for your language instead. Choose your language (currently Python) to see the setup instructions for your project. You can also change it anytime using the language selector in the navigation menu or a code snippet.

Add supertest support#

Install schematic-supertest in your project’s active Python environment (Python 3.11 or later). The package provides @supertest and assume.

Add schematic-supertest as a development dependency in your Cargo project. The crate provides #[supertest] and assume, imported from schematic. Use Rust 1.85 or later.

Add schematic.h to your project and put its directory on your compiler’s include path. The header provides SUPERTEST and SUPERTEST_ASSUME. You can download the header or use the commands below.

Use #include <schematic.h> in your supertest and compile with -Iinclude.

Run these commands in the .NET project that compiles your supertests. SchematicTech.Supertest provides [Supertest] and Assumptions.Assume. The examples also use xunit.v3.assert for assertions.

Install schematic-supertest as a development dependency in your JavaScript project. The package provides supertest and assume. Use Node.js 22 or later. The examples use ES modules, with "type": "module" in package.json.

Add these entries to the <dependencies> section of your Maven project’s pom.xml. The supertest package provides @Supertest and Assumptions.assume. The examples use JUnit for assertions.

Analyze schematic.vhd into the same work library as your supertests using VHDL-2008. The package provides supertest_assume. Mark each supertest process with --% supertest. You can download the package or use the commands below.

$ python -m pip install schematic-supertest

$ cargo add --dev schematic-supertest

$ mkdir -p include
$ curl -fsSL https://raw.githubusercontent.com/schematic-tech/supertest-c/v0.1.1/include/schematic.h -o include/schematic.h

$ dotnet add package SchematicTech.Supertest
$ dotnet add package xunit.v3.assert

$ npm install --save-dev schematic-supertest

<dependencies>
  <dependency>
    <groupId>tech.schematic.supertest</groupId>
    <artifactId>schematic-supertest</artifactId>
    <version>0.1.0</version>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>4.13.2</version>
    <scope>test</scope>
  </dependency>
</dependencies>

$ mkdir -p include
$ curl -fsSL https://raw.githubusercontent.com/schematic-tech/supertest-vhdl/v0.1.1/src/schematic.vhd -o include/schematic.vhd
$ ghdl -a --std=08 include/schematic.vhd

We recommend keeping supertests in tests/. Run cargo check --tests to check that they compile. Use super check to submit them for checking; cargo test does not run functions marked only with #[supertest].

We recommend keeping supertests in src/test/java/, where Maven makes these test dependencies available.

You can use your project’s existing assertion library instead of adding the one used in these examples.

Include use work.schematic.all; in the context of each design unit that calls supertest_assume. Analyze the package before those design units, using the same work library and VHDL standard.

Then write a supertest for your code and link your repository.

Set up the example project#

The example includes a small program with a bug and a supertest that exposes it.

Clone the supertest library for your language and prepare its text-tools example:

With GHDL and Make installed, clone the supertest library and prepare its saturating-increment example:

Use the .NET 8 SDK to build this example.

Use Node.js 22 or later to build this example.

Use JDK 17 or later. On Windows, use mvnw.cmd in place of ./mvnw.

$ git clone https://github.com/schematic-tech/supertest-python.git
$ cd supertest-python/examples/text-tools
$ python3 -m venv .venv
$ source .venv/bin/activate
$ python -m pip install -r requirements.txt

$ git clone https://github.com/schematic-tech/supertest-rust.git
$ cd supertest-rust/examples/text-tools
$ cargo check --tests

$ git clone https://github.com/schematic-tech/supertest-c.git
$ cd supertest-c/examples/text-tools
$ make

$ git clone https://github.com/schematic-tech/supertest-csharp.git
$ cd supertest-csharp/examples/text-tools
$ dotnet build -c Release

$ git clone https://github.com/schematic-tech/supertest-javascript.git
$ cd supertest-javascript
$ npm ci
$ npm run build
$ cd examples/text-tools

$ git clone https://github.com/schematic-tech/supertest-java.git
$ cd supertest-java
$ ./mvnw install
$ ./mvnw -f examples/text-tools/pom.xml test-compile
$ cd examples/text-tools

$ git clone https://github.com/schematic-tech/supertest-vhdl.git
$ cd supertest-vhdl/examples/saturating-increment
$ make

Link your repository#

Super CLI links the whole Git repository, even when you run it from a subdirectory, and syncs its current committed source to Schematic. See Source and commits for which files the CLI includes and how to exclude files.

The repository needs at least one commit, which a clone already has. From the directory you want to check, run:

$ super link .
  ✓ Linked supertest-python · main · 8e44bea
  Next: super check

$ super link .
  ✓ Linked supertest-rust · main · 8e44bea
  Next: super check

$ super link .
  ✓ Linked supertest-c · main · 8e44bea
  Next: super check

$ super link .
  ✓ Linked supertest-csharp · main · 8e44bea
  Next: super check

$ super link .
  ✓ Linked supertest-javascript · main · 8e44bea
  Next: super check

$ super link .
  ✓ Linked supertest-java · main · 8e44bea
  Next: super check

$ super link .
  ✓ Linked supertest-vhdl · main · 8e44bea
  Next: super check

Your repository name, branch, and commit may differ from the example output.

Run a check#

Run your first check from your project directory:

$ super check .

The . selects supertests in the current directory and its subdirectories. See the super check reference for options and other ways to select supertests.

The Welcome to Super CLI walkthrough follows the example through finding a bug, reviewing a fix, and verifying the corrected behavior.

Where to go next#

• Writing supertests explains inputs, assumptions, and assertions.
• Using AI agents shows how an agent can help you set up Super CLI, write supertests, and run checks.
• Check commands covers selecting supertests, following progress, and reviewing results.