Skip to content
Arch:Lang

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

Terminal window
npm install -g @archlang/cli

That gives you archlang on your path. Four subcommands:

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

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 kind 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

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

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

service Hello {
    team: Demo
    command 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-kind 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

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