stack-sh/cli is the open-source native Rust stack command for Stack architecture diagrams.
The repository contains native validation, formatting, and rendering commands. Stack CLI 0.4.0 is the supported native binary release for macOS 13 or newer and glibc-based Linux 2.31 or newer, on arm64 and x86_64. GitHub Releases, Homebrew, and the owner-maintained Aqua registry are available; Cargo and self-update are still planned. The target matrix, artifact names, verification material, channel ownership, and rollback rules are defined by the distribution contract, with signing and verification procedures in the supply-chain guide.
On supported Homebrew hosts, install the owner-maintained formula:
brew install stack-sh/tap/stackFor Aqua, copy the pinned configuration and policy from the Aqua installation section, review them, allow the policy, and install the checksum-locked package:
aqua policy allow
aqua update-checksum
aqua install
stack --versionFor a direct installation, download the archive for your target and its verification material from GitHub Releases. Verify the checksum signature and both attestations by following the supply-chain guide, then follow the direct installation steps. The macOS artifacts are reproducibly ad-hoc signed, not Apple-notarized; Sigstore and GitHub attestations provide the publisher-identity check.
The command inventory below follows the current source tree. stack doctor and stack config were added after 0.4.0 and are not present in the published 0.4.0 binaries; they will become available through installation channels in a later release.
stack help
stack help render
stack version
stack init
stack init --template groups-and-layout
stack init --template aws-serverless-checkout -o checkout.stack
stack check arch.stack
stack check arch.stack --json
stack fmt arch.stack
stack fmt --check arch.stack
stack fmt -
stack render arch.stack
stack render arch.stack -o arch.svg
stack render arch.stack --json
stack update --check
stack lsp
stack doctor
stack doctor --provider-pack .stack-icons
stack config path
stack config get default_icons_path
stack icons list
stack icons list aws s3
stack icons import gcp --accept-terms
stack icons import simple-icons --accept-terms
stack render arch.stack -o arch.svg --notice arch.NOTICE.md
stack completions zsh
stack manpage
stack help, stack -h, and stack --help print top-level help. Use stack help <COMMAND> or <COMMAND> -h / <COMMAND> --help for command-specific usage and examples; nested help is available through stack help config <COMMAND> and stack help icons <COMMAND>. stack version, stack -v, stack -V, and stack --version print the same Cargo package version. Help and version output use standard output and exit with status 0. Invalid arguments and unknown commands use standard error and status 2; close command typos include a suggested command and the relevant help invocation.
stack init creates diagram.stack from the versioned hello-stack template without prompting. Use --template <ID> to select any of the nine curated examples shared with the public Stack specification and Web gallery, and -o / --output to choose another file. Existing paths are never replaced unless --force is explicit; forced writes use the same atomic output behavior as rendering. Provider templates print the exact stack icons import commands needed for branded rendering and remain valid with deterministic fallback icons when packs are absent. The embedded catalog and source bytes are pinned by tests/specification-revision, and CI rejects drift from that public specification commit.
stack check reads the file as bytes and runs the full compiler, theme, layout, and routing validation pipeline without changing the source. Diagnostics are written to standard error in source order. Standard output remains empty.
stack check, stack fmt, and stack render accept --json for CI, editor, and agent consumers. JSON mode preserves exit statuses and emits one versioned envelope containing structured diagnostics, completed artifacts, and operational errors. Inline formatted source and SVG are carried as artifact content so standard output remains valid JSON. See the machine-readable output contract and its immutable version 1 JSON Schema.
stack fmt uses the engine formatter and preserves comments. File mode replaces changed source atomically through a temporary file in the same directory; unchanged files are not replaced. Syntax, encoding, and host I/O failures leave the original file untouched. stack fmt - reads bytes from standard input and writes only canonical source to standard output. --check never writes source and exits with status 1 when formatting is required.
stack render uses the same engine pipeline to produce deterministic standalone SVG. Without -o, standard output contains only SVG. With -o, the output is written atomically in the destination directory. It discovers imported aws, gcp, azure, and simple-icons packs below the shared icon store. Use --provider-pack <DIRECTORY> for a project-local icon-store root, and use --notice <NOTICE> to save the exact provider pack revisions, terms, source archives, and icon IDs embedded in that artifact. Pack files are bounded and validated before rendering. Diagnostics remain on standard error, warnings preserve SVG, and Stack errors never create or replace output.
stack lsp runs a native Language Server Protocol 3.18 adapter over standard input and output. It provides incremental document synchronization, versioned diagnostics, completion, hover, hierarchical document symbols, and whole-document formatting for .stack files. The adapter negotiates UTF-8, UTF-16, or UTF-32 positions and delegates language semantics and formatting to the pinned compiler and engine rather than reimplementing them. Standard output is reserved for framed JSON-RPC messages.
stack config path prints the selected config.yaml path without creating or reading the file. stack config get default_icons_path strictly reads the supported configuration and prints the effective icon-store path. stack doctor reports the CLI version, configuration path and source, configuration validity, effective icon-store source, and installed known-provider packs. It is read-only, emits actionable categories instead of configuration contents, exits 0 for healthy and warning-only reports, and exits 2 when it finds an operational problem. See the configuration discovery and doctor contract.
stack update is included in 0.4.0 for future receipted direct installations, with --check, exact-version selection, authenticated release-manifest and archive verification, and rollback-aware atomic replacement. It refuses Homebrew, Aqua, Cargo, and unknown ownership. The 0.4.0 release manifest does not activate self-update, and the documented manual installation creates no receipt, so the channel remains planned. See the self-update contract.
stack completions <bash|zsh|fish> and stack manpage generate deterministic shell integration and an offline roff manual from the CLI command metadata. The 0.4.0 release archives carry the exact generated files; Homebrew installs them into its managed completion and manual paths, while direct, Aqua, and future Cargo users can generate them into user-owned locations without modifying shell startup files. See the completion and manual guide.
stack icons list [PROVIDER] [QUERY] searches the asset-free catalog by ID, product name, or category. The catalog currently contains 1,051 IDs: 305 AWS, 45 Google Cloud, 639 Azure, and 62 curated developer and collaboration tool icons. This command reads only metadata embedded in the CLI.
stack icons import <PROVIDER> --accept-terms downloads the audited official archive set, verifies every complete SHA-256 before ZIP processing, reads allowlisted SVG entries with fixed size limits, sanitizes active and external content, preserves official colors and geometry, and writes the manifest, notice, and processed SVGs atomically. The default store is $XDG_CONFIG_HOME/stack/icons, falling back to $HOME/.config/stack/icons. $XDG_CONFIG_HOME/stack/config.yaml can set an absolute default_icons_path. Use -o <DIRECTORY> to put provider child directories below a project-local root. See the configuration contract for discovery and diagnosis, and the provider icon guide for project-local usage, sources, hashes, and rights.
| Result | Exit status |
|---|---|
| No error diagnostics, including warning-only input | 0 |
One or more Stack error diagnostics, or fmt --check finds a difference |
1 |
| Invalid arguments, host I/O failure, or engine operational failure | 2 |
The CLI links stack-engine and the protocol-neutral stack-compiler language-intelligence API as native Rust dependencies. It owns filesystem and standard-stream behavior, process exit codes, configuration discovery, provider-pack import, LSP transport and document state, notice output, and command presentation. It must not duplicate compiler, formatter, layout, or SVG-rendering logic.
The bundled engine resolves 30 provider-neutral core icons: api, web, mobile, desktop, server, container, cluster, cloud, scheduler, webhook, identity, observability, gateway, load-balancer, dns, cdn, firewall, network, event, stream, search, analytics, repository, pipeline, secret, document, task, chat, email, and ai. User-managed provider packs preserve upstream artwork and attach source, archive hash, transformation, terms, and notice metadata. Rendering resolves namespaced IDs such as aws:s3, preserves the authored semantic kind, embeds the selected local asset, and writes its provenance into SVG metadata and the optional notice sidecar.
The CLI requires Rust 1.85 or newer.
cargo run -- check arch.stack
cargo test --locked
cargo clippy --all-targets --all-features --locked -- -D warnings
python3 scripts/generate_cli_assets.py --binary target/debug/stack --checkCI validates formatting, unit and process-level integration tests, generated completion and manual drift, release metadata and workflow security policies, at least 90% line/region coverage and 95% function coverage, Clippy, documentation, a release build, --help, and --version on stable Rust. Tests and Clippy also run on Rust 1.85.
Canonical formatter behavior is checked against the pinned stack-sh/specification fixture revision recorded in tests/specification-revision.
The same checkout validates and updates the embedded stack init templates:
STACK_SPECIFICATION_DIR=../specification \
node scripts/sync-example-templates.mjs --check
STACK_SPECIFICATION_DIR=../specification \
node scripts/sync-example-templates.mjs
STACK_SPECIFICATION_DIR=../specification \
cargo test --features conformance --test template-conformance --lockedSee CONTRIBUTING.md before opening a change. Please report security vulnerabilities through the process in SECURITY.md, not a public issue.
Repository-authored work is licensed under the Apache License 2.0 for personal and commercial use. Runtime and build dependency licenses are recorded in THIRD_PARTY_LICENSES.md. Every published binary archive ships the applicable license and notice files described there.