Skip to content
ArchLang

1. Setup

You need three things to work in ArchLang:

  1. The CLI, for validating and formatting files.
  2. An editor with the language server attached, for completion and diagnostics.
  3. A viewer to see the diagrams your files render to.

This chapter installs all three. If you already have them, skim and continue to Chapter 2.

The CLI

Section titled “The CLI”
Terminal window
npm install -g @archlang/cli

That gives you archlang on your path. The subcommands you’ll reach for first (see Chapter 21 for the full set):

Terminal window
archlang info     path/to/package    # summarize a package
archlang validate path/to/package    # validate; exits non-zero on errors
archlang check    path/to/package    # validate + run derived checks
archlang format   path/to/file.arch  # canonical formatting (mints stable IDs)

archlang validate accepts --watch to re-run on every file change. archlang format accepts --check (exit non-zero if anything would change) and --diff (print what would change without writing).

You’ll use format constantly — it mints the stable IDs introduced in Chapter 13, so most files in this book are written without IDs and gain them on first save.

Editor

Section titled “Editor”

Two editors are supported as first-class clients of the ArchLang language server:

  • VS Code — install the ArchLang extension from the marketplace.
  • JetBrains (IDEA, WebStorm, GoLand, …) — install the ArchLang plugin from the JetBrains plugin marketplace.

Both give you completion of type names, hover documentation, go-to-definition for cross-module references, validation diagnostics, and inline diagram preview.

If your editor isn’t on that list, the LSP can be attached manually — see Tools → LSP.

Viewer

Section titled “Viewer”

The web viewer renders any package or single file. Two ways to reach it:

The editor extensions ship an inline preview pane that re-renders on every save, so for local work that’s usually the right tool.

Verify

Section titled “Verify”

Create an empty directory, drop in a single file hello.arch:

service Hello {
    aspect team: "Demo"
    rest_create greet
}

Run:

Terminal window
archlang validate .

If you see no output and the command exits cleanly, you’re set. If you see STDLIB_NOT_FOUND or a missing-type error, the toolchain doesn’t know what service is yet — your package needs a manifest. We’ll add one in the next chapter.

What’s next

Section titled “What’s next”

Chapter 2: Your First Architecture → — build a small system, render it, change it, watch it update.