Command line

Source code

Compile, check, format, run and test what is in the tree. Every command takes the current directory as its tree unless a path or names say otherwise.

adm build

adm build [targets...] [flags]

Builds the applications, libraries and plugins found in a source tree. Without names every unit is built; names select units of any kind, a directory or .adm file argument is the source path. An application becomes an executable, a library an .admlib source package (its permissions audited into the manifest), a plugin an .admplugin.

adm build App1 acme.imaging
adm build --libs samples/imaging
adm build App1 --release --os linux --arch arm64
adm build App1 --os wasm --out site

Builds are incremental. The compiler caches each module's checked and lowered form and its object code under ~/.adm/cache, so after an edit only the modules whose sources or imported interfaces changed are checked and compiled again. An unchanged binary is not linked again. An application or plugin build also drops every function the program cannot reach before code generation (a plugin keeps what it exports). --no-cache, ADM_NO_INCREMENTAL=1 and ADM_NO_SHAKE=1 turn these off.

adm check

adm check [paths...] [flags]

Semantic analysis without building: parses, resolves and type-checks, then prints diagnostics. adm check --all std validates the standard library.

adm explain

adm explain [codes...] [flags]

What a diagnostic code stands for: error or warning, its area, the message the compiler reports and its entry on the Diagnostics page.

adm doc

adm doc [module-or-symbol] [flags]

Documentation from the compiler's own resolver: a module's exports with signatures and doc comments, a workspace overview, or a symbol search across modules. Methods, fields and properties are not module exports and do not appear in a search; the language server and the MCP server's adm_symbol find those.

adm doc --module std.io
adm doc --search readFile
adm doc --workspace --root std --no-std

adm fmt

adm fmt [paths...] [flags]

Formats .adm files in place; the authoritative formatting, so never hand-align.

adm fmt
adm fmt --check src/

adm run

adm run [appName | file.adm | dir] [-- appArgs...] [flags]

Builds an application, runs it and removes the executable afterwards. Arguments after -- go to the program. A .adm file runs the application that file declares, with the modules beside it; a folder holding several applications needs the application's name. adm run ends with the program's exit status (128 plus the signal for a program a signal ended), and stopping adm run stops the program: Ctrl+C reaches it from the terminal, and adm passes a SIGTERM it receives on to it, every ending signal when it runs without a terminal (from an editor or a script), so the program is never left running. adm test runs its suites the same way.

adm run
adm run MyApp -- --help
adm run examples/listen.adm
adm run MyApp --os wasm

adm test

adm test [paths...] [flags]

Builds and runs the check suites under the paths (adm test std runs the whole standard library's). Only tests whose files lie under the paths run; the standard library and the dependencies the runner links are left out unless named. Each program gets its own scratch application folder through ADM_APP_HOME, so suites never touch real user folders. A test that crashes or runs out of time is reported failed ([crash], [timeout]) and the run goes on with the next one.

adm test std/services
adm test --run TestRule std/services
adm test --list --json std/io

adm package build

adm package build --app NAME [flags]

Builds a tar.gz release artifact from the [package] rules of adm.toml, versioned from [apps.<Name>] (0.1 when unset), optionally signed.

adm package install

adm package install <artifact.tar.gz> [flags]

Installs a release artifact into the user's application directory, versioned, and updates the current symlink.

Project and application

The manifest, the application's identity and policy, the units and dependencies of a tree.

adm list

adm list [DIR] [flags]

Lists every application, library and plugin declared under a directory: kind, name, file and line, folder, the nearest adm.toml above it and its version. A monorepo lists many units, some with a manifest and some without.

adm list testdata/apps --json

adm list packages

adm list packages [--dir DIR] [flags]

The project's dependencies from adm.lock: version, whether each is installed, the newest version the registry offers, the permissions accepted at install, the description, and the package's own requirements (the permissions its code reaches, with the chains).

adm audit

adm audit [DIR] [flags]

Lists the permissions a package's code reaches: every function is walked and each call followed, through the standard library and dependencies, to the gated functions it can reach (a service method with @commit(policy = ...) or @query(policy = ...), a function with @requires). Each permission comes with the chain that reaches it; an @on observer of a gated commit is listed as observe, and files binding foreign code (@c, @native) are named, since no policy can verify them. The interfaces the package serves to other processes (@remote<I>) and the ones it calls in them (IPC.connect<I>) are listed after the permissions. In a library tree the package is each library's exported modules and their closure; elsewhere it is the application's own modules. A library build writes the same set into the package manifest and fails when adm.toml narrows it with [requires] permissions = [...] to less than the code reaches.

adm audit
adm audit testdata/desktop_apps/opengl_window

adm app init

adm app init [flags]

Generates adm.toml with a fresh Ed25519 publisher key and repo salt, and writes the private key outside the repository (~/.config/adm/keys/<publisher id>.ed25519).

adm app info

adm app info [--dir DIR] [--app NAME] [flags]

The application's identity and everything adm.toml configures: publisher (id, public key, salt presence, private key path and whether it exists, creation date), the resolved app id, name, version and update feed, the [apps] tables, packaging rules, dependencies, registries, the [requires] narrowing and the policy flag. Without a manifest the identity comes from the application declaration.

adm app set

adm app set <table.key> <value> [--dir DIR] [--app NAME]

Writes one adm.toml value, keeping every other line and comment: the key's line is replaced, appended to its table, or the table is appended. With --app, version, slug, update.* and package.* address that application's tables. Values are written by the key's type: policy.sandbox as a bool, requires.permissions and registries.order as arrays from a comma list, everything else as a string. package.files replaces the whole file-rule list from from=>to[:mode], ...; without --app it writes the file-level [package] table, which is what a library or plugin build ships under files/. adm package build adds every installed library's shipped files to the archive under share/<namespace>/<name>/ on its own. Quote a segment holding a dot or a colon: apps."My App".version, deps."acme:utils".

adm app set --app Main version 1.2.0
adm app set update.feed https://example.com/feed.json
adm app set registries.order "corp, public"
adm app set --app Main package.files "dist/app=>bin/app:0755, README.md=>share/doc/README.md"

adm app unset

adm app unset <table.key | table> [--dir DIR] [--app NAME]

Removes one key, or a whole table when the name is one: registries.acme drops [registries.acme] and takes it out of the order list; with --app, package.files drops every file rule.

adm app bump

adm app bump <major|minor|patch> --app NAME [--dir DIR]

Increments the application's version in adm.toml.

adm app id

adm app id [AppName] [--dir DIR]

Prints the resolved identity and update configuration the build bakes in as __app_id__, __app_name__, __app_version__ and the update constants.

adm app rekey

adm app rekey [--dir DIR] [--private-key-out PATH] [--publisher NAME]

Gives an existing manifest a new key pair and repo salt, rewriting [publisher] in place and writing the new private key where init would. The publisher id and every app id change with it; signing looks only at the default key path or ADM_SIGNING_KEY, so a custom key path needs the variable. --publisher NAME uses a stored identity's key (adm publisher list) instead of generating one.

adm app sign

adm app sign <artifact> [flags]

Signs an artifact with the manifest's publisher key.

adm app verify

adm app verify <artifact> [--sig PATH]

Verifies an artifact's signature.

adm app policy init

adm app policy init [--dir DIR] [--app NAME] [--force]

Writes a commented policy.toml template into the application's folder (ADM_APP_HOME, else ~/.local/share/<app name>): the grants compiled into the program per package, then one table per held permission with the fields it can narrow. The Policy service reads the file at startup; it can only narrow what the build granted.

adm app policy set

adm app policy set [--package ns:name] <permission> <field.kind|setting> <values>
adm app policy set [--package ns:name] <permission> allow|deny|ask

Writes one rule into policy.toml, for the whole program or for one dependency: field.allow, field.deny or field.ask with a comma-separated list (globs, IPv4 networks, ${app.home}), or a scalar setting. A kind alone rules on the permission as a whole, the field *, which is the only rule a permission without fields (adm.clipboard.read, adm.runtime.spawn, adm.notifications.show) can have: it writes "*".deny = ["*"]. The file is created when missing.

adm app policy set adm.network.connect host.deny "*.example.net, 10.0.0.0/8"
adm app policy set --package acme:imaging adm.storage.read path.allow "${app.home}/**"
adm app policy set adm.clipboard.read deny

adm app policy unset

adm app policy unset [--package ns:name] <permission> <field.kind|setting>

Removes one rule.

adm app policy get

adm app policy get [--json]

Prints every rule of the file: subject (* or the package), permission, field (* for a rule on the whole permission), kind and values.

adm app policy log

adm app policy log [--dir DIR] [--app NAME] [--clear]

Prints the decision log the Policy service keeps beside the file: denials, asks, live answers, file loads, the sandbox report. --clear deletes the log; the service starts a fresh one at its next decision.

adm lib

adm lib [--dir DIR] [flags]

Lists the libraries the project depends on: version, publisher, where each came from, whether it is in the cache or in vendor/, and a newer registry version when one exists.

adm lib remove

adm lib remove [namespace:]name [--dir DIR]

Drops a dependency from adm.lock and its line from [deps] in adm.toml; the cached package stays for other projects.

adm lib verify

adm lib verify <package.admlib | plugin.admplugin> [flags]

Reads a container the way the compiler does before using one: every file must match the checksums and the publisher signature must verify. Prints name, version, publisher id, SHA-256 and dependencies; exits non-zero on a corrupt, tampered or unsigned container.

adm new

adm new application|library|plugin <folder> [flags]

Makes a project with its first unit, ready to build and test: adm.toml, the unit's declaration (main.adm, library.adm or plugin.adm), a module named after the unit with a function and its check suite, and a README with the build, run and test lines. The unit is named from the folder (my-app gives the application MyApp; a library gets dotted lower case, image.tools) unless --name says otherwise. The IDE's new-project screen makes the same project through it.

Package manager

Fetching, installing, publishing and vendoring libraries; see the Libraries page for the model behind them.

adm get

adm get [namespace:]name[@range] ... [flags]

Resolves each library in the configured registries, picks the highest version in range that is not yanked, downloads the container from the library's own repository, verifies it (index hash, checksums, signature, publisher, module ownership) and installs it into the package cache, recording it in adm.lock; dependencies the library declares follow. Then the permissions the package asks for are shown as a checklist, grouped by package, with one more row when the package binds foreign code (@c, @link, @native); the accepted set goes into the lock (permissions=, and foreign=yes for the bindings) and a later version asking for more, or starting to bind foreign code, is refused until accepted again. With no arguments every [deps] entry the lock does not cover yet is fetched.

adm get acme:imaging
adm get acme:imaging@^1.4 --accept adm.storage.*

adm install

adm install [package.admlib | URL ...] [flags]

Installs .admlib packages from files or URLs into the cache and records them in adm.lock, with the same verification and the same permission checklist as get. With no arguments every package the lock names but the cache lacks is fetched again from its recorded source.

adm install ../lib/acme.files-0.1.admlib --accept all

adm publish

adm publish [flags]

In a library's source tree with a clean git working tree and a GitHub origin: builds and signs the .admlib, tags the source <name>@<version>, pushes the tag, creates its GitHub release with the container as the asset, and opens a pull request on the registry adding the index line. The container never enters the repository. Needs the GitHub CLI (gh), logged in as the account that owns the origin. Refuses when the version is not newer than the registry's, when nothing signs the package, or when the tree is dirty.

Before building, the library's API is compared with the newest version in the registry, read from the sources of both. Anything removed or changed in a way that breaks callers (a parameter renamed or retyped, a default dropped, a method added to an interface, an enum member added) calls for a major release, an addition for a minor one, anything else for a patch. When the version raises less than that, publish lists the changes and suggests the version semantic versioning gives (a break after 0.5.3 suggests 1.0.0): a terminal is asked whether to take it, publish anyway or abort; without a terminal --semver must say.

adm yank

adm yank [NAMESPACE:]NAME@VERSION [flags]

Withdraws a published version: opens a pull request on the registry that adds a yank line for it. adm get and adm search no longer offer the version and a range no longer resolves to it. A project that already has it in adm.lock keeps installing it, with a warning that shows the reason. Nothing is deleted, and the version number is never reused. The pull request must come from the GitHub account that owns the namespace, which is what gh is logged in as.

adm publisher new

adm publisher new <name>

Generates a key pair and stores it under a local name: the name in ~/.config/adm/publishers.toml, the key in ~/.config/adm/keys. adm app init --publisher <name> then writes that identity's public key into a new adm.toml, so several repositories sign as one publisher. The name is a local label and is never published.

adm publisher list

adm publisher list

Lists the stored identities.

adm publisher name

adm publisher name <publisher id> <name>

Names a key already in the keys directory, one adm app init made.

adm publisher export

adm publisher export <name>

Prints the identity's private key (base64), for adm publisher import or ADM_SIGNING_KEY.

adm publisher import

adm publisher import <name> <file|->

Stores a private key printed by adm publisher export under the name.

adm search

adm search [text] [flags]

Lists every library whose name, namespace or description contains the text (all of them without text). The registries are pulled when their local clones are more than an hour old (ADM_CATALOG_MAX_AGE, a Go duration, changes that).

adm search humanize

adm vendor

adm vendor [--dir DIR]

Copies every locked package from the cache into vendor/ beside the lock, the same layout; when that directory exists the compiler and the language server read dependencies from it instead of ~/.adm/pkg, so a checkout builds without get or network access.

Developer tools

Compiler internals and editor integration.

adm dump

adm dump <file> [flags]

Dumps a compilation stage for one file: tokens, the AST, the IR or LLVM IR.

adm dump main.adm --stage llvm

adm lsp

adm lsp [--log-protocol]

Starts the language server on stdio (go to definition, references, hover, workspace symbols, diagnostics); --log-protocol traces every request to stderr. Every server also keeps a session journal, ~/.adm/cache/lsp/adm-lsp-<pid>.log (ADM_CACHE): the root the editor gave it, the files it found, each analysis with its error count and the files holding the errors, its restarts; journals idle for a week are removed. The server runs on at most 8 processors and limits its heap to a quarter of the machine's memory (at least 4 GiB); GOMAXPROCS, GOGC and GOMEMLIMIT override. The first analysis leaves the bodies of standard-library modules nobody has open unchecked and fills in their diagnostics and references from what an earlier session stored under ~/.adm/cache/ir/lspbodies (ADM_CACHE); adm clean clears it.

adm mcp

adm mcp [--root DIR] [--log-protocol]
adm mcp install [TOOL...|all]

Starts a Model Context Protocol server on stdio exposing the compiler's resolver and type checker as agent tools. A tool call that names no roots analyzes --root; without it, the folders the client has open, else the current directory. --log-protocol traces every message to stderr.

The twelve tools that change nothing are marked read-only, so a client can run them without asking; adm_fmt, adm_fix and adm_rename write source files. No tool builds or runs the project's code, check suites included: those are run with adm test in a terminal. A file that is edited, added or removed is seen by the next call. Tool calls run side by side: a long type check does not hold up a lookup, a client can cancel a call, and a call that asks for progress is told every few seconds that it is still running. adm_check, adm_references and adm_lint also return their answer as structured data. The three language documents are offered as resources too (adm://docs/language-specification, adm://docs/idioms, adm://docs/memory-model). Each result names the adm that answered (_meta), and when a newer adm is installed at the server's own path, the server restarts onto it between calls, keeping the session (on Windows the results say so instead). The server speaks the protocol revisions 2024-11-05 to 2025-11-25.

adm mcp install

Registers the server with the AI coding tools on the machine, so an agent can look up ADM symbols, read module documentation, check code and run suites in any project. Without arguments it lists the tools it found and what each one has:

$ adm mcp install
claude     Claude Code              not registered for every project
                                    ✓ this project: adm mcp --root . (/work/app/.mcp.json)
codex      Codex                    ✓ registered
vscode     VS Code (Copilot chat)   not registered for every project
zed        Zed (agent panel)        not registered for every project
not found: copilot, cursor, gemini, opencode, windsurf

$ adm mcp install claude zed     # the named tools
$ adm mcp install all            # every tool found

The first line of a tool is its user-wide registration, the one that applies in every project. A second line appears when the project in the current directory registers the server in its own files (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, .gemini/settings.json, opencode.json); those are only read, never written. registered as: ... means the tool starts another command line than the one this adm would write, for instance after the binary moved; installing again replaces it.

With names, the server is written to each tool's user-wide settings as the full path of the running adm followed by mcp, with no --root, so it analyzes whichever project the tool has open. Restart a running tool afterwards.

A tool counts as found when its program is on PATH or its settings folder exists. Settings files are edited in place: one entry is set, and comments, key order and formatting stay as they were. A file that does not parse is reported and left untouched. Naming a tool that is not installed, or an unknown name, is an error; with several tools, one failing does not stop the others.

adm env

adm env [--json]

Prints the ADM_HOME, ADM_BIN, ADM_CACHE, ADM_LIB and ADM_PATH variables as set.

adm fix

adm fix [PATHS...] [flags]

Rewrites code written for an older adm to what this one expects. A release that changes the language or the standard library (a renamed annotation, a construct spelled another way) ships a fix for it; adm fix runs them over the .adm files under PATHS (the current directory by default) and writes the files back. Each fix recognises the old form by itself: nothing records which version a file was written for, current code is left alone, and a second run changes nothing. Fixes read tokens, so they work on a file the compiler no longer parses. A fix is skipped, with the reason, when the program declares something of its own that the old form would mean. Hidden folders and vendor are not walked. Lint findings are repaired by adm lint --fix, not here.

adm graph

adm graph [DIR] [flags]
adm graph packages [--dir DIR] [flags]
adm graph services [DIR] [flags]

Shows what depends on what. adm graph prints the import graph of the applications, libraries, plugins and modules under DIR (the current directory by default) as a tree. A module already listed above is marked (*) and not expanded again; (cycle) marks an import that leads back to a module it is nested under. Standard library modules are shown where they are imported but not expanded. adm graph packages shows the libraries adm.lock pins, with their versions and which was built against which. adm graph services shows the services and their dependencies; a soft dependency is marked (soft) and drawn dashed.

Shop [application]
├── adm.database.sqlite admlang
│   ├── std.data.db
│   └── std.net.url
├── shop
│   ├── std.data.db
│   └── std.services.database
└── std.services.database

adm lint

adm lint [paths...] [--json] [--fix] [--skip CODE,...] [--exclude GLOB] [--list]

Static checks over a program that type-checks, reported for the files under the given paths (default .); the standard library is loaded but never reported on. The text report groups findings by file and ends with a count per check. --json prints an array of {file, line, column, code, severity, message, fix, edits}, which the IDE's Lint tab reads. A finding with edits can be fixed mechanically: --fix applies every such edit on disk and names the files changed, and the Lint tab's Fix button does the same for one finding or a whole group. The language server runs the same checks on the open files, so editors show the findings inline (warnings and weak warnings, source adm-lint) with the fixes as code actions; initializationOptions.lint takes enabled and a skip list, and the adm/lint request returns every finding under a directory from the server's current analysis. On the command line an unchanged tree answers from a result cache under ~/.adm/cache/lint (every file the last run loaded still hashes the same and the roots hold the same files); ADM_NO_LINT_CACHE=1 bypasses it and --fix always runs.

What leaks, breaks or is dead is a warning: bind-copy, unmatched-path, ref-cycle, closure-cycle, observer-cycle, missing-dispose, unsynchronised-field, blocking-observer, unchecked-map-index, array-identity, non-exhaustive-match, unreachable, empty-onerror, self-assign, constant-condition, undeclared-dependency, undeclared-permission, assertless-test, suite-file-without-suite, unused-import, unused-internal and unused-local. The rest are informational. Test files skip the naming and documentation checks, and constructors and destructors need no doc comment. --skip leaves checks out; the exit code is 0 either way. Fixes exist for ref-cycle (inserts weak on the optional field), unused-import (removes the line or the name), accessor-prefix, redundant-internal, array-identity and the prefer-* rewrites.

adm lint
adm lint std/io --skip missing-doc,todo
adm lint --fix .
adm lint --list

adm ide

adm ide

Starts the IDE.

Not implemented yet.

Toolchain

The installation itself.

adm doctor

adm doctor [--json] [--verbose]

Diagnoses the installation: compiler, C toolchain, library paths, caches. --json prints one result per check with title, status, message and a fix hint.

adm targets

adm targets

Prints every <os>-<arch> the build accepts, the clang triple it maps to and whether it can be linked here: the host always, another platform only when ADM_SYSROOT_<OS>_<ARCH> points at a sysroot or the toolchain ships a baseline for it. The sysroot a platform would use is shown.

adm update

adm update [flags]

Looks up the latest language package on the distribution repository and installs it over this installation (bin/, lib/, tools/; caches, packages and catalogs are kept). A development checkout is refused.

adm version

adm version [flags]

Shows the version, checking for a newer release unless told not to.

adm clean

adm clean

Removes every build cache under ADM_CACHE (default ~/.adm/cache).

adm config

adm config

Configures the toolchain.

Not implemented yet.

adm completion

adm completion bash|zsh|fish|powershell

Prints the shell completion script for the named shell.

source <(adm completion zsh)

Environment variables

What the toolchain and the programs it builds read from the environment.

Toolchain

Compiled programs

Read at startup by every program the compiler builds.