Skip to content

Guide every installer to a verified first SVG #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
konojunya merged 1 commit into from
Sep 5, 2026
Merged

Guide every installer to a verified first SVG #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 128 additions & 7 deletions content/site/guide/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,126 @@
# Getting started

The fastest way to use Stack is the browser [Playground](https://stack-diagram.com/). It runs the formatter, validator, layout engine, and SVG renderer locally in WebAssembly; you do not need to install a command or send source to a rendering API.
Choose one installer, then create your first SVG below. Prefer working in your terminal or with a [coding agent](./coding-agents)? Use the CLI. Want to try Stack without installing anything? Open the [Playground](https://stack-diagram.com/) and follow the browser example further down.

## Install the native CLI
## Install the CLI

For terminal workflows and local automation, install the owner-maintained Homebrew formula with `brew install stack-sh/tap/stack`. It uses the canonical Stack CLI {{cliVersion}} release archive and supports Apple Silicon macOS plus glibc-based Linux on arm64 and x86_64 when the host meets Homebrew's current tier-1 requirements. Homebrew owns upgrades through `brew upgrade stack-sh/tap/stack`; uninstalling the formula leaves your Stack configuration and icon store in place. See the [CLI distribution contract](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#homebrew-installation) for the exact platform matrix, direct-install alternative, and recovery policy.
Stack CLI {{cliVersion}} supports macOS and glibc Linux on arm64 and x86_64. Prebuilt archives require macOS 13 or glibc 2.31 or newer; Windows and Alpine/musl are not supported. Choose one installer so different copies do not compete on `PATH`. The [distribution contract](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#supported-platform-matrix) owns the exact support matrix.

Rust users can install the same CLI from crates.io with a working Rust 1.85 or newer toolchain and native linker:
### Homebrew

`cargo install stack-diagram-cli --version {{cliVersion}} --locked`
Use an existing Homebrew installation on Apple Silicon macOS or supported Linux. Homebrew’s own tier-1 host requirements also apply.

`stack --version`
```text
brew install stack-sh/tap/stack
```

### Cargo

Use Rust 1.85 or newer with a native linker: Xcode Command Line Tools on macOS, or a C compiler/linker on Linux. Make sure Cargo’s bin directory is on `PATH`. The package is `stack-diagram-cli`; the installed command is `stack`.

```text
cargo install stack-diagram-cli --version {{cliVersion}} --locked
```

### Aqua

In a Git repository, save the following as `aqua.yaml`:

```yaml
checksum:
enabled: true
require_checksum: true
supported_envs:
- all
registries:
- name: stack-sh
type: github_content
repo_owner: stack-sh
repo_name: cli
ref: 42702cda91a4156901b9a601bd143c43dcf05766
path: aqua/registry.yaml
packages:
- name: stack-sh/cli@v{{cliVersion}}
registry: stack-sh
```

Save this narrowly scoped policy as `aqua-policy.yaml`, review it, then allow it and install with Aqua:

```yaml
registries:
- name: stack-sh
type: github_content
repo_owner: stack-sh
repo_name: cli
ref: 'Version == "42702cda91a4156901b9a601bd143c43dcf05766"'
path: aqua/registry.yaml
packages:
- name: stack-sh/cli
registry: stack-sh
version: semver(">= 0.3.0")
```

```text
aqua policy allow
aqua update-checksum
aqua install
```

Commit `aqua.yaml`, `aqua-policy.yaml`, and the generated `aqua-checksums.json`. Aqua’s bin directory must be on `PATH`. The registry is pinned to an immutable revision; do not replace it with `main`.

### Direct download

With the [GitHub CLI](https://cli.github.com/) installed and authenticated, run this in a POSIX shell on a supported host. It downloads to a new temporary directory, verifies the checksum and exact tagged publisher identity before extraction, and refuses to replace an existing `~/.local/bin/stack`. The archive is ad-hoc signed on macOS, not notarized. Stop if any verification fails.

```text
(
set -eu
version={{cliVersion}}
case "$(uname -s)/$(uname -m)" in
Darwin/arm64) target=aarch64-apple-darwin ;;
Darwin/x86_64) target=x86_64-apple-darwin ;;
Linux/aarch64) target=aarch64-unknown-linux-gnu ;;
Linux/x86_64) target=x86_64-unknown-linux-gnu ;;
*) echo "Unsupported platform" >&2; exit 1 ;;
esac
archive="stack-v${version}-${target}.tar.gz"
download_dir=$(mktemp -d)
cd "$download_dir"
gh release download "v$version" --repo stack-sh/cli --pattern "$archive" --pattern "stack-v${version}-checksums.txt"
awk -v archive="$archive" '$2 == archive { print }' "stack-v${version}-checksums.txt" > archive-checksum.txt
if command -v sha256sum >/dev/null 2>&1; then
sha256sum --check archive-checksum.txt
else
shasum -a 256 --check archive-checksum.txt
fi
gh attestation verify "$archive" --repo stack-sh/cli --signer-workflow stack-sh/cli/.github/workflows/release.yaml --source-ref "refs/tags/v$version" --deny-self-hosted-runners
tar -xzf "$archive"
mkdir -p "$HOME/.local/bin"
test ! -e "$HOME/.local/bin/stack"
install -m 0755 "stack-v${version}-${target}/stack" "$HOME/.local/bin/stack"
)
export PATH="$HOME/.local/bin:$PATH"
```

## Create your first SVG

In a new empty working directory, run:

```sh
$ stack --version
$ stack init
$ stack check diagram.stack
$ stack render diagram.stack -o diagram.svg
```

Expected: `stack {{cliVersion}}`, a new `diagram.stack`, no check errors, and a non-empty `diagram.svg`. Open the SVG in a browser or add it to your README. `stack init` protects existing files; use a fresh directory instead of overwriting your work.

This builds the `stack` binary from registry-only dependencies on macOS or glibc Linux, on arm64 or x86_64. Cargo owns upgrades: run the install command with the desired released version; uninstall with `cargo uninstall stack-diagram-cli`. Choose one installer for a given binary location to avoid competing copies on `PATH`; Stack does not update itself. Cargo does not install shell completion or manual files automatically; see the [Cargo installation contract](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#cargo-installation) for prerequisites and optional shell integration. Aqua users can use the [owner registry](https://github.com/stack-sh/cli/blob/main/aqua/README.md).
Edit `diagram.stack` to describe your system, then repeat check and render. Format it when needed:

```sh
$ stack fmt diagram.stack
$ stack fmt --check diagram.stack
```

## Write your first document

Expand Down Expand Up @@ -92,3 +200,16 @@ If Stack finds a problem, the diagnostic shows its severity, stable code, locati
- Read [Nodes and groups](../language/nodes-and-groups) to model components and boundaries.
- Read [Edges and layout](../language/edges-and-layout) for relationships and placement intent.
- Read [Themes and icons](../language/themes-and-icons) before selecting a visual system or explicit icon.

## Update or uninstall

Stack does not update itself. Use the installer that owns your binary. Configuration and imported icon packs remain in place when the binary is removed.

| Installer | Update | Uninstall |
| --- | --- | --- |
| Homebrew | `brew upgrade stack-sh/tap/stack` | `brew uninstall stack-sh/tap/stack` |
| Cargo | Run the Cargo install command above with the desired version. | `cargo uninstall stack-diagram-cli` |
| Aqua | `aqua update`, `aqua update-checksum`, `aqua install` | Run `aqua rm -m pl stack-sh,stack-sh/cli` while this configuration is present, then remove `stack-sh/cli` from `aqua.yaml`. Other projects using this package may reinstall it when needed. |
| Direct download | Verify a new release and replace only your directly installed binary. | Remove only the direct binary you installed (`~/.local/bin/stack`). |

For shell completions, manual pages, and recovery, see [shell integration](https://github.com/stack-sh/cli/blob/main/docs/completions.md), [safe upgrades](https://github.com/stack-sh/cli/blob/main/docs/self-update.md), and [supply-chain verification](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md).
135 changes: 128 additions & 7 deletions content/site/ja/guide/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,126 @@
# はじめる

最短の利用方法はbrowser [Playground](https://stack-diagram.com/)です。Formatter、validator、layout engine、SVG rendererがWebAssemblyとしてlocalで動作するため、commandのinstallやrendering APIへのsource送信は不要です。
導入方法を1つ選び、このページの手順で最初のSVGを作ります。ターミナルや[coding agent](./coding-agents)で使うならCLIを、インストールせず試すなら[Playground](https://stack-diagram.com/)と下のブラウザー向けの例を使ってください。

## Native CLIをinstallする
## CLIを導入する

Terminal workflowとlocal automationでは、owner管理のHomebrew formulaを`brew install stack-sh/tap/stack`でinstallします。CanonicalなStack CLI {{cliVersion}} release archiveを使用し、Homebrewの現行Tier 1要件を満たすApple Silicon macOSと、arm64 / x86_64のglibc Linuxをsupportします。UpgradeはHomebrewが`brew upgrade stack-sh/tap/stack`で管理し、formulaをuninstallしてもStackのconfigとicon storeは保持されます。正確なplatform matrix、direct install、recovery policyは[CLI distribution contract](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#homebrew-installation)を参照してください。
Stack CLI {{cliVersion}}はarm64 / x86_64のmacOSとglibc Linuxに対応します。配布バイナリーの要件はmacOS 13以降またはglibc 2.31以降です。WindowsとAlpine/muslは対象外です。`PATH`上で複数のバイナリーが競合しないよう、導入方法を1つ選んでください。正確な対応表は[配布契約](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#supported-platform-matrix)が正本です。

Rustを利用している場合は、Rust 1.85以降のtoolchainとnative linkerを用意し、crates.ioから同じCLIをinstallできます。
### Homebrew

`cargo install stack-diagram-cli --version {{cliVersion}} --locked`
Apple Silicon macOSまたは対応するLinuxで、導入済みのHomebrewを使います。Homebrew自身のTier 1要件も満たす必要があります。

`stack --version`
```text
brew install stack-sh/tap/stack
```

### Cargo

Rust 1.85以降とネイティブリンカーが必要です。macOSではXcode Command Line Tools、LinuxではCコンパイラーとリンカーを用意し、Cargoのbinディレクトリを`PATH`へ追加してください。パッケージ名は`stack-diagram-cli`、コマンド名は`stack`です。

```text
cargo install stack-diagram-cli --version {{cliVersion}} --locked
```

### Aqua

Gitリポジトリ内に、次の内容を`aqua.yaml`として保存します。

```yaml
checksum:
enabled: true
require_checksum: true
supported_envs:
- all
registries:
- name: stack-sh
type: github_content
repo_owner: stack-sh
repo_name: cli
ref: 42702cda91a4156901b9a601bd143c43dcf05766
path: aqua/registry.yaml
packages:
- name: stack-sh/cli@v{{cliVersion}}
registry: stack-sh
```

次の限定的なポリシーを`aqua-policy.yaml`として保存し、内容を確認してから許可・インストールします。

```yaml
registries:
- name: stack-sh
type: github_content
repo_owner: stack-sh
repo_name: cli
ref: 'Version == "42702cda91a4156901b9a601bd143c43dcf05766"'
path: aqua/registry.yaml
packages:
- name: stack-sh/cli
registry: stack-sh
version: semver(">= 0.3.0")
```

```text
aqua policy allow
aqua update-checksum
aqua install
```

`aqua.yaml`、`aqua-policy.yaml`、生成された`aqua-checksums.json`をcommitしてください。Aquaのbinディレクトリを`PATH`に追加します。レジストリは不変のrevisionに固定しており、`main`へ置き換えないでください。

### 直接ダウンロード

[GitHub CLI](https://cli.github.com/)を導入・認証済みの対応ホストで、POSIXシェルから実行します。新しい一時ディレクトリへ取得し、チェックサムとタグ付き公開元の認証を検証してから展開します。既存の`~/.local/bin/stack`は置き換えません。macOSの署名はad-hocで、公証はされていません。検証に失敗したら中断してください。

```text
(
set -eu
version={{cliVersion}}
case "$(uname -s)/$(uname -m)" in
Darwin/arm64) target=aarch64-apple-darwin ;;
Darwin/x86_64) target=x86_64-apple-darwin ;;
Linux/aarch64) target=aarch64-unknown-linux-gnu ;;
Linux/x86_64) target=x86_64-unknown-linux-gnu ;;
*) echo "Unsupported platform" >&2; exit 1 ;;
esac
archive="stack-v${version}-${target}.tar.gz"
download_dir=$(mktemp -d)
cd "$download_dir"
gh release download "v$version" --repo stack-sh/cli --pattern "$archive" --pattern "stack-v${version}-checksums.txt"
awk -v archive="$archive" '$2 == archive { print }' "stack-v${version}-checksums.txt" > archive-checksum.txt
if command -v sha256sum >/dev/null 2>&1; then
sha256sum --check archive-checksum.txt
else
shasum -a 256 --check archive-checksum.txt
fi
gh attestation verify "$archive" --repo stack-sh/cli --signer-workflow stack-sh/cli/.github/workflows/release.yaml --source-ref "refs/tags/v$version" --deny-self-hosted-runners
tar -xzf "$archive"
mkdir -p "$HOME/.local/bin"
test ! -e "$HOME/.local/bin/stack"
install -m 0755 "stack-v${version}-${target}/stack" "$HOME/.local/bin/stack"
)
export PATH="$HOME/.local/bin:$PATH"
```

## 最初のSVGを作る

新しい空の作業ディレクトリで実行します。

```sh
$ stack --version
$ stack init
$ stack check diagram.stack
$ stack render diagram.stack -o diagram.svg
```

`stack {{cliVersion}}`と表示され、`diagram.stack`が作成され、checkがエラーなく終了し、空でない`diagram.svg`ができれば成功です。SVGはブラウザーで開いたりREADMEに貼ったりできます。`stack init`は既存ファイルを保護するため、上書きせず新しいディレクトリを使ってください。

macOSまたはglibc Linuxのarm64 / x86_64で、registry由来の依存だけを使ってbinary `stack`をbuildします。Upgradeは目的の公開versionを指定してinstall commandを実行し、uninstallは`cargo uninstall stack-diagram-cli`です。同じbinaryの配置先には1つのinstallerを選び、`PATH`上の競合を避けてください。Stack自身は自己更新しません。Cargoはshell completionやmanualを自動配置しないため、前提条件と任意のshell連携は[Cargo installation contract](https://github.com/stack-sh/cli/blob/main/docs/distribution.md#cargo-installation)を参照してください。Aquaでは[owner registry](https://github.com/stack-sh/cli/blob/main/aqua/README.md)を利用できます。
`diagram.stack`を自分の構成に書き換え、checkとrenderを繰り返します。整形が必要な場合は次を実行します。

```sh
$ stack fmt diagram.stack
$ stack fmt --check diagram.stack
```

## 最初のdocumentを書く

Expand Down Expand Up @@ -92,3 +200,16 @@ Sourceは4つの要素で構成されています。
- Componentとboundaryは[Nodeとgroup](../language/nodes-and-groups)を参照します。
- Relationshipと配置intentは[Edgeとlayout](../language/edges-and-layout)を参照します。
- Visual systemや明示iconを選ぶ前に[Themeとicon](../language/themes-and-icons)を参照します。

## 更新・アンインストール

Stack自身は更新を行いません。導入に使ったツールで管理します。バイナリーを削除しても設定とimport済みicon packは残ります。

| 導入方法 | 更新 | アンインストール |
| --- | --- | --- |
| Homebrew | `brew upgrade stack-sh/tap/stack` | `brew uninstall stack-sh/tap/stack` |
| Cargo | 上のCargo導入コマンドで目的のversionを指定します。 | `cargo uninstall stack-diagram-cli` |
| Aqua | `aqua update`, `aqua update-checksum`, `aqua install` | この設定がある状態で`aqua rm -m pl stack-sh,stack-sh/cli`を実行し、`aqua.yaml`から`stack-sh/cli`を削除します。他のプロジェクトが必要とする場合は再インストールされます。 |
| 直接ダウンロード | 新しいreleaseを検証し、直接導入したバイナリーだけを差し替えます。 | 自分で導入したバイナリー（`~/.local/bin/stack`）だけを削除します。 |

補完・man page・復旧手順は[シェル連携](https://github.com/stack-sh/cli/blob/main/docs/completions.md)、[安全な更新](https://github.com/stack-sh/cli/blob/main/docs/self-update.md)、[配布物の検証](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md)を参照してください。
Loading