🚀 Getting Started

Important

You do not need to install ACORN on your computer to use it in a CI job. If you only need to validate or publish a repository automatically, configure ACORN in CI using this example .gitlab-ci.yml. Use one of the options below when you want to run ACORN directly on your computer or in a container.

Installation

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	Homebrew or a pre-compiled binary	Use 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)

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)

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

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

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

Download pre-compiled binary

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

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