🚀 Getting started

Important

Local install is optional. If you only need automated validation or publishing, configure ACORN in CI with the example .gitlab-ci.yml. The sections below are for running ACORN directly on your workstation or in a container.

Installation

If you are running ACORN locally, choose one method from the table below. For background on the concepts behind these workflows, see Concepts.

Choose an installation method

User or environment	Recommended option	Best when…
CI pipeline	CI template	You only need automated validation or publishing; no local installation is required.
Windows workstation	Scoop	You want straightforward installation and upgrades.
macOS workstation	Homebrew	You want a managed installation; standalone macOS binaries are not available.
Linux workstation	AppImage, Debian package, Homebrew, or a pre-compiled binary	Use an AppImage without installation, a Debian package for system integration, Homebrew for managed upgrades, or the binary for minimal dependencies.
Rust developer	Cargo	Rust is already installed or you want a source-built executable.
Containerized environment	Docker or Podman	You want isolation, reproducibility, or a pinned ACORN version.
ACORN contributor	Install from source	You plan to modify, test, or debug ACORN itself.

Install with Scoop (Windows only)

Use this if you are on Windows and want straightforward scoop update upgrades.

Ensure you have Scoop installed.
Open your terminal and add the extras bucket to Scoop
```
scoop bucket add extras
```
Run the following command to install ACORN
```
scoop install acorn
```
After installation, you can verify the installation by running:
```
acorn help
```
You can keep ACORN up to date with Scoop by running:
```
scoop update acorn
```

Install with Homebrew (Linux and macOS)

Use this if you are on macOS or Linux and want a managed install via brew.

Add the custom tap:

brew tap research-enablement/acorn https://code.ornl.gov/research-enablement/homebrew-acorn.git/

Trust the custom tap:
```
brew trust research-enablement/acorn
```
Install ACORN:
```
brew install acorn-cli
```
Verify installation:
```
acorn help
```
Upgrade to the latest version:
```
brew update
brew upgrade acorn-cli
```

Install with Cargo

Use this if you already have Rust and Cargo or want a source-built binary.

Ensure you have Rust and Cargo installed. If not, you can install them using rustup.rs.
Open your terminal and run the following command to install ACORN
```
cargo install --locked acorn-cli
```
After installation, you can verify the installation by running:
```
acorn help
```

Run inside a container

Use this if you want isolation or a pinned version without a local install.

Ensure you have Docker¹ installed.

Pull the latest ACORN image with Docker¹

docker pull savannah.ornl.gov/research-enablement/acorn/runner

Run ACORN using Docker¹

docker run --rm savannah.ornl.gov/research-enablement/acorn/runner help

Tip

You will probably need to mount a volume to use ACORN with your local files. For example:
docker run --rm -v $(pwd):/data savannah.ornl.gov/research-enablement/acorn/runner:latest check /data/project

Run the AppImage (Linux)

Use this if you want one portable file with both the command-line and terminal interfaces.

Download the AppImage for your architecture from the ACORN GitLab Releases page:
- x86_64: acorn-v<version>-x86_64.AppImage
- ARM64: acorn-v<version>-aarch64.AppImage

Download its adjacent .sha256 file and verify it before running:

sha256sum -c acorn-v<version>-<architecture>.AppImage.sha256
chmod +x acorn-v<version>-<architecture>.AppImage

Launch without arguments to open the terminal interface, or pass any ordinary ACORN arguments:

./acorn-v<version>-<architecture>.AppImage
./acorn-v<version>-<architecture>.AppImage check /path/to/project

Install the Debian package (Linux)

Use this on Debian, Ubuntu, or a compatible distribution when you want /usr/bin/acorn managed by the system package database.

Download the package and its .sha256 file from the ACORN GitLab Releases page:
- amd64: acorn_<version>-1_amd64.deb
- ARM64: acorn_<version>-1_arm64.deb

Verify and install the local package:

sha256sum -c acorn_<version>-1_<architecture>.deb.sha256
sudo apt install ./acorn_<version>-1_<architecture>.deb
acorn --version

The downloaded filename begins with acorn_; the package database records it as acorn-cli, and the installed command is acorn. These direct downloads do not configure an APT repository or automatic updates.

Debian’s unrelated node-acorn package installs a command with the same name. The ACORN package declares that conflict, so APT may remove node-acorn when installing acorn-cli.

Download pre-compiled binary

Use this if you want a single binary with minimal dependencies.

Download the latest release from the ACORN GitLab Releases page
- 🪟 Windows
  - Open a PowerShell terminal, visit the releases page to find the latest version, and run:
```
irm -OutFile acorn.exe -Uri https://code.ornl.gov/api/v4/projects/16689/packages/generic/x86_64-pc-windows-gnu/v<version>/acorn.exe
```
  - Test the downloaded executable:
```
.\acorn.exe help
```
- 🐧 Linux
  - Open a terminal, visit the releases page to find the latest version, and run:
```
curl -LO https://code.ornl.gov/api/v4/projects/16689/packages/generic/x86_64-unknown-linux-musl/v<version>/acorn
```
  - Make the downloaded file executable:
```
chmod +x acorn
```
  - Test the downloaded executable:
```
acorn help
```
- 🍎 macOS
  - Standalone macOS binaries are not currently published. Use the Homebrew, Cargo, or source installation above.

Install from source

Use this if you are contributing to ACORN itself.

Clone the ACORN repository

git clone https://code.ornl.gov/research-enablement/acorn.git
cd acorn

Install acorn command

cargo install --locked --path ./crates/acorn-cli

After installation, you can verify the installation by running:
```
acorn help
```

These instructions will work with any OCI-compliant container runtime, such as Docker or Podman. ↩ ↩2 ↩3

Keyboard shortcuts

🌱 Plant an acorn, grow your science