Skip to main content
aspect init scaffolds a new Bazel workspace from the Aspect Workflows template. Pick a language preset, run one command, and you get a working bazel build //... repo with hermetic toolchains, Gazelle-generated BUILD files, aspect format, aspect lint, and a curated bazelrc. Use it when you’re starting a new project, prototyping how a language ruleset fits together, or producing a minimal reproduction for a bug report. The command is native to the CLI — there is no external scaffold binary to install.
aspect init requires Aspect CLI v2026.25.11 or newer. See version pinning to lock a minimum version for your repo, or install to upgrade.

​
Quickstart

# Interactive: pick a preset from a numbered list
aspect init my-app && cd my-app

# Non-interactive: name the preset upfront
aspect init my-app --preset js && cd my-app

# Scaffold into the current directory
aspect init . --preset go
After rendering, aspect init runs tools/repin inside the new workspace to materialize the language lockfiles the template ships as placeholders. The final output points you at the next steps: 
Done. Next steps:
  cd my-app
  aspect build //...

​
Workspace guard

aspect init refuses to scaffold into a directory that already looks like a Bazel workspace. If the target contains a MODULE.bazel, WORKSPACE, WORKSPACE.bazel, or WORKSPACE.bzlmod file, the command exits with a message and does nothing — so running aspect init from inside an existing repo is safe. To start a fresh project, point aspect init at a new directory (aspect init my-app) or cd into an empty one and run aspect init ..

​
Presets

A preset selects which language(s) and tools the scaffolded workspace includes. Pass --preset <name> to skip the interactive picker:
PresetWhat you get
minimalBazel-only scaffold with no language rules — start from scratch.
shellShell scripts (rules_shell) with shellcheck and shfmt.
goGo (rules_go + Gazelle).
jsJavaScript / TypeScript (rules_js, rules_ts, pnpm workspaces).
pyPython (aspect_rules_py + uv).
javaJava (rules_java).
kotlinKotlin (rules_kotlin).
cppC/C++ (rules_cc).
rustRust (rules_rust).
rubyRuby (rules_ruby).
scalaScala (rules_scala).
kitchen-sinkEvery language preset above, wired into one workspace. Useful for exploring or for reproductions that span rulesets.
When you omit --preset, the CLI prints a numbered list and reads your choice from the terminal. Non-TTY invocations (CI, scripts, pipes) must pass --preset=<name> explicitly — the command fails fast otherwise. 
aspect init my-app --preset py
aspect init repro --preset kitchen-sink

​
Flags

​
--preset <name>

The preset to scaffold. Omit for the interactive picker. An unknown name fails with the list of valid presets.

​
--name <project_name>

Override the project name baked into the generated files (module name in MODULE.bazel, package names, etc.). Defaults to the basename of the output directory, normalized to snake_case (hyphens become underscores). When the output directory is . or empty, the default is my_project. 
aspect init . --preset go --name my_service

​
--license <spdx>

Whether to write a LICENSE file. Accepted values (case-sensitive):
  • Apache-2.0 — write the Apache 2.0 license.
  • none — omit the LICENSE file. Default.
aspect init my-app --preset js --license=Apache-2.0
The flag overrides the template’s license feature gate; the default none keeps the scaffold permissive about what you add later.

​
--template <scheme>:<value>

Where to fetch the template tree. The value is a scheme-prefixed locator so new source kinds can be added without changing the flag surface. Two schemes are built in: github:<owner>/<repo> (default: github:aspect-build/aspect-workflows-template) Downloads the template archive from GitHub. By default, aspect init resolves the repo’s latest published release — so an installed CLI picks up template updates without a CLI upgrade. Override the ref with --template-ref <branch|tag|commit>. 
# Default: latest release of aspect-build/aspect-workflows-template
aspect init my-app --preset js

# Track the template's main branch
aspect init my-app --preset js --template-ref=main

# Point at a fork or your own template
aspect init my-app --preset js --template=github:my-org/my-template
file:<dir> (also file://<dir> URI form) Use a local checkout of a template repo. --template-ref is ignored — the directory is read as-is. This is the form to use when you’re developing the template itself or running fully offline. 
aspect init my-app --preset js --template=file:/path/to/checkout
aspect init my-app --preset js --template=file://./aspect-workflows-template
A missing or unknown scheme fails with a clear message (supported: github:, file:).

​
--template-ref <branch|tag|commit>

Override the ref resolved for github: templates. Accepts any value the GitHub archive/<ref>.tar.gz endpoint accepts — a branch (main), a tag (v1.2.3), or a commit SHA. Ignored when --template uses the file: scheme.

​
--skip-repin

Skip the post-render tools/repin step. Use this when you don’t have the lockfile toolchain (uv, pnpm, etc.) installed on your machine yet, or when you want to inspect the generated tree before lockfiles are materialized. 
aspect init my-app --preset py --skip-repin
cd my-app
./tools/repin   # run later, once your environment is ready

​
The post-render tools/repin step

The Aspect Workflows template ships language lockfiles (uv.lock, pnpm-lock.yaml, Cargo.lock, etc.) as placeholders. After rendering, aspect init runs the generated tools/repin script inside the new workspace to populate them so the project is immediately buildable. tools/repin is a regular shell script in the scaffolded tools/ directory; you can run it again at any time after changing dependencies. Pass --skip-repin to opt out of the automatic run — for example when bootstrapping in an environment that doesn’t have the relevant package manager installed yet. If the scaffold doesn’t contain tools/repin (the minimal preset, for example), the step is skipped silently.

​
Examples

Start a JS/TS project, then build it: 
aspect init my-app --preset js
cd my-app
aspect build //...
Pin the template to a known good ref for a bug reproduction: 
aspect init repro \
    --preset kitchen-sink \
    --template-ref=v2026.6.0
Use a fork of the template: 
aspect init my-app \
    --preset go \
    --template=github:my-org/aspect-workflows-template \
    --template-ref=main
Scaffold offline from a local checkout: 
git clone https://github.com/aspect-build/aspect-workflows-template
aspect init my-app \
    --preset py \
    --template=file:./aspect-workflows-template