Quickstart

This guide walks you through creating a Vorpal project, setting up a development environment, building an artifact, and running it. You should have Vorpal installed before continuing.

1. Create your project

Create a new directory and initialize a Vorpal project:

mkdir hello-world && cd hello-world
vorpal init hello-world

The init command prompts you to choose a language for your build configuration — Go, Rust, or TypeScript. Vorpal scaffolds a working project with a Vorpal.toml manifest and a sample build configuration in your chosen language.

2. Develop your project

All vorpal init projects include a language-specific development environment with the relevant toolchain pinned and ready. Activate it:

source $(vorpal build --path hello-world-shell)/bin/activate

This drops you into a shell with your project’s dependencies available — consistent across machines and teammates. To exit the environment, run deactivate or close the shell.

See Environments to learn more about development and user environments.

3. Build your project

Compile your build configuration and produce a content-addressed artifact:

vorpal build hello-world

On the first build, Vorpal downloads the necessary toolchains for your target platforms. Subsequent builds use the local cache — unchanged inputs resolve instantly without re-downloading or re-compiling.

A successful build returns the artifact’s content digest. To get the full filesystem path to the artifact instead, use the --path flag:

vorpal build --path hello-world

To force a fresh build and skip the cache, use --rebuild:

vorpal build --rebuild hello-world

See vorpal build in the CLI reference for all available options.

4. Run your project (optional)

If your artifact produces an executable in /bin with the same name as the artifact, you can run it directly:

vorpal run hello-world

The run command looks up the artifact by name, finds the matching binary in the artifact’s /bin directory, and executes it. This is useful for CLI tools, servers, and any artifact that produces a runnable binary.

See vorpal run in the CLI reference for all available options.

Next steps

Now that you have a working project, explore the SDK guide for your language:

To understand how Vorpal’s build model works under the hood, see the Architecture overview.