Backup Before You Update
Prior to updating ARI, it is always advised to first take a full backup of your files and database. Before updating, save a copy of:
- Your database. Use Settings → Backups in ARI. See Backup & Restore.
- Your
modules-custom/andthemes-custom/folders. - Your
.env.localfile. - Any uploaded files in the
data/folder.
What an Update Changes
An update replaces ARI's own files with the new release. Everything that belongs to you is left alone.
| What | Where it lives | After an update |
|---|---|---|
| ARI itself and built-in modules | core files, modules-core/ | Replaced with the new release |
| Built-in themes | themes-core/ | Replaced with the new release |
| Your modules | modules-custom/ | Untouched |
| Your themes | themes-custom/ | Untouched |
| Your settings | .env.local | Untouched |
| Your data | your database, data/ | Kept. The database is updated automatically the next time ARI starts. |
The one rule to remember: do not edit files inside modules-core/ or themes-core/. Changes made there are replaced by the next update. To change a built-in module, see Changing a Built-In Module below.
How to Update
Pick whichever suits you. All three end in the same place.
Option 1: The ARI Command
Change into your ARI folder (cd ~/ARI, or wherever you installed ARI) and run the command for your system.
On macOS and Linux:
./ari update
On Windows, in PowerShell:
.\ari.cmd update
You will see the version you are moving from and to, a list of what changed, and a question asking whether to go ahead. Nothing is changed until you say yes. ARI then installs anything new the release needs. Run ./ari start afterward to launch, or .\ari.cmd start on Windows.
The rest of this page writes commands as ./ari. On Windows, use .\ari.cmd in its place. The commands and options are the same.
Option 2: Ask Claude
Claude can walk you through the update process. In Claude type this command:
/ari-update
Claude then:
- Finds the latest release, or the version you ask for
- Shows you what's new before changing anything
- Updates after your confirmation
- Takes care of the follow-up: installs new dependencies, refreshes the module list, and tells you about any new settings the release needs so you can add them
It also notices unsaved changes before it starts. If the update stops on a conflict, it lists the files involved so you can resolve them. See Commands for more details.
Option 3: Git by Hand
If you prefer to run Git yourself, replace 2.0.8 with the release you want:
git fetch upstream
git merge 2.0.8
pnpm install
If Git reports that upstream does not exist, add it once with git remote add upstream https://github.com/ARIsoftware/ARI.git and run the commands again. Then restart with ./ari start.
To try the newest work in progress instead of a release, run git pull upstream main in place of the first two commands.
Choosing a Version
ARI is published as numbered releases, such as 2.0.8. You can see them all on the ARI releases page. Your own version is shown at the bottom of the ARI sidebar.
When you start ARI, it will let you know if a newer release is available:
↑ ARI 2.0.8 available (you have 2.0.7) — run ./ari update
Most people only ever need the first command below.
| Command | What it does | When to use it |
|---|---|---|
./ari update | Updates to the latest release | Almost always |
./ari update 2.0.8 | Updates to the release you name | You want a particular release, not the newest one |
./ari update --edge | Updates to the newest work in progress | You want to try changes before they are released |
Changing a Built-In Module
You can change any built-in module and still update freely. Copy its folder from modules-core/ into modules-custom/, keeping the same name, and make your changes in the copy. ARI uses your copy in place of the original, and updates never touch it.
See Customizing Modules for the full steps. Themes work the same way, using themes-core/ and themes-custom/; see Themes.
Common Questions
What ARI version am I running?
Run ./ari update. It shows the version you have before it changes anything, and you can answer no to leave ARI as it is.
The version is also listed at the top of the Health page in ARI, at http://localhost:3000/health.
It says I already have the latest release "plus newer commits"
Nothing is wrong. Your copy of ARI already includes everything in the latest release, and some newer changes as well. This is normal if you installed ARI before numbered releases existed, or if you used --edge. There is nothing to do. You will move onto the next release when it comes out.
Can I go back to an older version?
No. ARI only updates forward, and if you ask for an older release it declines and changes nothing. The reason is your database: it is updated along with ARI and cannot be moved back, so an older ARI is not supported with a newer database.
If an update causes a problem, please report it so it can be fixed in the next release.
The update stopped and mentioned conflicts
This means a file you changed was also changed in the new release, and ARI will not guess which version you want. It lists the files involved. Open each one, keep the parts you want, then run:
git add <file>
git commit
Conflicts are rare when your changes live in modules-custom/ and themes-custom/. If you would like help, Claude Code can walk you through them, or see Support.
It warned me about uncommitted changes
You have edited one of ARI's own files and not saved the change in Git. You can continue, but it is safer to save your work first so nothing is lost if there is a conflict:
git commit -am "My changes"
My first update went further than the latest release
The first update from an older copy of ARI is carried out by the version you already had, which predates numbered releases and takes the newest work in progress. Every update after that follows releases.
Something looks wrong after updating
Run ./ari doctor for a diagnostic report, and open the Health Check page in ARI. Both point to the most common problems quickly.