Install artifactize

Every install provides artifactize, with its built-in tools available as artifactize tools. Non-Store channels also provide those tools as the standalone artifactize-tools command. Every GitHub release attaches prebuilt binaries for Linux (statically linked, x86_64 and aarch64), macOS (Apple silicon and Intel) and Windows (x64), each archive with a SHA-256 checksum, and the desktop app: one macOS disk image for both Mac CPUs, signed and notarized by Apple, and a Linux AppImage and .deb for x86_64; the Windows zip carries the app beside the commands. Stable releases are also published on crates.io, Homebrew and the Microsoft Store. winget distribution is in preparation and is not available yet. It is open source under the Apache License 2.0.

Before v1, the Linux build gates a release; the macOS and Windows archives and the desktop app are attached as soon as they build.

Prerequisites

• Linux (x86_64 or aarch64), macOS (Apple silicon or Intel) or Windows (x64). WSL 2 runs the Linux build.
• The example projects use python3 to run Python checks and grep to search text. Both commands must be available in your terminal. Projects run their declared commands as given on every OS; see Operating systems.
• Optional, one per Agent backend you plan to use: OPENAI_API_KEY, ANTHROPIC_API_KEY, or a ChatGPT plan that includes Codex. Runtime and Human evals need none.

PATH is the list of directories your terminal searches for commands. Before starting the examples, check that it can find their required tools:

python3 --version
grep --help

These should print a Python version and grep’s help. If either command is not found, install that tool or add its directory to PATH before continuing.

Only cargo install needs a Rust toolchain: the latest stable Rust, from rustup, and a C compiler (SQLite is built from source).

Install

Pick your OS. Install from one channel only; the Store uses the artifactize tools facade, while other channels also install the standalone tools command.

Start with the default for your OS, or choose an alternative below:

The defaults install the desktop app too, except Homebrew, which installs it as a separate cask. Cargo and a source build install the commands only.

Linux

curl -fsSL https://artifactize.dev/install.sh | sh
artifactize --version

The script picks the archive for your OS and CPU from the latest stable GitHub release, checks its SHA-256 against the release’s checksum and refuses a mismatch. It runs both new binaries before replacing anything, then installs them to ~/.local/bin. It uses curl or wget, never sudo, and never edits your shell startup files: if ~/.local/bin is not on PATH, it prints the line to add. It also warns about another artifactize or artifactize-tools on PATH that would run instead. On x86_64 Linux with glibc it also installs the desktop app from the same release, checked the same way: it unpacks the AppImage once into ~/.local/share/artifactize/desktop (no FUSE needed), adds an artifactize-desktop launcher beside the commands and an Artifactize menu entry. On aarch64 or musl systems such as Alpine it installs the commands only. Two environment variables change what it does; a prerelease installs only when ARTIFACTIZE_VERSION names it:

curl -fsSL https://artifactize.dev/install.sh | ARTIFACTIZE_VERSION=0.5.2 sh             # this release
curl -fsSL https://artifactize.dev/install.sh | ARTIFACTIZE_INSTALL_DIR="$HOME/bin" sh   # this directory

macOS

Homebrew is a macOS package manager: it installs and updates command-line tools for you. If brew is not available in your terminal, follow Homebrew’s setup instructions first. Then run:

brew install lhj6102/tap/artifactize
artifactize --version

The formula in the lhj6102/tap Homebrew tap installs both commands for your Mac’s CPU and follows stable releases. The desktop app is a cask in the same tap. It links the app’s own artifactize and artifactize-tools onto Homebrew’s PATH, so this one command gives you the app and both commands (uninstall the formula first if you have it; the cask replaces it):

brew install --cask lhj6102/tap/artifactize

The install script works on macOS as on Linux, with the same checks and environment variables. It installs the commands to ~/.local/bin, which a new Mac does not have on PATH; the script prints the line to add to your shell’s startup file, such as ~/.zshrc. It also installs the desktop app as ~/Applications/Artifactize.app.

curl -fsSL https://artifactize.dev/install.sh | sh

Windows

Microsoft Store (default). Install Artifactize from its Store page, or in a terminal:

winget install 9PB6W4LL165D --source msstore
artifactize --version   # in a new terminal

Microsoft signs Store packages, so Smart App Control lets them run, and the Store keeps them up to date. The package provides artifactize as an app execution alias; its tools run as artifactize tools read FILE, artifactize tools list, and so on. Other channels also provide the standalone artifactize-tools command. It adds two Start menu entries: Artifactize opens the desktop app, and Artifactize CLI shows the command’s help and a hint to open Windows Terminal or PowerShell, then waits for Enter when it owns the console alone; terminal launches and redirected input/output never pause. The Store package uses Windows’ default AppData virtualization: the app and the command keep their own package-private state rather than sharing Runs, sign-in and cache with winget, zip or Cargo installs. Windows removes that private state when you uninstall the Store app. See State for the Windows overlay caveat.

PowerShell install script. In Windows PowerShell 5.1 or PowerShell 7, without administrator rights:

irm https://artifactize.dev/install.ps1 | iex
artifactize --version   # in a new terminal

The script checks the zip’s SHA-256, runs both new binaries, then installs artifactize.exe, artifactize-tools.exe and the desktop app’s artifactize-desktop.exe to %LOCALAPPDATA%\Programs\artifactize, adds that directory to your user Path and adds an Artifactize Start menu shortcut for the app; open a new terminal afterwards. It reads the same environment variables as install.sh.

Smart App Control. The release zip used by the install script is not code-signed. On a machine with Smart App Control on, Windows may block a new release even when an earlier one ran. If Windows blocks the new binaries, the script stops before replacing anything: your previous artifactize and artifactize-tools stay installed and runnable, and Path is left unchanged. Do not bypass your application-control policy; install from the Microsoft Store instead.

winget (in preparation — not available yet). lhj6102.Artifactize has not been accepted into winget. Use the Microsoft Store now. After the package is published, the intended command is:

winget install lhj6102.Artifactize

That package installs both commands and the desktop app from the release zip and follows stable releases.

WSL. Inside WSL 2, artifactize is the Linux build: install it in the distribution with the Linux instructions. It is separate from a Windows install and keeps its own state. Built-in open and login codex use the distribution’s xdg-open, never a Windows program; see Opening files and the browser.

Cargo (all platforms)

With cargo-binstall, fetch the same prebuilt binaries into ~/.cargo/bin:

cargo binstall artifactize artifactize-tools

Or build the latest stable release from crates.io:

cargo install artifactize artifactize-tools --locked
cargo install artifactize@<version> artifactize-tools@<version> --locked   # a particular release

--locked builds with the dependency versions the release was tested with. The binaries go to ~/.cargo/bin, which must be on PATH; --root DIR installs them under DIR/bin instead. Both cargo commands work on macOS and Windows too.

Build from source (all platforms)

To build from source, install from a checkout; its rust-toolchain.toml selects stable Rust. The example projects and the Quick start use a checkout too:

git clone https://github.com/lhj6102/artifactize
cd artifactize
cargo install --path crates/artifactize --locked
cargo install --path crates/artifactize-tools --locked

Releases take their version from their tag, so a build from a checkout reports the placeholder version 0.0.0-dev.

Desktop app

The desktop app runs Monitor, Review and Graph in a window. It shows the Runs that artifactize verify starts, so the commands come with it: the Microsoft Store, install.ps1, install.sh, the Homebrew cask and the .deb put artifactize on PATH. From the disk image or an AppImage run on its own, the app sets up the commands on first launch (below). TUI and MCP already come with the ordinary artifactize binary; they need no additional product install.

The defaults above install it: the Microsoft Store and install.ps1 on Windows, install.sh on macOS and x86_64 Linux, and the Homebrew cask on macOS. Each release also attaches the app on its own:

Each file has a .sha256 checksum beside it. Run the app as artifactize-desktop, or open Artifactize from your applications menu or the Start menu.

The app checks standard terminal command locations and its inherited PATH in the background, without running shell startup files. On macOS this includes the system’s /etc/paths and /etc/paths.d entries, which new login terminals use. An existing command from Homebrew, an install script, .deb, winget or the Store is left alone; there is no setting to choose. Otherwise:

• macOS: the app writes its absolute Contents/MacOS directory to /etc/paths.d/artifactize through the system administrator prompt. Open a new terminal afterwards and run artifactize --version. Both commands run from the installed app, so updating the app updates them too. If you move the app, launch it again to repair an entry pointing to the old, missing location. Cancelling the prompt is remembered in the app’s state for that bundle location; it will not ask on every launch.
• Linux AppImage: the commands are copied to ${XDG_DATA_HOME:-~/.local/share}/artifactize/bin and linked from ~/.local/bin. They keep working after the temporary AppImage mount goes away, and launching a newer AppImage refreshes the app’s copies. Files or links in ~/.local/bin that the app did not create are never replaced. If your shell does not already search ~/.local/bin, add export PATH="$HOME/.local/bin:$PATH" to its startup file and open a new terminal. The app does not edit shell startup files.

Setup errors are logged without stopping the app. Windows installers, .deb and install.sh’s extracted Linux app already provide the commands and need no setup.

Build the desktop app from source

In addition to the source-build Rust prerequisites above, install Node.js 24, pnpm at the version named in crates/artifactize-desktop/ui/package.json, and Tauri’s native prerequisites for your OS. Linux needs WebKitGTK 4.1, GTK 3 and librsvg development packages; macOS needs the Xcode command-line tools; Windows needs the C++ build tools and WebView2. From the repository root:

pnpm -C crates/artifactize-desktop/ui install --frozen-lockfile
pnpm -C crates/artifactize-desktop/ui build
cargo install --path crates/artifactize-desktop --locked --bin artifactize-desktop
artifactize-desktop

The frontend must be built before Cargo: the normal app embeds ui/dist. Keep the default Cargo features and do not enable the test-only e2e feature for a normal app. Install the CLI from the same checkout too, as above: the app shows the Runs that artifactize verify starts. The app uses the same state home and credentials as the unpackaged CLI, not the Store app’s private state.

Plugin for Claude Code and Codex

The plugin adds the Hey Arti skill and the artifactize MCP server to Claude Code or Codex. It runs the artifactize program, so install that first with one of the channels above. This repository is the plugin’s marketplace, a catalog the assistant reads to find the plugin.

In a Claude Code session, add the marketplace, then install the plugin from it:

/plugin marketplace add lhj6102/artifactize
/plugin install artifactize@artifactize

From a shell, claude plugin marketplace add lhj6102/artifactize and claude plugin install artifactize@artifactize do the same.

For Codex, in a shell:

codex plugin marketplace add lhj6102/artifactize
codex plugin add artifactize@artifactize

Or run /plugins in Codex CLI and pick the artifactize marketplace.

Update

The install scripts and Cargo get a release as soon as it is published. Homebrew and the Microsoft Store follow stable releases only; a Store update can lag while Microsoft reviews it. The prepared winget channel targets stable releases only; its first publication is still pending. Updating keeps your state.

The plugin follows this repository’s main branch, which holds released versions. Update it with /plugin marketplace update artifactize in Claude Code (or turn on auto-update for the marketplace in /plugin), or codex plugin marketplace upgrade artifactize in Codex.

Upgrading from 0.11

State schemas 6 and 7 are upgraded additively to 8 on first use. Existing Runs, cache records and Human approvals are preserved. An older binary limited to schema 6 or 7 cannot open the upgraded state; keep a backup before switching versions.

artifactize verify now submits a durable Run, prints its ID and exits on acceptance. Add --wait to scripts and CI that need the validation exit code. Closing a terminal or interrupting a watcher leaves the Run running; artifactize run cancel RUN_ID is the explicit cancellation action. The foreground Human deadline and verify --timeout-ms are removed. --request-key makes retries return the same Run.

Gate bypass (--ignore-gates and review_policy) is removed. Per-request --speculate and --defer-human replace it, both off by default; deferred sign-offs end with SIGNOFFS_PENDING and --wait exit 5. See Runs and status. Plain artifactize monitor starts on ALL; monitor ., a positional path or --repo selects that repository initially.

Upgrading to 0.9

Rewrite declarations as TOML index.artf for folders and <file>.artf for files. Keys are snake_case and evals are [evals.<id>] tables; .artfignore replaces the old ignore file. There is no converter. Have an agent rewrite and commit the files, remove the legacy markers and run artifactize config check. Families are removed; use your own generator if you want templates and commit its .artf output. See Declarations (.artf).

The original 0.9 transition introduced state schema 6 and required replacing pre-schema-6 state. Current versions preserve existing schema-6 or schema-7 state by upgrading it automatically to schema 8, including Runs, cache records and Human approvals. Only schemas 1–5 require a new state: they are refused with exit 2, and artifactize doctor reports a hard error and exits 1. For those older states, set ARTIFACTIZE_STATE_HOME or --state-dir to a new directory, or move the old one away. Reuse-key v2 matches no pre-0.9 result, even in a team review store or with a script fingerprint. The first full verify reviews every eval once, Human sign-offs included. See Upgrading to 0.9.

Monitor now opens an eval’s Detail in its pane rather than a modal. Standalone Review shares that Human Detail: claims are explicit, and tools and submission never claim for you. The verdict forms, submit keys and editor shortcut changed; see Human reviews and Monitor for the current controls.

0.5.0 removes the chatgpt and claude Agent backends, with login chatgpt, logout chatgpt and the internal mcp command, and adds codex for ChatGPT plan users. config check names the replacements for each eval or profile variant that still declares a removed backend. artifactize no longer uses ChatGPT tokens saved by an earlier release: disconnect artifactize in ChatGPT Settings, then delete auth/chatgpt.json, auth/chatgpt-registration.json and auth/chatgpt.lock from the state directory.

State

All state, including Runs, saved Agent conversations and sign-ins, lives in one directory, by default ~/.local/state/artifactize (%LOCALAPPDATA%\artifactize on Windows). State lists its contents, the environment variables that move it and the Store version’s private copy.

--state-dir PATH moves the whole state for one command. Use the same value for login, verify, request, run and monitor. State must be outside the repository under review. Tokens under auth/ are also refused inside any git work tree or artifactize project, such as a dotfiles repository at $HOME or a gitignored folder in a checkout; ARTIFACTIZE_CODEX_AUTH_FILE needs no storage (State).

Backends

An Agent eval names exactly one backend and one exact model ID. There is no model catalog and no fallback to another backend or model.

A backend is the connection Artifactize uses to send an Agent review to a model service. An API key is that service’s secret account credential. For the API-key backends, create a key in your OpenAI account or Anthropic Console, then replace ... in the matching command with that key. Never commit it or put it in an Artifact declaration. Codex uses the separate browser sign-in below instead.

In PowerShell, set a key with $env:OPENAI_API_KEY = "...".

login codex signs in to your ChatGPT account the way the Codex CLI does. It prints a sign-in URL and opens it in the default browser (xdg-open on Linux and WSL, open on macOS, the default browser on Windows). Finish in a browser on the same machine: the browser returns to localhost:1455. On WSL 2, a Windows browser works too; copy the printed URL into it if nothing opens. Artifactize reserves both IPv4 and IPv6 loopback addresses (IPv4 only if the host has no IPv6). If another process, such as a Codex CLI or app sign-in, holds port 1455, artifactize skips its callback listener and asks for a pasted redirect instead. On another machine, use the same fallback. Paste the full URL starting http://localhost:1455/auth/callback?code= into the terminal, or the desktop sign-in’s paste field. Find it in the browser’s address bar after the failed load, or in DevTools → Network if the page keeps loading. logout codex revokes and deletes artifactize’s tokens. To use the tokens of an existing Codex sign-in instead, set ARTIFACTIZE_CODEX_AUTH_FILE=~/.codex/auth.json; artifactize only reads that file. See Codex.

artifactize doctor                 # state and its schema, API-key presence, Codex sign-in, review store
artifactize doctor --repo PROJECT  # also validates PROJECT's declarations

doctor calls no provider and creates no Run. Missing keys or sign-ins are warnings, because every backend is optional. It exits 1 only for hard errors such as unusable state or invalid configuration.

Cleanup and uninstall

artifactize prune --dry-run           # list removable scratch output of finished Runs
artifactize prune --older-than 7d     # remove it; saved results stay readable
artifactize logout codex              # if you signed in with Codex
artifactize remote logout             # if you signed in to a review store

Then remove the commands the way you installed them:

rm ~/.local/bin/artifactize ~/.local/bin/artifactize-tools   # install.sh (or your ARTIFACTIZE_INSTALL_DIR)
brew uninstall artifactize                                   # Homebrew
cargo uninstall artifactize artifactize-tools                # cargo install or cargo binstall

And the desktop app:

rm -rf ~/Applications/Artifactize.app                        # install.sh on macOS
rm -rf ~/.local/share/artifactize/desktop ~/.local/bin/artifactize-desktop \
  ~/.local/share/applications/artifactize.desktop             # install.sh on Linux
brew uninstall --cask artifactize                            # Homebrew cask, with its commands
sudo apt remove artifactize                                  # .deb

From a disk image, drag Artifactize from Applications to the Trash. If you approved first-launch command setup, also remove its terminal path entry:

sudo rm -f /etc/paths.d/artifactize

For an AppImage run on its own, delete the AppImage. Remove only the command links that point to the app’s stable copies, then remove those copies:

bin="${XDG_DATA_HOME:-$HOME/.local/share}/artifactize/bin"
for command in artifactize artifactize-tools; do
  link="$HOME/.local/bin/$command"
  [ "$(readlink "$link")" != "$bin/$command" ] || rm "$link"
done
rm -rf "$bin"

Open a new terminal after removing a command’s path entry.

On Windows:

winget uninstall lhj6102.Artifactize                       # future winget install, after publication
Remove-Item -Recurse "$env:LOCALAPPDATA\Programs\artifactize"   # install.ps1
Remove-Item "$([Environment]::GetFolderPath('Programs'))\Artifactize.lnk"   # its Start menu shortcut

Uninstall the Store version from Settings → Apps → Installed apps, or right-click Artifactize in the Start menu. After removing an install.ps1 install, also remove its directory from your user Path (search the Start menu for “Edit environment variables for your account”).

Uninstalling the Store app removes its package-private state, including Runs, saved results, sign-in and cache. Other install methods keep their state directory, so a later unpackaged install finds those Runs and results again. prune never touches active Runs, database rows or the repository. To remove retained unpackaged state, delete the state directory that artifactize doctor prints on its first line.

Uninstall does not remove your project files, exported files, or state explicitly placed outside AppData with --state-dir or an environment override. Files written by user-configured commands outside the package-private view can remain too; the Windows packaging test measured a Runtime child’s new AppData file in the real location. Remove those separately if you no longer need them. Existing unvirtualized AppData files are also outside the Store package’s cleanup; see the Windows behavior and overlay caveat.

Next, take the Quick start: a five-minute tour that needs no model.

Removed gate-bypass settings

review_policy and review_policy.dependency_gates are removed; even an empty policy table fails configuration validation as an unknown field. The old --ignore-gates CLI flag and VerifyOptions.ignore_gates library option are also removed. Choose speculation and deferred sign-offs per verification request instead; neither mode waives final approval obligations. Old saved keys are ignored on read, so removing the legacy policy needs no state migration.